X-Git-Url: https://sigrok.org/gitweb/?a=blobdiff_plain;f=session.c;h=9f8a4df797728e401aa7b5e42fe54408b003f945;hb=6375e1c3eba6243bcaa28f0eee5452cc6f9ae2fd;hp=92ee648a631c77d41092beb3bf010f00c5537d30;hpb=b04781bb2ba910d17b0bc11b499b1be352faa9cc;p=libsigrok.git

diff --git a/session.c b/session.c
index 92ee648a..9f8a4df7 100644
--- a/session.c
+++ b/session.c
@@ -25,6 +25,20 @@
 #include "libsigrok.h"
 #include "libsigrok-internal.h"
 
+/**
+ * @file
+ *
+ * Creating, using, or destroying libsigrok sessions.
+ */
+
+/**
+ * @defgroup grp_session Session handling
+ *
+ * Creating, using, or destroying libsigrok sessions.
+ *
+ * @{
+ */
+
 struct source {
 	int timeout;
 	sr_receive_data_callback_t cb;
@@ -43,7 +57,7 @@ struct sr_session *session;
 /**
  * Create a new session.
  *
- * TODO: Should it use the file-global "session" variable or take an argument?
+ * @todo Should it use the file-global "session" variable or take an argument?
  *       The same question applies to all the other session functions.
  *
  * @return A pointer to the newly allocated session, or NULL upon errors.
@@ -78,22 +92,20 @@ SR_API int sr_session_destroy(void)
 
 	/* TODO: Error checks needed? */
 
-	/* TODO: Loop over protocol decoders and free them. */
-
 	g_free(session);
 	session = NULL;
 
 	return SR_OK;
 }
 
-static void sr_dev_close(struct sr_dev *dev)
+static void sr_dev_close(struct sr_dev_inst *sdi)
 {
-	if (dev && dev->driver && dev->driver->dev_close)
-		dev->driver->dev_close(dev->driver_index);
+	if (sdi->driver && sdi->driver->dev_close)
+		sdi->driver->dev_close(sdi);
 }
 
 /**
- * Remove all the devices from the current session. TODO?
+ * Remove all the devices from the current session.
  *
  * The session itself (i.e., the struct sr_session) is not free'd and still
  * exists after this function returns.
@@ -114,19 +126,20 @@ SR_API int sr_session_dev_remove_all(void)
 }
 
 /**
- * Add a device to the current session.
+ * Add a device instance to the current session.
  *
- * @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.
+ * @param sdi The device instance to add to the current session. Must not
+ *            be NULL. Also, sdi->driver and sdi->driver->dev_open must
+ *            not be NULL.
  *
  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments.
  */
-SR_API int sr_session_dev_add(struct sr_dev *dev)
+SR_API int sr_session_dev_add(const struct sr_dev_inst *sdi)
 {
 	int ret;
 
-	if (!dev) {
-		sr_err("session: %s: dev was NULL", __func__);
+	if (!sdi) {
+		sr_err("session: %s: sdi was NULL", __func__);
 		return SR_ERR_ARG;
 	}
 
@@ -135,28 +148,27 @@ SR_API int sr_session_dev_add(struct sr_dev *dev)
 		return SR_ERR_BUG;
 	}
 
-	/* 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 "
+	/* If sdi->driver is NULL, this is a virtual device. */
+	if (!sdi->driver) {
+		sr_dbg("session: %s: sdi->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);
+		session->devs = g_slist_append(session->devs, (gpointer)sdi);
 		return SR_OK;
 	}
 
-	/* 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__);
+	/* sdi->driver is non-NULL (i.e. we have a real device). */
+	if (!sdi->driver->dev_open) {
+		sr_err("session: %s: sdi->driver->dev_open was NULL", __func__);
 		return SR_ERR_BUG;
 	}
 
-	if ((ret = dev->driver->dev_open(dev->driver_index)) != SR_OK) {
+	if ((ret = sdi->driver->dev_open((struct sr_dev_inst *)sdi)) != SR_OK) {
 		sr_err("session: %s: dev_open failed (%d)", __func__, ret);
 		return ret;
 	}
 
-	session->devs = g_slist_append(session->devs, dev);
+	session->devs = g_slist_append(session->devs, (gpointer)sdi);
 
 	return SR_OK;
 }
@@ -205,27 +217,25 @@ SR_API int sr_session_datafeed_callback_add(sr_datafeed_callback_t cb)
 	return SR_OK;
 }
 
-/**
- * TODO.
- */
 static int sr_session_run_poll(void)
 {
 	unsigned int i;
 	int ret;
 
-	while (session->running) {
-		ret = g_poll(session->pollfds, session->num_sources, session->source_timeout);
-
+	while (session->num_sources > 0) {
+		ret = g_poll(session->pollfds, session->num_sources,
+				session->source_timeout);
 		for (i = 0; i < session->num_sources; i++) {
 			if (session->pollfds[i].revents > 0 || (ret == 0
 				&& session->source_timeout == session->sources[i].timeout)) {
 				/*
 				 * Invoke the source's callback on an event,
-				 * or if the poll timeout out and this source
+				 * or if the poll timed out and this source
 				 * asked for that timeout.
 				 */
-				if (!session->sources[i].cb(session->pollfds[i].fd, session->pollfds[i].revents,
-						  session->sources[i].cb_data))
+				if (!session->sources[i].cb(session->pollfds[i].fd,
+						session->pollfds[i].revents,
+						session->sources[i].cb_data))
 					sr_session_source_remove(session->sources[i].poll_object);
 			}
 		}
@@ -243,32 +253,27 @@ static int sr_session_run_poll(void)
  */
 SR_API int sr_session_start(void)
 {
-	struct sr_dev *dev;
+	struct sr_dev_inst *sdi;
 	GSList *l;
 	int ret;
 
 	if (!session) {
 		sr_err("session: %s: session was NULL; a session must be "
-		       "created first, before starting it.", __func__);
+		       "created before starting it.", __func__);
 		return SR_ERR_BUG;
 	}
 
 	if (!session->devs) {
-		/* TODO: Actually the case? */
 		sr_err("session: %s: session->devs was NULL; a session "
 		       "cannot be started without devices.", __func__);
 		return SR_ERR_BUG;
 	}
 
-	/* TODO: Check driver_index validity? */
-
 	sr_info("session: starting");
 
 	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) {
+		sdi = l->data;
+		if ((ret = sdi->driver->dev_acquisition_start(sdi, sdi)) != SR_OK) {
 			sr_err("session: %s: could not start an acquisition "
 			       "(%d)", __func__, ret);
 			break;
@@ -283,8 +288,6 @@ SR_API int sr_session_start(void)
 /**
  * Run the session.
  *
- * TODO: Various error checks etc.
- *
  * @return SR_OK upon success, SR_ERR_BUG upon errors.
  */
 SR_API int sr_session_run(void)
@@ -303,12 +306,11 @@ SR_API int sr_session_run(void)
 	}
 
 	sr_info("session: running");
-	session->running = TRUE;
 
 	/* Do we have real sources? */
 	if (session->num_sources == 1 && session->pollfds[0].fd == -1) {
 		/* Dummy source, freewheel over it. */
-		while (session->running)
+		while (session->num_sources)
 			session->sources[0].cb(-1, 0, session->sources[0].cb_data);
 	} else {
 		/* Real sources, use g_poll() main loop. */
@@ -342,7 +344,7 @@ SR_API int sr_session_halt(void)
  */
 SR_API int sr_session_stop(void)
 {
-	struct sr_dev *dev;
+	struct sr_dev_inst *sdi;
 	GSList *l;
 
 	if (!session) {
@@ -351,17 +353,24 @@ SR_API int sr_session_stop(void)
 	}
 
 	sr_info("session: stopping");
-	session->running = FALSE;
 
 	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);
+		sdi = l->data;
+		if (sdi->driver) {
+			if (sdi->driver->dev_acquisition_stop)
+				sdi->driver->dev_acquisition_stop(sdi, sdi);
 		}
 	}
 
+	/*
+	 * Some sources may not be necessarily associated with a device.
+	 * Those sources may still be present even after stopping all devices.
+	 * We need to make sure all sources are removed, or we risk running the
+	 * session in an infinite loop.
+	 */
+	while (session->num_sources)
+		sr_session_source_remove(session->sources[0].poll_object);
+
 	return SR_OK;
 }
 
@@ -370,10 +379,10 @@ SR_API int sr_session_stop(void)
  *
  * @param packet The packet to show debugging information for.
  */
-static void datafeed_dump(struct sr_datafeed_packet *packet)
+static void datafeed_dump(const struct sr_datafeed_packet *packet)
 {
-	struct sr_datafeed_logic *logic;
-	struct sr_datafeed_analog *analog;
+	const struct sr_datafeed_logic *logic;
+	const struct sr_datafeed_analog *analog;
 
 	switch (packet->type) {
 	case SR_DF_HEADER:
@@ -391,7 +400,7 @@ static void datafeed_dump(struct sr_datafeed_packet *packet)
 		sr_dbg("bus: received SR_DF_LOGIC %" PRIu64 " bytes", logic->length);
 		break;
 	case SR_DF_META_ANALOG:
-		sr_dbg("bus: received SR_DF_META_LOGIC");
+		sr_dbg("bus: received SR_DF_META_ANALOG");
 		break;
 	case SR_DF_ANALOG:
 		analog = packet->payload;
@@ -418,19 +427,21 @@ static void datafeed_dump(struct sr_datafeed_packet *packet)
  *
  * Hardware drivers use this to send a data packet to the frontend.
  *
- * @param dev TODO.
+ * @param sdi TODO.
  * @param packet The datafeed packet to send to the session bus.
  *
  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments.
+ *
+ * @private
  */
-SR_PRIV int sr_session_send(struct sr_dev *dev,
-			    struct sr_datafeed_packet *packet)
+SR_PRIV int sr_session_send(const struct sr_dev_inst *sdi,
+			    const struct sr_datafeed_packet *packet)
 {
 	GSList *l;
 	sr_datafeed_callback_t cb;
 
-	if (!dev) {
-		sr_err("session: %s: dev was NULL", __func__);
+	if (!sdi) {
+		sr_err("session: %s: sdi was NULL", __func__);
 		return SR_ERR_ARG;
 	}
 
@@ -443,13 +454,24 @@ SR_PRIV int sr_session_send(struct sr_dev *dev,
 		if (sr_log_loglevel_get() >= SR_LOG_DBG)
 			datafeed_dump(packet);
 		cb = l->data;
-		/* TODO: Check for cb != NULL. */
-		cb(dev, packet);
+		cb(sdi, packet);
 	}
 
 	return SR_OK;
 }
 
+/**
+ * Add an event source for a file descriptor.
+ *
+ * @param pollfd The GPollFD.
+ * @param timeout Max time to wait before the callback is called, ignored if 0.
+ * @param cb Callback function to add. Must not be NULL.
+ * @param cb_data Data for the callback function. Can be NULL.
+ * @param poll_object TODO.
+ *
+ * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
+ *         SR_ERR_MALLOC upon memory allocation errors.
+ */
 static int _sr_session_source_add(GPollFD *pollfd, int timeout,
 	sr_receive_data_callback_t cb, void *cb_data, gintptr poll_object)
 {
@@ -463,14 +485,15 @@ static int _sr_session_source_add(GPollFD *pollfd, int timeout,
 
 	/* Note: cb_data can be NULL, that's not a bug. */
 
-	new_pollfds = g_try_realloc(session->pollfds, sizeof(GPollFD) * (session->num_sources + 1));
+	new_pollfds = g_try_realloc(session->pollfds,
+			sizeof(GPollFD) * (session->num_sources + 1));
 	if (!new_pollfds) {
 		sr_err("session: %s: new_pollfds malloc failed", __func__);
 		return SR_ERR_MALLOC;
 	}
 
 	new_sources = g_try_realloc(session->sources, sizeof(struct source) *
-	(session->num_sources + 1));
+			(session->num_sources + 1));
 	if (!new_sources) {
 		sr_err("session: %s: new_sources malloc failed", __func__);
 		return SR_ERR_MALLOC;
@@ -493,7 +516,7 @@ static int _sr_session_source_add(GPollFD *pollfd, int timeout,
 }
 
 /**
- * Add a event source for a file descriptor.
+ * Add an event source for a file descriptor.
  *
  * @param fd The file descriptor.
  * @param events Events to check for.
@@ -518,8 +541,6 @@ SR_API int sr_session_source_add(int fd, int events, int timeout,
 /**
  * Add an event source for a GPollFD.
  *
- * TODO: More error checks etc.
- *
  * @param pollfd The GPollFD.
  * @param timeout Max time to wait before the callback is called, ignored if 0.
  * @param cb Callback function to add. Must not be NULL.
@@ -538,8 +559,6 @@ SR_API int sr_session_source_add_pollfd(GPollFD *pollfd, int timeout,
 /**
  * Add an event source for a GIOChannel.
  *
- * TODO: More error checks etc.
- *
  * @param channel The GIOChannel.
  * @param events Events to poll on.
  * @param timeout Max time to wait before the callback is called, ignored if 0.
@@ -555,8 +574,7 @@ SR_API int sr_session_source_add_channel(GIOChannel *channel, int events,
 	GPollFD p;
 
 #ifdef _WIN32
-	g_io_channel_win32_make_pollfd(channel,
-			events, &p);
+	g_io_channel_win32_make_pollfd(channel, events, &p);
 #else
 	p.fd = g_io_channel_unix_get_fd(channel);
 	p.events = events;
@@ -565,7 +583,17 @@ SR_API int sr_session_source_add_channel(GIOChannel *channel, int events,
 	return _sr_session_source_add(&p, timeout, cb, cb_data, (gintptr)channel);
 }
 
-
+/**
+ * Remove the source belonging to the specified channel.
+ *
+ * @todo Add more error checks and logging.
+ *
+ * @param channel The channel for which the source should be removed.
+ *
+ * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
+ *         SR_ERR_MALLOC upon memory allocation errors, SR_ERR_BUG upon
+ *         internal errors.
+ */
 static int _sr_session_source_remove(gintptr poll_object)
 {
 	struct source *new_sources;
@@ -613,11 +641,9 @@ static int _sr_session_source_remove(gintptr poll_object)
 	return SR_OK;
 }
 
-/*
+/**
  * Remove the source belonging to the specified file descriptor.
  *
- * TODO: More error checks.
- *
  * @param fd The file descriptor for which the source should be removed.
  *
  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
@@ -632,8 +658,6 @@ SR_API int sr_session_source_remove(int fd)
 /**
  * Remove the source belonging to the specified poll descriptor.
  *
- * TODO: More error checks.
- *
  * @param pollfd The poll descriptor for which the source should be removed.
  *
  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
@@ -645,11 +669,9 @@ SR_API int sr_session_source_remove_pollfd(GPollFD *pollfd)
 	return _sr_session_source_remove((gintptr)pollfd);
 }
 
-/*
+/**
  * Remove the source belonging to the specified channel.
  *
- * TODO: More error checks.
- *
  * @param channel The channel for which the source should be removed.
  *
  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
@@ -660,3 +682,5 @@ SR_API int sr_session_source_remove_channel(GIOChannel *channel)
 {
 	return _sr_session_source_remove((gintptr)channel);
 }
+
+/** @} */