X-Git-Url: https://sigrok.org/gitweb/?a=blobdiff_plain;f=session.c;h=f1a8370bf48784641973a978ae5ba45a28f110bb;hb=01c3e9dbd5bd583012fc1f46237bf4fde784d209;hp=b33baa5c57f32a990d62dba28ce3e0816dc87d2d;hpb=996b0c7234c5cc420181b57370f6ba264aee24d2;p=libsigrok.git

diff --git a/session.c b/session.c
index b33baa5c..f1a8370b 100644
--- a/session.c
+++ b/session.c
@@ -1,7 +1,7 @@
 /*
  * This file is part of the sigrok project.
  *
- * Copyright (C) 2012 Bert Vermeulen <bert@biot.com>
+ * Copyright (C) 2010-2012 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
@@ -32,8 +32,8 @@ struct source {
 	int fd;
 	int events;
 	int timeout;
-	sr_receive_data_callback cb;
-	void *user_data;
+	sr_receive_data_callback_t cb;
+	void *cb_data;
 };
 
 /* There can only be one session at a time. */
@@ -47,9 +47,6 @@ static int source_timeout = -1;
 /**
  * Create a new session.
  *
- * TODO.
- *
- * TODO: Should return int?
  * TODO: Should it use the file-global "session" variable or take an argument?
  *       The same question applies to all the other session functions.
  *
@@ -79,8 +76,8 @@ SR_API int sr_session_destroy(void)
 		return SR_ERR_BUG;
 	}
 
-	g_slist_free(session->devices);
-	session->devices = NULL;
+	g_slist_free(session->devs);
+	session->devs = NULL;
 
 	/* TODO: Error checks needed? */
 
@@ -100,15 +97,15 @@ SR_API int sr_session_destroy(void)
  *
  * @return SR_OK upon success, SR_ERR_BUG if no session exists.
  */
-SR_API int sr_session_device_clear(void)
+SR_API int sr_session_dev_remove_all(void)
 {
 	if (!session) {
 		sr_err("session: %s: session was NULL", __func__);
 		return SR_ERR_BUG;
 	}
 
-	g_slist_free(session->devices);
-	session->devices = NULL;
+	g_slist_free(session->devs);
+	session->devs = NULL;
 
 	return SR_OK;
 }
@@ -116,55 +113,57 @@ SR_API int sr_session_device_clear(void)
 /**
  * Add a device to the current session.
  *
- * @param device The device to add to the current session. Must not be NULL.
- *               Also, device->plugin and device->plugin->opendev must not
- *               be NULL.
+ * @param dev The device to add to the current session. Must not be NULL.
+ *            Also, dev->driver and dev->driver->dev_open must not be NULL.
  *
  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments.
  */
-SR_API int sr_session_device_add(struct sr_device *device)
+SR_API int sr_session_dev_add(struct sr_dev *dev)
 {
 	int ret;
 
-	if (!device) {
-		sr_err("session: %s: device was NULL", __func__);
+	if (!dev) {
+		sr_err("session: %s: dev was NULL", __func__);
 		return SR_ERR_ARG;
 	}
 
-	if (!device->plugin) {
-		sr_err("session: %s: device->plugin was NULL", __func__);
-		return SR_ERR_ARG;
+	if (!session) {
+		sr_err("session: %s: session was NULL", __func__);
+		return SR_ERR_BUG;
 	}
 
-	if (!device->plugin->opendev) {
-		sr_err("session: %s: device->plugin->opendev was NULL",
-		       __func__);
-		return SR_ERR_ARG;
+	/* If dev->driver is NULL, this is a virtual device. */
+	if (!dev->driver) {
+		sr_dbg("session: %s: dev->driver was NULL, this seems to be "
+		       "a virtual device; continuing", __func__);
+		/* Just add the device, don't run dev_open(). */
+		session->devs = g_slist_append(session->devs, dev);
+		return SR_OK;
 	}
 
-	if (!session) {
-		sr_err("session: %s: session was NULL", __func__);
-		return SR_ERR; /* TODO: SR_ERR_BUG? */
+	/* dev->driver is non-NULL (i.e. we have a real device). */
+	if (!dev->driver->dev_open) {
+		sr_err("session: %s: dev->driver->dev_open was NULL",
+		       __func__);
+		return SR_ERR_BUG;
 	}
 
-	if ((ret = device->plugin->opendev(device->plugin_index)) != SR_OK) {
-		sr_err("session: %s: opendev failed (%d)", __func__, ret);
+	if ((ret = dev->driver->dev_open(dev->driver_index)) != SR_OK) {
+		sr_err("session: %s: dev_open failed (%d)", __func__, ret);
 		return ret;
 	}
 
-	session->devices = g_slist_append(session->devices, device);
+	session->devs = g_slist_append(session->devs, dev);
 
 	return SR_OK;
 }
 
 /**
- * Clear all datafeed callbacks in the current session.
- *
- * TODO.
+ * Remove all datafeed callbacks in the current session.
  *
  * @return SR_OK upon success, SR_ERR_BUG if no session exists.
  */
-SR_API int sr_session_datafeed_callback_clear(void)
+SR_API int sr_session_datafeed_callback_remove_all(void)
 {
 	if (!session) {
 		sr_err("session: %s: session was NULL", __func__);
@@ -180,20 +179,25 @@ SR_API int sr_session_datafeed_callback_clear(void)
 /**
  * Add a datafeed callback to the current session.
  *
- * @param callback TODO.
+ * @param cb Function to call when a chunk of data is received.
+ *           Must not be NULL.
+ *
  * @return SR_OK upon success, SR_ERR_BUG if no session exists.
  */
-SR_API int sr_session_datafeed_callback_add(sr_datafeed_callback callback)
+SR_API int sr_session_datafeed_callback_add(sr_datafeed_callback_t cb)
 {
 	if (!session) {
 		sr_err("session: %s: session was NULL", __func__);
 		return SR_ERR_BUG;
 	}
 
-	/* TODO: Is 'callback' allowed to be NULL? */
+	if (!cb) {
+		sr_err("session: %s: cb was NULL", __func__);
+		return SR_ERR_ARG;
+	}
 
 	session->datafeed_callbacks =
-	    g_slist_append(session->datafeed_callbacks, callback);
+	    g_slist_append(session->datafeed_callbacks, cb);
 
 	return SR_OK;
 }
@@ -238,7 +242,7 @@ static int sr_session_run_poll(void)
 				 * asked for that timeout.
 				 */
 				if (!sources[i].cb(fds[i].fd, fds[i].revents,
-						  sources[i].user_data))
+						  sources[i].cb_data))
 					sr_session_source_remove(sources[i].fd);
 			}
 		}
@@ -251,38 +255,38 @@ static int sr_session_run_poll(void)
 /**
  * Start a session.
  *
- * There can only be one session at a time. TODO
+ * There can only be one session at a time.
  *
  * @return SR_OK upon success, SR_ERR upon errors.
  */
 SR_API int sr_session_start(void)
 {
-	struct sr_device *device;
+	struct sr_dev *dev;
 	GSList *l;
 	int ret;
 
 	if (!session) {
 		sr_err("session: %s: session was NULL; a session must be "
 		       "created first, before starting it.", __func__);
-		return SR_ERR; /* TODO: SR_ERR_BUG? */
+		return SR_ERR_BUG;
 	}
 
-	if (!session->devices) {
+	if (!session->devs) {
 		/* TODO: Actually the case? */
-		sr_err("session: %s: session->devices was NULL; a session "
+		sr_err("session: %s: session->devs was NULL; a session "
 		       "cannot be started without devices.", __func__);
-		return SR_ERR; /* TODO: SR_ERR_BUG? */
+		return SR_ERR_BUG;
 	}
 
-	/* TODO: Check plugin_index validity? */
+	/* TODO: Check driver_index validity? */
 
 	sr_info("session: starting");
 
-	for (l = session->devices; l; l = l->next) {
-		device = l->data;
-		/* TODO: Check for device != NULL. */
-		if ((ret = device->plugin->start_acquisition(
-				device->plugin_index, device)) != SR_OK) {
+	for (l = session->devs; l; l = l->next) {
+		dev = l->data;
+		/* TODO: Check for dev != NULL. */
+		if ((ret = dev->driver->dev_acquisition_start(
+				dev->driver_index, dev)) != SR_OK) {
 			sr_err("session: %s: could not start an acquisition "
 			       "(%d)", __func__, ret);
 			break;
@@ -309,9 +313,9 @@ SR_API int sr_session_run(void)
 		return SR_ERR_BUG;
 	}
 
-	if (!session->devices) {
+	if (!session->devs) {
 		/* TODO: Actually the case? */
-		sr_err("session: %s: session->devices was NULL; a session "
+		sr_err("session: %s: session->devs was NULL; a session "
 		       "cannot be run without devices.", __func__);
 		return SR_ERR_BUG;
 	}
@@ -323,7 +327,7 @@ SR_API int sr_session_run(void)
 	if (num_sources == 1 && sources[0].fd == -1) {
 		/* Dummy source, freewheel over it. */
 		while (session->running)
-			sources[0].cb(-1, 0, sources[0].user_data);
+			sources[0].cb(-1, 0, sources[0].cb_data);
 	} else {
 		/* Real sources, use g_poll() main loop. */
 		sr_session_run_poll();
@@ -335,7 +339,8 @@ SR_API int sr_session_run(void)
 /**
  * Halt the current session.
  *
- * TODO.
+ * This requests the current session be stopped as soon as possible, for
+ * example on receiving an SR_DF_END packet.
  *
  * @return SR_OK upon success, SR_ERR_BUG if no session exists.
  */
@@ -355,13 +360,14 @@ SR_API int sr_session_halt(void)
 /**
  * Stop the current session.
  *
- * TODO: Difference to halt?
+ * The current session is stopped immediately, with all acquisition sessions
+ * being stopped and hardware drivers cleaned up.
  *
  * @return SR_OK upon success, SR_ERR_BUG if no session exists.
  */
 SR_API int sr_session_stop(void)
 {
-	struct sr_device *device;
+	struct sr_dev *dev;
 	GSList *l;
 
 	if (!session) {
@@ -372,14 +378,14 @@ SR_API int sr_session_stop(void)
 	sr_info("session: stopping");
 	session->running = FALSE;
 
-	for (l = session->devices; l; l = l->next) {
-		device = l->data;
-		/* Check for device != NULL. */
-		if (device->plugin) {
-			if (device->plugin->stop_acquisition)
-				device->plugin->stop_acquisition(device->plugin_index, device);
-			if (device->plugin->cleanup)
-				device->plugin->cleanup();
+	for (l = session->devs; l; l = l->next) {
+		dev = l->data;
+		/* Check for dev != NULL. */
+		if (dev->driver) {
+			if (dev->driver->dev_acquisition_stop)
+				dev->driver->dev_acquisition_stop(dev->driver_index, dev);
+			if (dev->driver->cleanup)
+				dev->driver->cleanup();
 		}
 	}
 
@@ -387,10 +393,9 @@ SR_API int sr_session_stop(void)
 }
 
 /**
- * @brief debug helper
+ * Debug helper.
  *
  * @param packet The packet to show debugging information for.
- *
  */
 static void datafeed_dump(struct sr_datafeed_packet *packet)
 {
@@ -415,29 +420,26 @@ static void datafeed_dump(struct sr_datafeed_packet *packet)
 		sr_dbg("bus: received unknown packet type %d", packet->type);
 		break;
 	}
-
 }
 
 /**
- * TODO.
+ * Send a packet to whatever is listening on the datafeed bus.
+ *
+ * Hardware drivers use this to send a data packet to the frontend.
+ *
+ * @param dev TODO.
+ * @param packet The datafeed packet to send to the session bus.
  *
- * @param device TODO.
- * @param packet TODO.
  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments.
  */
-SR_API int sr_session_bus(struct sr_device *device,
-			  struct sr_datafeed_packet *packet)
+SR_PRIV int sr_session_send(struct sr_dev *dev,
+			    struct sr_datafeed_packet *packet)
 {
 	GSList *l;
-	sr_datafeed_callback cb;
-
-	if (!device) {
-		sr_err("session: %s: device was NULL", __func__);
-		return SR_ERR_ARG;
-	}
+	sr_datafeed_callback_t cb;
 
-	if (!device->plugin) {
-		sr_err("session: %s: device->plugin was NULL", __func__);
+	if (!dev) {
+		sr_err("session: %s: dev was NULL", __func__);
 		return SR_ERR_ARG;
 	}
 
@@ -446,16 +448,12 @@ SR_API int sr_session_bus(struct sr_device *device,
 		return SR_ERR_ARG;
 	}
 
-	/*
-	 * TODO: Send packet through PD pipe, and send the output of that to
-	 * the callbacks as well.
-	 */
 	for (l = session->datafeed_callbacks; l; l = l->next) {
 		if (sr_log_loglevel_get() >= SR_LOG_DBG)
 			datafeed_dump(packet);
 		cb = l->data;
 		/* TODO: Check for cb != NULL. */
-		cb(device, packet);
+		cb(dev, packet);
 	}
 
 	return SR_OK;
@@ -469,22 +467,23 @@ SR_API int sr_session_bus(struct sr_device *device,
  * @param fd TODO.
  * @param events TODO.
  * @param timeout TODO.
- * @param callback TODO.
- * @param user_data TODO.
+ * @param cb Callback function to add. Must not be NULL.
+ * @param cb_data Data for the callback function. Can be NULL.
+ *
  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
  *         SR_ERR_MALLOC upon memory allocation errors.
  */
 SR_API int sr_session_source_add(int fd, int events, int timeout,
-		sr_receive_data_callback callback, void *user_data)
+		sr_receive_data_callback_t cb, void *cb_data)
 {
 	struct source *new_sources, *s;
 
-	if (!callback) {
-		sr_err("session: %s: callback was NULL", __func__);
+	if (!cb) {
+		sr_err("session: %s: cb was NULL", __func__);
 		return SR_ERR_ARG;
 	}
 
-	/* Note: user_data can be NULL, that's not a bug. */
+	/* Note: cb_data can be NULL, that's not a bug. */
 
 	new_sources = g_try_malloc0(sizeof(struct source) * (num_sources + 1));
 	if (!new_sources) {
@@ -502,8 +501,8 @@ SR_API int sr_session_source_add(int fd, int events, int timeout,
 	s->fd = fd;
 	s->events = events;
 	s->timeout = timeout;
-	s->cb = callback;
-	s->user_data = user_data;
+	s->cb = cb;
+	s->cb_data = cb_data;
 	sources = new_sources;
 
 	if (timeout != source_timeout && timeout > 0
@@ -519,6 +518,7 @@ SR_API int sr_session_source_add(int fd, int events, int timeout,
  * TODO: More error checks.
  *
  * @param fd TODO.
+ *
  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
  *         SR_ERR_MALLOC upon memory allocation errors, SR_ERR_BUG upon
  *         internal errors.
@@ -530,7 +530,7 @@ SR_API int sr_session_source_remove(int fd)
 
 	if (!sources) {
 		sr_err("session: %s: sources was NULL", __func__);
-		return SR_ERR_BUG; /* TODO: Other? */
+		return SR_ERR_BUG;
 	}
 
 	/* TODO: Check if 'fd' valid. */