[libsigrok.git] / src / backend.c

/*
 * This file is part of the libsigrok project.
 *
 * Copyright (C) 2010-2012 Bert Vermeulen <bert@biot.com>
 * Copyright (C) 2012 Peter Stuge <peter@stuge.se>
 *
 * 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 <config.h>
#include <glib.h>
#ifdef _WIN32
#include <winsock2.h>
#endif
#include <libsigrok/libsigrok.h>
#include "libsigrok-internal.h"
#include "minilzo/minilzo.h"

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

/**
 * @mainpage libsigrok API
 *
 * @section sec_intro Introduction
 *
 * The <a href="http://sigrok.org">sigrok</a> project aims at creating a
 * portable, cross-platform, Free/Libre/Open-Source signal analysis software
 * suite that supports various device types (such as logic analyzers,
 * oscilloscopes, multimeters, and more).
 *
 * <a href="http://sigrok.org/wiki/Libsigrok">libsigrok</a> is a shared
 * library written in C which provides the basic API for talking to
 * <a href="http://sigrok.org/wiki/Supported_hardware">supported hardware</a>
 * and reading/writing the acquired data into various
 * <a href="http://sigrok.org/wiki/Input_output_formats">input/output
 * file formats</a>.
 *
 * @section sec_api API reference
 *
 * See the "Modules" page for an introduction to various libsigrok
 * related topics and the detailed API documentation of the respective
 * functions.
 *
 * You can also browse the API documentation by file, or review all
 * data structures.
 *
 * @section sec_mailinglists Mailing lists
 *
 * There is one mailing list for sigrok/libsigrok: <a href="https://lists.sourceforge.net/lists/listinfo/sigrok-devel">sigrok-devel</a>.
 *
 * @section sec_irc IRC
 *
 * You can find the sigrok developers in the
 * <a href="ircs://irc.libera.chat/#sigrok">\#sigrok</a>
 * IRC channel on Libera.Chat.
 *
 * @section sec_website Website
 *
 * <a href="http://sigrok.org/wiki/Libsigrok">sigrok.org/wiki/Libsigrok</a>
 */

/**
 * @file
 *
 * Initializing and shutting down libsigrok.
 */

/**
 * @defgroup grp_init Initialization
 *
 * Initializing and shutting down libsigrok.
 *
 * Before using any of the libsigrok functionality (except for
 * sr_log_loglevel_set()), sr_init() must be called to initialize the
 * library, which will return a struct sr_context when the initialization
 * was successful.
 *
 * When libsigrok functionality is no longer needed, sr_exit() should be
 * called, which will (among other things) free the struct sr_context.
 *
 * Example for a minimal program using libsigrok:
 *
 * @code{.c}
 *   #include <stdio.h>
 *   #include <libsigrok/libsigrok.h>
 *
 *   int main(int argc, char **argv)
 *   {
 *   	int ret;
 *   	struct sr_context *sr_ctx;
 *
 *   	if ((ret = sr_init(&sr_ctx)) != SR_OK) {
 *   		printf("Error initializing libsigrok (%s): %s.\n",
 *   		       sr_strerror_name(ret), sr_strerror(ret));
 *   		return 1;
 *   	}
 *
 *   	// Use libsigrok functions here...
 *
 *   	if ((ret = sr_exit(sr_ctx)) != SR_OK) {
 *   		printf("Error shutting down libsigrok (%s): %s.\n",
 *   		       sr_strerror_name(ret), sr_strerror(ret));
 *   		return 1;
 *   	}
 *
 *   	return 0;
 *   }
 * @endcode
 *
 * @{
 */

SR_API GSList *sr_buildinfo_libs_get(void)
{
	GSList *l = NULL, *m = NULL;
#if defined(HAVE_LIBUSB_1_0) && !defined(__FreeBSD__)
	const struct libusb_version *lv;
#endif

	m = g_slist_append(NULL, g_strdup("glib"));
	m = g_slist_append(m, g_strdup_printf("%d.%d.%d (rt: %d.%d.%d/%d:%d)",
		GLIB_MAJOR_VERSION, GLIB_MINOR_VERSION, GLIB_MICRO_VERSION,
		glib_major_version, glib_minor_version, glib_micro_version,
		glib_binary_age, glib_interface_age));
	l = g_slist_append(l, m);

	m = g_slist_append(NULL, g_strdup("libzip"));
	m = g_slist_append(m, g_strdup_printf("%s", CONF_LIBZIP_VERSION));
	l = g_slist_append(l, m);

	m = g_slist_append(NULL, g_strdup("minilzo"));
	m = g_slist_append(m, g_strdup_printf("%s", lzo_version_string()));
	l = g_slist_append(l, m);

#ifdef HAVE_LIBSERIALPORT
	m = g_slist_append(NULL, g_strdup("libserialport"));
	m = g_slist_append(m, g_strdup_printf("%s/%s (rt: %s/%s)",
		SP_PACKAGE_VERSION_STRING, SP_LIB_VERSION_STRING,
		sp_get_package_version_string(), sp_get_lib_version_string()));
	l = g_slist_append(l, m);
#endif
#ifdef HAVE_LIBUSB_1_0
	m = g_slist_append(NULL, g_strdup("libusb-1.0"));
#ifdef __FreeBSD__
	m = g_slist_append(m, g_strdup_printf("%s", CONF_LIBUSB_1_0_VERSION));
#else
	lv = libusb_get_version();
	m = g_slist_append(m, g_strdup_printf("%d.%d.%d.%d%s API 0x%08x",
		lv->major, lv->minor, lv->micro, lv->nano, lv->rc,
#if defined(LIBUSB_API_VERSION)
		LIBUSB_API_VERSION
#elif defined(LIBUSBX_API_VERSION)
		LIBUSBX_API_VERSION
#endif
		));
#endif
	l = g_slist_append(l, m);
#endif
#ifdef HAVE_LIBHIDAPI
	m = g_slist_append(NULL, g_strdup("hidapi"));
	m = g_slist_append(m, g_strdup_printf("%s", CONF_LIBHIDAPI_VERSION));
	l = g_slist_append(l, m);
#endif
#ifdef HAVE_LIBBLUEZ
	m = g_slist_append(NULL, g_strdup("bluez"));
	m = g_slist_append(m, g_strdup_printf("%s", CONF_LIBBLUEZ_VERSION));
	l = g_slist_append(l, m);
#endif
#ifdef HAVE_LIBFTDI
	m = g_slist_append(NULL, g_strdup("libftdi"));
	m = g_slist_append(m, g_strdup_printf("%s", CONF_LIBFTDI_VERSION));
	l = g_slist_append(l, m);
#endif
#ifdef HAVE_LIBGPIB
	m = g_slist_append(NULL, g_strdup("libgpib"));
	m = g_slist_append(m, g_strdup_printf("%s", CONF_LIBGPIB_VERSION));
	l = g_slist_append(l, m);
#endif
#ifdef HAVE_LIBREVISA
	m = g_slist_append(NULL, g_strdup("librevisa"));
	m = g_slist_append(m, g_strdup_printf("%s", CONF_LIBREVISA_VERSION));
	l = g_slist_append(l, m);
#endif

	return l;
}

SR_API char *sr_buildinfo_host_get(void)
{
	return g_strdup_printf("%s, %s-endian", CONF_HOST,
#ifdef WORDS_BIGENDIAN
	"big"
#else
	"little"
#endif
	);
}

SR_API char *sr_buildinfo_scpi_backends_get(void)
{
	GString *s;
	char *str;

	s = g_string_sized_new(200);

	g_string_append_printf(s, "TCP, ");
#if HAVE_RPC
	g_string_append_printf(s, "RPC, ");
#endif
#ifdef HAVE_SERIAL_COMM
	g_string_append_printf(s, "serial, ");
#endif
#ifdef HAVE_LIBREVISA
	g_string_append_printf(s, "VISA, ");
#endif
#ifdef HAVE_LIBGPIB
	g_string_append_printf(s, "GPIB, ");
#endif
#ifdef HAVE_LIBUSB_1_0
	g_string_append_printf(s, "USBTMC, ");
#endif
	s->str[s->len - 2] = '\0';

	str = g_strdup(s->str);
	g_string_free(s, TRUE);

	return str;
}

static void print_versions(void)
{
	GString *s;
	GSList *l, *l_orig, *m;
	char *str;
	const char *lib, *version;

	sr_dbg("libsigrok %s/%s.",
		sr_package_version_string_get(), sr_lib_version_string_get());

	s = g_string_sized_new(200);
	g_string_append(s, "Libs: ");
	l_orig = sr_buildinfo_libs_get();
	for (l = l_orig; l; l = l->next) {
		m = l->data;
		lib = m->data;
		version = m->next->data;
		g_string_append_printf(s, "%s %s, ", lib, version);
		g_slist_free_full(m, g_free);
	}
	g_slist_free(l_orig);
	s->str[s->len - 2] = '.';
	s->str[s->len - 1] = '\0';
	sr_dbg("%s", s->str);
	g_string_free(s, TRUE);

	str = sr_buildinfo_host_get();
	sr_dbg("Host: %s.", str);
	g_free(str);

	str = sr_buildinfo_scpi_backends_get();
	sr_dbg("SCPI backends: %s.", str);
	g_free(str);
}

static void print_resourcepaths(void)
{
	GSList *l, *l_orig;

	sr_dbg("Firmware search paths:");
	l_orig = sr_resourcepaths_get(SR_RESOURCE_FIRMWARE);
	for (l = l_orig; l; l = l->next)
		sr_dbg(" - %s", (const char *)l->data);
	g_slist_free_full(l_orig, g_free);
}

/**
 * Sanity-check all libsigrok drivers.
 *
 * @param[in] ctx Pointer to a libsigrok context struct. Must not be NULL.
 *
 * @retval SR_OK All drivers are OK
 * @retval SR_ERR One or more drivers have issues.
 * @retval SR_ERR_ARG Invalid argument.
 */
static int sanity_check_all_drivers(const struct sr_context *ctx)
{
	int i, errors, ret = SR_OK;
	struct sr_dev_driver **drivers;
	const char *d;

	if (!ctx)
		return SR_ERR_ARG;

	sr_spew("Sanity-checking all drivers.");

	drivers = sr_driver_list(ctx);
	for (i = 0; drivers[i]; i++) {
		errors = 0;

		d = (drivers[i]->name) ? drivers[i]->name : "NULL";

		if (!drivers[i]->name) {
			sr_err("No name in driver %d ('%s').", i, d);
			errors++;
		}
		if (!drivers[i]->longname) {
			sr_err("No longname in driver %d ('%s').", i, d);
			errors++;
		}
		if (drivers[i]->api_version < 1) {
			sr_err("API version in driver %d ('%s') < 1.", i, d);
			errors++;
		}
		if (!drivers[i]->init) {
			sr_err("No init in driver %d ('%s').", i, d);
			errors++;
		}
		if (!drivers[i]->cleanup) {
			sr_err("No cleanup in driver %d ('%s').", i, d);
			errors++;
		}
		if (!drivers[i]->scan) {
			sr_err("No scan in driver %d ('%s').", i, d);
			errors++;
		}
		if (!drivers[i]->dev_list) {
			sr_err("No dev_list in driver %d ('%s').", i, d);
			errors++;
		}
		if (!drivers[i]->dev_clear) {
			sr_err("No dev_clear in driver %d ('%s').", i, d);
			errors++;
		}
		/* Note: config_get() is optional. */
		if (!drivers[i]->config_set) {
			sr_err("No config_set in driver %d ('%s').", i, d);
			errors++;
		}
		/* Note: config_channel_set() is optional. */
		/* Note: config_commit() is optional. */
		if (!drivers[i]->config_list) {
			sr_err("No config_list in driver %d ('%s').", i, d);
			errors++;
		}
		if (!drivers[i]->dev_open) {
			sr_err("No dev_open in driver %d ('%s').", i, d);
			errors++;
		}
		if (!drivers[i]->dev_close) {
			sr_err("No dev_close in driver %d ('%s').", i, d);
			errors++;
		}
		if (!drivers[i]->dev_acquisition_start) {
			sr_err("No dev_acquisition_start in driver %d ('%s').",
			       i, d);
			errors++;
		}
		if (!drivers[i]->dev_acquisition_stop) {
			sr_err("No dev_acquisition_stop in driver %d ('%s').",
			       i, d);
			errors++;
		}

		/* Note: 'priv' is allowed to be NULL. */

		if (errors == 0)
			continue;

		ret = SR_ERR;
	}

	return ret;
}

/**
 * Sanity-check all libsigrok input modules.
 *
 * @retval SR_OK All modules are OK
 * @retval SR_ERR One or more modules have issues.
 */
static int sanity_check_all_input_modules(void)
{
	int i, errors, ret = SR_OK;
	const struct sr_input_module **inputs;
	const char *d;

	sr_spew("Sanity-checking all input modules.");

	inputs = sr_input_list();
	for (i = 0; inputs[i]; i++) {
		errors = 0;

		d = (inputs[i]->id) ? inputs[i]->id : "NULL";

		if (!inputs[i]->id) {
			sr_err("No ID in module %d ('%s').", i, d);
			errors++;
		}
		if (!inputs[i]->name) {
			sr_err("No name in module %d ('%s').", i, d);
			errors++;
		}
		if (!inputs[i]->desc) {
			sr_err("No description in module %d ('%s').", i, d);
			errors++;
		}
		if (!inputs[i]->init) {
			sr_err("No init in module %d ('%s').", i, d);
			errors++;
		}
		if (!inputs[i]->receive) {
			sr_err("No receive in module %d ('%s').", i, d);
			errors++;
		}
		if (!inputs[i]->end) {
			sr_err("No end in module %d ('%s').", i, d);
			errors++;
		}

		if (errors == 0)
			continue;

		ret = SR_ERR;
	}

	return ret;
}

/**
 * Sanity-check all libsigrok output modules.
 *
 * @retval SR_OK All modules are OK
 * @retval SR_ERR One or more modules have issues.
 */
static int sanity_check_all_output_modules(void)
{
	int i, errors, ret = SR_OK;
	const struct sr_output_module **outputs;
	const char *d;

	sr_spew("Sanity-checking all output modules.");

	outputs = sr_output_list();
	for (i = 0; outputs[i]; i++) {
		errors = 0;

		d = (outputs[i]->id) ? outputs[i]->id : "NULL";

		if (!outputs[i]->id) {
			sr_err("No ID in module %d ('%s').", i, d);
			errors++;
		}
		if (!outputs[i]->name) {
			sr_err("No name in module %d ('%s').", i, d);
			errors++;
		}
		if (!outputs[i]->desc) {
			sr_err("No description in module '%s'.", d);
			errors++;
		}
		if (!outputs[i]->receive) {
			sr_err("No receive in module '%s'.", d);
			errors++;
		}

		if (errors == 0)
			continue;

		ret = SR_ERR;
	}

	return ret;
}

/**
 * Sanity-check all libsigrok transform modules.
 *
 * @retval SR_OK All modules are OK
 * @retval SR_ERR One or more modules have issues.
 */
static int sanity_check_all_transform_modules(void)
{
	int i, errors, ret = SR_OK;
	const struct sr_transform_module **transforms;
	const char *d;

	sr_spew("Sanity-checking all transform modules.");

	transforms = sr_transform_list();
	for (i = 0; transforms[i]; i++) {
		errors = 0;

		d = (transforms[i]->id) ? transforms[i]->id : "NULL";

		if (!transforms[i]->id) {
			sr_err("No ID in module %d ('%s').", i, d);
			errors++;
		}
		if (!transforms[i]->name) {
			sr_err("No name in module %d ('%s').", i, d);
			errors++;
		}
		if (!transforms[i]->desc) {
			sr_err("No description in module '%s'.", d);
			errors++;
		}
		/* Note: options() is optional. */
		/* Note: init() is optional. */
		if (!transforms[i]->receive) {
			sr_err("No receive in module '%s'.", d);
			errors++;
		}
		/* Note: cleanup() is optional. */

		if (errors == 0)
			continue;

		ret = SR_ERR;
	}

	return ret;
}

/**
 * Initialize libsigrok.
 *
 * This function must be called before any other libsigrok function.
 *
 * @param ctx Pointer to a libsigrok context struct pointer. Must not be NULL.
 *            This will be a pointer to a newly allocated libsigrok context
 *            object upon success, and is undefined upon errors.
 *
 * @return SR_OK upon success, a (negative) error code otherwise. Upon errors
 *         the 'ctx' pointer is undefined and should not be used. Upon success,
 *         the context will be free'd by sr_exit() as part of the libsigrok
 *         shutdown.
 *
 * @since 0.2.0
 */
SR_API int sr_init(struct sr_context **ctx)
{
	int ret = SR_ERR;
	struct sr_context *context;
#ifdef _WIN32
	WSADATA wsadata;
#endif

	print_versions();

	print_resourcepaths();

	if (!ctx) {
		sr_err("%s(): libsigrok context was NULL.", __func__);
		return SR_ERR;
	}

	context = g_malloc0(sizeof(struct sr_context));

	sr_drivers_init(context);

	if (sanity_check_all_drivers(context) < 0) {
		sr_err("Internal driver error(s), aborting.");
		goto done;
	}

	if (sanity_check_all_input_modules() < 0) {
		sr_err("Internal input module error(s), aborting.");
		goto done;
	}

	if (sanity_check_all_output_modules() < 0) {
		sr_err("Internal output module error(s), aborting.");
		goto done;
	}

	if (sanity_check_all_transform_modules() < 0) {
		sr_err("Internal transform module error(s), aborting.");
		goto done;
	}

#ifdef _WIN32
	if ((ret = WSAStartup(MAKEWORD(2, 2), &wsadata)) != 0) {
		sr_err("WSAStartup failed with error code %d.", ret);
		ret = SR_ERR;
		goto done;
	}
#endif

	if ((ret = lzo_init()) != LZO_E_OK) {
		sr_err("lzo_init() failed with return code %d.", ret);
		sr_err("This usually indicates a compiler bug. Recompile without");
		sr_err("optimizations, and enable '-DLZO_DEBUG' for diagnostics.");
		ret = SR_ERR;
		goto done;
	}

#ifdef HAVE_LIBUSB_1_0
	ret = libusb_init(&context->libusb_ctx);
	if (LIBUSB_SUCCESS != ret) {
		sr_err("libusb_init() returned %s.", libusb_error_name(ret));
		ret = SR_ERR;
		goto done;
	}
#endif
#ifdef HAVE_LIBHIDAPI
	/*
	 * According to <hidapi.h>, the hid_init() routine just returns
	 * zero or non-zero, and hid_error() appears to relate to calls
	 * for a specific device after hid_open(). Which means that there
	 * is no more detailled information available beyond success/fail
	 * at this point in time.
	 */
	if (hid_init() != 0) {
		sr_err("HIDAPI hid_init() failed.");
		ret = SR_ERR;
		goto done;
	}
#endif
	sr_resource_set_hooks(context, NULL, NULL, NULL, NULL);

	*ctx = context;
	context = NULL;
	ret = SR_OK;

done:
	g_free(context);
	return ret;
}

/**
 * Shutdown libsigrok.
 *
 * @param ctx Pointer to a libsigrok context struct. Must not be NULL.
 *
 * @retval SR_OK Success
 * @retval other Error code SR_ERR, ...
 *
 * @since 0.2.0
 */
SR_API int sr_exit(struct sr_context *ctx)
{
	if (!ctx) {
		sr_err("%s(): libsigrok context was NULL.", __func__);
		return SR_ERR;
	}

	sr_hw_cleanup_all(ctx);

#ifdef _WIN32
	WSACleanup();
#endif

#ifdef HAVE_LIBHIDAPI
	hid_exit();
#endif
#ifdef HAVE_LIBUSB_1_0
	libusb_exit(ctx->libusb_ctx);
#endif

	g_free(sr_driver_list(ctx));
	g_free(ctx);

	return SR_OK;
}

/** @} */
Commit	Line	Data
a1bb33af	1	/*
50985c20	2	* This file is part of the libsigrok project.
a1bb33af	3	*
c73d2ea4	4	* Copyright (C) 2010-2012 Bert Vermeulen <bert@biot.com>
b8072700	5	* Copyright (C) 2012 Peter Stuge <peter@stuge.se>
a1bb33af UH	6	*
	7	* This program is free software: you can redistribute it and/or modify
	8	* it under the terms of the GNU General Public License as published by
	9	* the Free Software Foundation, either version 3 of the License, or
	10	* (at your option) any later version.
	11	*
	12	* This program is distributed in the hope that it will be useful,
	13	* but WITHOUT ANY WARRANTY; without even the implied warranty of
	14	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
	15	* GNU General Public License for more details.
	16	*
	17	* You should have received a copy of the GNU General Public License
	18	* along with this program. If not, see <http://www.gnu.org/licenses/>.
	19	*/
	20
6ec6c43b	21	#include <config.h>
a1bb33af	22	#include <glib.h>
6954fdbc UH	23	#ifdef _WIN32
	24	#include <winsock2.h>
	25	#endif
c1aae900	26	#include <libsigrok/libsigrok.h>
45c59c8b	27	#include "libsigrok-internal.h"
b9cd0c6a	28	#include "minilzo/minilzo.h"
a1bb33af	29
2ad1deb8	30	/** @cond PRIVATE */
3544f848	31	#define LOG_PREFIX "backend"
2ad1deb8	32	/** @endcond */
3544f848	33
5b30cca7 UH	34	/**
	35	* @mainpage libsigrok API
	36	*
	37	* @section sec_intro Introduction
	38	*
	39	* The <a href="http://sigrok.org">sigrok</a> project aims at creating a
	40	* portable, cross-platform, Free/Libre/Open-Source signal analysis software
	41	* suite that supports various device types (such as logic analyzers,
	42	* oscilloscopes, multimeters, and more).
	43	*
	44	* <a href="http://sigrok.org/wiki/Libsigrok">libsigrok</a> is a shared
	45	* library written in C which provides the basic API for talking to
	46	* <a href="http://sigrok.org/wiki/Supported_hardware">supported hardware</a>
	47	* and reading/writing the acquired data into various
	48	* <a href="http://sigrok.org/wiki/Input_output_formats">input/output
	49	* file formats</a>.
	50	*
f21193fa	51	* @section sec_api API reference
5b30cca7	52	*
f21193fa UH	53	* See the "Modules" page for an introduction to various libsigrok
	54	* related topics and the detailed API documentation of the respective
	55	* functions.
	56	*
	57	* You can also browse the API documentation by file, or review all
	58	* data structures.
5b30cca7 UH	59	*
	60	* @section sec_mailinglists Mailing lists
	61	*
b88c3e49	62	* There is one mailing list for sigrok/libsigrok: <a href="https://lists.sourceforge.net/lists/listinfo/sigrok-devel">sigrok-devel</a>.
5b30cca7 UH	63	*
	64	* @section sec_irc IRC
	65	*
	66	* You can find the sigrok developers in the
1e91a90f GS	67	* <a href="ircs://irc.libera.chat/#sigrok">\#sigrok</a>
1e91a90f GS	68	* IRC channel on Libera.Chat.
5b30cca7 UH	69	*
	70	* @section sec_website Website
	71	*
	72	* <a href="http://sigrok.org/wiki/Libsigrok">sigrok.org/wiki/Libsigrok</a>
	73	*/
	74
393fb9cb UH	75	/**
	76	* @file
	77	*
	78	* Initializing and shutting down libsigrok.
	79	*/
	80
7b870c38 UH	81	/**
	82	* @defgroup grp_init Initialization
	83	*
	84	* Initializing and shutting down libsigrok.
	85	*
ad0293f1 UH	86	* Before using any of the libsigrok functionality (except for
	87	* sr_log_loglevel_set()), sr_init() must be called to initialize the
	88	* library, which will return a struct sr_context when the initialization
	89	* was successful.
afe2f28e UH	90	*
	91	* When libsigrok functionality is no longer needed, sr_exit() should be
	92	* called, which will (among other things) free the struct sr_context.
	93	*
	94	* Example for a minimal program using libsigrok:
	95	*
	96	* @code{.c}
	97	* #include <stdio.h>
	98	* #include <libsigrok/libsigrok.h>
	99	*
	100	* int main(int argc, char **argv)
	101	* {
	102	* int ret;
	103	* struct sr_context *sr_ctx;
	104	*
	105	* if ((ret = sr_init(&sr_ctx)) != SR_OK) {
df823ac4	106	* printf("Error initializing libsigrok (%s): %s.\n",
afe2f28e UH	107	* sr_strerror_name(ret), sr_strerror(ret));
	108	* return 1;
	109	* }
	110	*
	111	* // Use libsigrok functions here...
	112	*
	113	* if ((ret = sr_exit(sr_ctx)) != SR_OK) {
df823ac4	114	* printf("Error shutting down libsigrok (%s): %s.\n",
afe2f28e UH	115	* sr_strerror_name(ret), sr_strerror(ret));
	116	* return 1;
	117	* }
	118	*
	119	* return 0;
	120	* }
	121	* @endcode
	122	*
7b870c38 UH	123	* @{
	124	*/
	125
42be2adb	126	SR_API GSList *sr_buildinfo_libs_get(void)
bd7b83cf	127	{
42be2adb	128	GSList l = NULL, m = NULL;
731c01f2	129	#if defined(HAVE_LIBUSB_1_0) && !defined(__FreeBSD__)
bd7b83cf UH	130	const struct libusb_version *lv;
	131	#endif
	132
42be2adb UH	133	m = g_slist_append(NULL, g_strdup("glib"));
42be2adb UH	134	m = g_slist_append(m, g_strdup_printf("%d.%d.%d (rt: %d.%d.%d/%d:%d)",
bd7b83cf UH	135	GLIB_MAJOR_VERSION, GLIB_MINOR_VERSION, GLIB_MICRO_VERSION,
bd7b83cf UH	136	glib_major_version, glib_minor_version, glib_micro_version,
42be2adb UH	137	glib_binary_age, glib_interface_age));
	138	l = g_slist_append(l, m);
	139
	140	m = g_slist_append(NULL, g_strdup("libzip"));
	141	m = g_slist_append(m, g_strdup_printf("%s", CONF_LIBZIP_VERSION));
	142	l = g_slist_append(l, m);
	143
b9cd0c6a GS	144	m = g_slist_append(NULL, g_strdup("minilzo"));
	145	m = g_slist_append(m, g_strdup_printf("%s", lzo_version_string()));
	146	l = g_slist_append(l, m);
	147
bd7b83cf	148	#ifdef HAVE_LIBSERIALPORT
42be2adb UH	149	m = g_slist_append(NULL, g_strdup("libserialport"));
42be2adb UH	150	m = g_slist_append(m, g_strdup_printf("%s/%s (rt: %s/%s)",
bd7b83cf	151	SP_PACKAGE_VERSION_STRING, SP_LIB_VERSION_STRING,
42be2adb UH	152	sp_get_package_version_string(), sp_get_lib_version_string()));
42be2adb UH	153	l = g_slist_append(l, m);
bd7b83cf UH	154	#endif
bd7b83cf UH	155	#ifdef HAVE_LIBUSB_1_0
42be2adb	156	m = g_slist_append(NULL, g_strdup("libusb-1.0"));
731c01f2	157	#ifdef __FreeBSD__
42be2adb	158	m = g_slist_append(m, g_strdup_printf("%s", CONF_LIBUSB_1_0_VERSION));
731c01f2	159	#else
bd7b83cf	160	lv = libusb_get_version();
e6104296 UH	161	m = g_slist_append(m, g_strdup_printf("%d.%d.%d.%d%s API 0x%08x",
e6104296 UH	162	lv->major, lv->minor, lv->micro, lv->nano, lv->rc,
17e0251d UH	163	#if defined(LIBUSB_API_VERSION)
	164	LIBUSB_API_VERSION
	165	#elif defined(LIBUSBX_API_VERSION)
	166	LIBUSBX_API_VERSION
	167	#endif
	168	));
bd7b83cf	169	#endif
42be2adb	170	l = g_slist_append(l, m);
731c01f2	171	#endif
4417074c GS	172	#ifdef HAVE_LIBHIDAPI
	173	m = g_slist_append(NULL, g_strdup("hidapi"));
	174	m = g_slist_append(m, g_strdup_printf("%s", CONF_LIBHIDAPI_VERSION));
	175	l = g_slist_append(l, m);
	176	#endif
f085705f GS	177	#ifdef HAVE_LIBBLUEZ
	178	m = g_slist_append(NULL, g_strdup("bluez"));
	179	m = g_slist_append(m, g_strdup_printf("%s", CONF_LIBBLUEZ_VERSION));
	180	l = g_slist_append(l, m);
	181	#endif
bd7b83cf	182	#ifdef HAVE_LIBFTDI
42be2adb UH	183	m = g_slist_append(NULL, g_strdup("libftdi"));
	184	m = g_slist_append(m, g_strdup_printf("%s", CONF_LIBFTDI_VERSION));
	185	l = g_slist_append(l, m);
bd7b83cf UH	186	#endif
bd7b83cf UH	187	#ifdef HAVE_LIBGPIB
42be2adb UH	188	m = g_slist_append(NULL, g_strdup("libgpib"));
	189	m = g_slist_append(m, g_strdup_printf("%s", CONF_LIBGPIB_VERSION));
	190	l = g_slist_append(l, m);
bd7b83cf UH	191	#endif
bd7b83cf UH	192	#ifdef HAVE_LIBREVISA
42be2adb UH	193	m = g_slist_append(NULL, g_strdup("librevisa"));
	194	m = g_slist_append(m, g_strdup_printf("%s", CONF_LIBREVISA_VERSION));
	195	l = g_slist_append(l, m);
bd7b83cf	196	#endif
bd7b83cf	197
42be2adb UH	198	return l;
	199	}
	200
	201	SR_API char *sr_buildinfo_host_get(void)
	202	{
	203	return g_strdup_printf("%s, %s-endian", CONF_HOST,
bd7b83cf	204	#ifdef WORDS_BIGENDIAN
42be2adb	205	"big"
bd7b83cf	206	#else
42be2adb	207	"little"
bd7b83cf	208	#endif
42be2adb UH	209	);
42be2adb UH	210	}
bd7b83cf	211
42be2adb UH	212	SR_API char *sr_buildinfo_scpi_backends_get(void)
	213	{
	214	GString *s;
	215	char *str;
	216
	217	s = g_string_sized_new(200);
bd7b83cf UH	218
	219	g_string_append_printf(s, "TCP, ");
	220	#if HAVE_RPC
	221	g_string_append_printf(s, "RPC, ");
	222	#endif
1df81f4b	223	#ifdef HAVE_SERIAL_COMM
bd7b83cf UH	224	g_string_append_printf(s, "serial, ");
	225	#endif
	226	#ifdef HAVE_LIBREVISA
	227	g_string_append_printf(s, "VISA, ");
	228	#endif
	229	#ifdef HAVE_LIBGPIB
	230	g_string_append_printf(s, "GPIB, ");
	231	#endif
	232	#ifdef HAVE_LIBUSB_1_0
	233	g_string_append_printf(s, "USBTMC, ");
	234	#endif
42be2adb UH	235	s->str[s->len - 2] = '\0';
	236
	237	str = g_strdup(s->str);
	238	g_string_free(s, TRUE);
	239
	240	return str;
	241	}
	242
	243	static void print_versions(void)
	244	{
	245	GString *s;
	246	GSList l, l_orig, *m;
	247	char *str;
	248	const char lib, version;
	249
942719b4	250	sr_dbg("libsigrok %s/%s.",
42be2adb UH	251	sr_package_version_string_get(), sr_lib_version_string_get());
	252
	253	s = g_string_sized_new(200);
	254	g_string_append(s, "Libs: ");
	255	l_orig = sr_buildinfo_libs_get();
	256	for (l = l_orig; l; l = l->next) {
	257	m = l->data;
	258	lib = m->data;
	259	version = m->next->data;
	260	g_string_append_printf(s, "%s %s, ", lib, version);
	261	g_slist_free_full(m, g_free);
	262	}
	263	g_slist_free(l_orig);
bd7b83cf UH	264	s->str[s->len - 2] = '.';
	265	s->str[s->len - 1] = '\0';
	266	sr_dbg("%s", s->str);
bd7b83cf	267	g_string_free(s, TRUE);
42be2adb UH	268
	269	str = sr_buildinfo_host_get();
	270	sr_dbg("Host: %s.", str);
	271	g_free(str);
	272
	273	str = sr_buildinfo_scpi_backends_get();
	274	sr_dbg("SCPI backends: %s.", str);
	275	g_free(str);
bd7b83cf UH	276	}
bd7b83cf UH	277
410883ba UH	278	static void print_resourcepaths(void)
	279	{
	280	GSList l, l_orig;
	281
	282	sr_dbg("Firmware search paths:");
	283	l_orig = sr_resourcepaths_get(SR_RESOURCE_FIRMWARE);
	284	for (l = l_orig; l; l = l->next)
	285	sr_dbg(" - %s", (const char *)l->data);
	286	g_slist_free_full(l_orig, g_free);
	287	}
	288
55a6daf5 UH	289	/**
	290	* Sanity-check all libsigrok drivers.
	291	*
032da34b UH	292	* @param[in] ctx Pointer to a libsigrok context struct. Must not be NULL.
032da34b UH	293	*
04cb9157 MH	294	* @retval SR_OK All drivers are OK
04cb9157 MH	295	* @retval SR_ERR One or more drivers have issues.
032da34b	296	* @retval SR_ERR_ARG Invalid argument.
55a6daf5	297	*/
032da34b	298	static int sanity_check_all_drivers(const struct sr_context *ctx)
55a6daf5 UH	299	{
	300	int i, errors, ret = SR_OK;
	301	struct sr_dev_driver **drivers;
	302	const char *d;
	303
032da34b UH	304	if (!ctx)
	305	return SR_ERR_ARG;
	306
55a6daf5 UH	307	sr_spew("Sanity-checking all drivers.");
55a6daf5 UH	308
032da34b	309	drivers = sr_driver_list(ctx);
55a6daf5 UH	310	for (i = 0; drivers[i]; i++) {
	311	errors = 0;
	312
	313	d = (drivers[i]->name) ? drivers[i]->name : "NULL";
	314
	315	if (!drivers[i]->name) {
	316	sr_err("No name in driver %d ('%s').", i, d);
	317	errors++;
	318	}
	319	if (!drivers[i]->longname) {
	320	sr_err("No longname in driver %d ('%s').", i, d);
	321	errors++;
	322	}
	323	if (drivers[i]->api_version < 1) {
	324	sr_err("API version in driver %d ('%s') < 1.", i, d);
	325	errors++;
	326	}
	327	if (!drivers[i]->init) {
	328	sr_err("No init in driver %d ('%s').", i, d);
	329	errors++;
	330	}
	331	if (!drivers[i]->cleanup) {
	332	sr_err("No cleanup in driver %d ('%s').", i, d);
	333	errors++;
	334	}
	335	if (!drivers[i]->scan) {
	336	sr_err("No scan in driver %d ('%s').", i, d);
	337	errors++;
	338	}
	339	if (!drivers[i]->dev_list) {
	340	sr_err("No dev_list in driver %d ('%s').", i, d);
	341	errors++;
	342	}
f778bf02 UH	343	if (!drivers[i]->dev_clear) {
	344	sr_err("No dev_clear in driver %d ('%s').", i, d);
	345	errors++;
	346	}
6fab7b8f UH	347	/* Note: config_get() is optional. */
	348	if (!drivers[i]->config_set) {
	349	sr_err("No config_set in driver %d ('%s').", i, d);
	350	errors++;
	351	}
797f1a0c UH	352	/* Note: config_channel_set() is optional. */
797f1a0c UH	353	/* Note: config_commit() is optional. */
6fab7b8f UH	354	if (!drivers[i]->config_list) {
	355	sr_err("No config_list in driver %d ('%s').", i, d);
	356	errors++;
	357	}
55a6daf5 UH	358	if (!drivers[i]->dev_open) {
	359	sr_err("No dev_open in driver %d ('%s').", i, d);
	360	errors++;
	361	}
	362	if (!drivers[i]->dev_close) {
	363	sr_err("No dev_close in driver %d ('%s').", i, d);
	364	errors++;
	365	}
55a6daf5 UH	366	if (!drivers[i]->dev_acquisition_start) {
	367	sr_err("No dev_acquisition_start in driver %d ('%s').",
	368	i, d);
	369	errors++;
	370	}
	371	if (!drivers[i]->dev_acquisition_stop) {
	372	sr_err("No dev_acquisition_stop in driver %d ('%s').",
	373	i, d);
	374	errors++;
	375	}
	376
	377	/* Note: 'priv' is allowed to be NULL. */
	378
	379	if (errors == 0)
	380	continue;
	381
	382	ret = SR_ERR;
	383	}
	384
	385	return ret;
	386	}
	387
218e629f UH	388	/**
	389	* Sanity-check all libsigrok input modules.
	390	*
04cb9157 MH	391	* @retval SR_OK All modules are OK
04cb9157 MH	392	* @retval SR_ERR One or more modules have issues.
218e629f UH	393	*/
	394	static int sanity_check_all_input_modules(void)
	395	{
	396	int i, errors, ret = SR_OK;
17bfaca6	397	const struct sr_input_module **inputs;
218e629f UH	398	const char *d;
	399
	400	sr_spew("Sanity-checking all input modules.");
	401
	402	inputs = sr_input_list();
	403	for (i = 0; inputs[i]; i++) {
	404	errors = 0;
	405
	406	d = (inputs[i]->id) ? inputs[i]->id : "NULL";
	407
	408	if (!inputs[i]->id) {
	409	sr_err("No ID in module %d ('%s').", i, d);
	410	errors++;
	411	}
17bfaca6 BV	412	if (!inputs[i]->name) {
	413	sr_err("No name in module %d ('%s').", i, d);
	414	errors++;
	415	}
	416	if (!inputs[i]->desc) {
218e629f UH	417	sr_err("No description in module %d ('%s').", i, d);
	418	errors++;
	419	}
218e629f UH	420	if (!inputs[i]->init) {
	421	sr_err("No init in module %d ('%s').", i, d);
	422	errors++;
	423	}
17bfaca6 BV	424	if (!inputs[i]->receive) {
17bfaca6 BV	425	sr_err("No receive in module %d ('%s').", i, d);
7066fd46 BV	426	errors++;
	427	}
	428	if (!inputs[i]->end) {
	429	sr_err("No end in module %d ('%s').", i, d);
218e629f UH	430	errors++;
	431	}
	432
	433	if (errors == 0)
	434	continue;
	435
	436	ret = SR_ERR;
	437	}
	438
	439	return ret;
	440	}
	441
	442	/**
	443	* Sanity-check all libsigrok output modules.
	444	*
04cb9157 MH	445	* @retval SR_OK All modules are OK
04cb9157 MH	446	* @retval SR_ERR One or more modules have issues.
218e629f UH	447	*/
	448	static int sanity_check_all_output_modules(void)
	449	{
	450	int i, errors, ret = SR_OK;
a755b0e1	451	const struct sr_output_module **outputs;
218e629f UH	452	const char *d;
	453
	454	sr_spew("Sanity-checking all output modules.");
	455
	456	outputs = sr_output_list();
	457	for (i = 0; outputs[i]; i++) {
	458	errors = 0;
	459
	460	d = (outputs[i]->id) ? outputs[i]->id : "NULL";
	461
	462	if (!outputs[i]->id) {
	463	sr_err("No ID in module %d ('%s').", i, d);
	464	errors++;
	465	}
a755b0e1 BV	466	if (!outputs[i]->name) {
	467	sr_err("No name in module %d ('%s').", i, d);
	468	errors++;
	469	}
	470	if (!outputs[i]->desc) {
44559b2c	471	sr_err("No description in module '%s'.", d);
218e629f UH	472	errors++;
218e629f UH	473	}
44559b2c BV	474	if (!outputs[i]->receive) {
44559b2c BV	475	sr_err("No receive in module '%s'.", d);
218e629f UH	476	errors++;
	477	}
	478
218e629f UH	479	if (errors == 0)
	480	continue;
	481
	482	ret = SR_ERR;
	483	}
	484
	485	return ret;
	486	}
	487
187cfc60 UH	488	/**
	489	* Sanity-check all libsigrok transform modules.
	490	*
	491	* @retval SR_OK All modules are OK
	492	* @retval SR_ERR One or more modules have issues.
	493	*/
	494	static int sanity_check_all_transform_modules(void)
	495	{
	496	int i, errors, ret = SR_OK;
	497	const struct sr_transform_module **transforms;
	498	const char *d;
	499
	500	sr_spew("Sanity-checking all transform modules.");
	501
	502	transforms = sr_transform_list();
	503	for (i = 0; transforms[i]; i++) {
	504	errors = 0;
	505
	506	d = (transforms[i]->id) ? transforms[i]->id : "NULL";
	507
	508	if (!transforms[i]->id) {
	509	sr_err("No ID in module %d ('%s').", i, d);
	510	errors++;
	511	}
	512	if (!transforms[i]->name) {
	513	sr_err("No name in module %d ('%s').", i, d);
	514	errors++;
	515	}
	516	if (!transforms[i]->desc) {
	517	sr_err("No description in module '%s'.", d);
	518	errors++;
	519	}
	520	/* Note: options() is optional. */
	521	/* Note: init() is optional. */
	522	if (!transforms[i]->receive) {
	523	sr_err("No receive in module '%s'.", d);
	524	errors++;
	525	}
	526	/* Note: cleanup() is optional. */
	527
	528	if (errors == 0)
	529	continue;
	530
	531	ret = SR_ERR;
	532	}
	533
	534	return ret;
	535	}
	536
cd009d55 UH	537	/**
	538	* Initialize libsigrok.
	539	*
c46762a2 UH	540	* This function must be called before any other libsigrok function.
	541	*
	542	* @param ctx Pointer to a libsigrok context struct pointer. Must not be NULL.
	543	* This will be a pointer to a newly allocated libsigrok context
	544	* object upon success, and is undefined upon errors.
	545	*
	546	* @return SR_OK upon success, a (negative) error code otherwise. Upon errors
	547	* the 'ctx' pointer is undefined and should not be used. Upon success,
	548	* the context will be free'd by sr_exit() as part of the libsigrok
	549	* shutdown.
9fb5f2df	550	*
53f05fa8	551	* @since 0.2.0
cd009d55	552	*/
b8072700	553	SR_API int sr_init(struct sr_context **ctx)
a1bb33af	554	{
b8072700 PS	555	int ret = SR_ERR;
b8072700 PS	556	struct sr_context *context;
fa69e191 ML	557	#ifdef _WIN32
	558	WSADATA wsadata;
	559	#endif
b8072700	560
bd7b83cf UH	561	print_versions();
bd7b83cf UH	562
410883ba UH	563	print_resourcepaths();
410883ba UH	564
c46762a2 UH	565	if (!ctx) {
	566	sr_err("%s(): libsigrok context was NULL.", __func__);
	567	return SR_ERR;
	568	}
	569
032da34b UH	570	context = g_malloc0(sizeof(struct sr_context));
032da34b UH	571
5d8b3913	572	sr_drivers_init(context);
032da34b UH	573
032da34b UH	574	if (sanity_check_all_drivers(context) < 0) {
55a6daf5	575	sr_err("Internal driver error(s), aborting.");
928560e6	576	goto done;
55a6daf5 UH	577	}
55a6daf5 UH	578
218e629f UH	579	if (sanity_check_all_input_modules() < 0) {
218e629f UH	580	sr_err("Internal input module error(s), aborting.");
928560e6	581	goto done;
218e629f UH	582	}
	583
	584	if (sanity_check_all_output_modules() < 0) {
	585	sr_err("Internal output module error(s), aborting.");
928560e6	586	goto done;
218e629f UH	587	}
218e629f UH	588
187cfc60 UH	589	if (sanity_check_all_transform_modules() < 0) {
187cfc60 UH	590	sr_err("Internal transform module error(s), aborting.");
928560e6	591	goto done;
187cfc60 UH	592	}
187cfc60 UH	593
fa69e191 ML	594	#ifdef _WIN32
	595	if ((ret = WSAStartup(MAKEWORD(2, 2), &wsadata)) != 0) {
	596	sr_err("WSAStartup failed with error code %d.", ret);
	597	ret = SR_ERR;
	598	goto done;
	599	}
	600	#endif
	601
b9cd0c6a GS	602	if ((ret = lzo_init()) != LZO_E_OK) {
	603	sr_err("lzo_init() failed with return code %d.", ret);
	604	sr_err("This usually indicates a compiler bug. Recompile without");
	605	sr_err("optimizations, and enable '-DLZO_DEBUG' for diagnostics.");
	606	ret = SR_ERR;
	607	goto done;
	608	}
	609
785b9ff2 PS	610	#ifdef HAVE_LIBUSB_1_0
785b9ff2 PS	611	ret = libusb_init(&context->libusb_ctx);
8e2d43cc	612	if (LIBUSB_SUCCESS != ret) {
9d122af8	613	sr_err("libusb_init() returned %s.", libusb_error_name(ret));
63c07e48	614	ret = SR_ERR;
785b9ff2 PS	615	goto done;
785b9ff2 PS	616	}
4417074c GS	617	#endif
	618	#ifdef HAVE_LIBHIDAPI
	619	/*
	620	* According to <hidapi.h>, the hid_init() routine just returns
	621	* zero or non-zero, and hid_error() appears to relate to calls
	622	* for a specific device after hid_open(). Which means that there
	623	* is no more detailled information available beyond success/fail
	624	* at this point in time.
	625	*/
	626	if (hid_init() != 0) {
	627	sr_err("HIDAPI hid_init() failed.");
	628	ret = SR_ERR;
	629	goto done;
	630	}
785b9ff2	631	#endif
bee24666	632	sr_resource_set_hooks(context, NULL, NULL, NULL, NULL);
785b9ff2	633
b8072700	634	*ctx = context;
123d97b1	635	context = NULL;
b8072700 PS	636	ret = SR_OK;
	637
	638	done:
b1f83103	639	g_free(context);
b8072700	640	return ret;
a1bb33af UH	641	}
a1bb33af UH	642
cd009d55 UH	643	/**
	644	* Shutdown libsigrok.
	645	*
c46762a2 UH	646	* @param ctx Pointer to a libsigrok context struct. Must not be NULL.
c46762a2 UH	647	*
04cb9157 MH	648	* @retval SR_OK Success
04cb9157 MH	649	* @retval other Error code SR_ERR, ...
9fb5f2df	650	*
53f05fa8	651	* @since 0.2.0
cd009d55	652	*/
b8072700	653	SR_API int sr_exit(struct sr_context *ctx)
a1bb33af	654	{
c46762a2 UH	655	if (!ctx) {
	656	sr_err("%s(): libsigrok context was NULL.", __func__);
	657	return SR_ERR;
	658	}
	659
032da34b	660	sr_hw_cleanup_all(ctx);
cd009d55	661
fa69e191 ML	662	#ifdef _WIN32
	663	WSACleanup();
	664	#endif
	665
4417074c GS	666	#ifdef HAVE_LIBHIDAPI
	667	hid_exit();
	668	#endif
785b9ff2 PS	669	#ifdef HAVE_LIBUSB_1_0
	670	libusb_exit(ctx->libusb_ctx);
	671	#endif
	672
032da34b	673	g_free(sr_driver_list(ctx));
b8072700 PS	674	g_free(ctx);
b8072700 PS	675
cd009d55	676	return SR_OK;
a1bb33af	677	}
7b870c38 UH	678
7b870c38 UH	679	/** @} */