X-Git-Url: https://sigrok.org/gitweb/?a=blobdiff_plain;f=session.c;h=81e09b114dc59c44a2300dd85ad927329a7714ba;hb=61a429c963fb21c3d8cb8e9166d621526724b714;hp=e4b8c1c24d7901feb3c85573338af018c8194528;hpb=2ac2e629fc2ba2e89351d3ce337e0de9e034c540;p=libsigrok.git

diff --git a/session.c b/session.c
index e4b8c1c2..81e09b11 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,8 +92,6 @@ SR_API int sr_session_destroy(void)
 
 	/* TODO: Error checks needed? */
 
-	/* TODO: Loop over protocol decoders and free them. */
-
 	g_free(session);
 	session = NULL;
 
@@ -88,12 +100,12 @@ SR_API int sr_session_destroy(void)
 
 static void sr_dev_close(struct sr_dev_inst *sdi)
 {
-	if (sdi->driver->dev_close)
+	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,9 +126,9 @@ 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 instance to add to the current session. Must not
+ * @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.
  *
@@ -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);
 			}
 		}
@@ -278,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)
@@ -298,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. */
@@ -346,7 +353,6 @@ SR_API int sr_session_stop(void)
 	}
 
 	sr_info("session: stopping");
-	session->running = FALSE;
 
 	for (l = session->devs; l; l = l->next) {
 		sdi = l->data;
@@ -385,7 +391,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;
@@ -412,10 +418,12 @@ 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(const struct sr_dev_inst *sdi,
 			    struct sr_datafeed_packet *packet)
@@ -443,6 +451,18 @@ SR_PRIV int sr_session_send(const struct sr_dev_inst *sdi,
 	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)
 {
@@ -487,7 +507,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.
@@ -512,8 +532,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.
@@ -532,8 +550,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.
@@ -549,8 +565,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;
@@ -559,7 +574,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;
@@ -607,11 +632,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
@@ -626,8 +649,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
@@ -639,11 +660,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
@@ -654,3 +673,5 @@ SR_API int sr_session_source_remove_channel(GIOChannel *channel)
 {
 	return _sr_session_source_remove((gintptr)channel);
 }
+
+/** @} */