X-Git-Url: http://sigrok.org/gitweb/?a=blobdiff_plain;f=session.c;h=973fd15231250e04b18e233c43cbaf84a2818a25;hb=4c961f5ed5e127aae75e48cd4369dc25439f24d4;hp=0c57a87ba3a6573e73b00c24c173deb84a830b27;hpb=b4bd70889f3009f5d836a9bf701725a6aceac039;p=libsigrok.git

diff --git a/session.c b/session.c
index 0c57a87b..973fd152 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;
 
@@ -93,7 +105,7 @@ static void sr_dev_close(struct sr_dev_inst *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.
  *
@@ -259,6 +271,7 @@ SR_API int sr_session_start(void)
 
 	sr_info("session: starting");
 
+	ret = SR_OK;
 	for (l = session->devs; l; l = l->next) {
 		sdi = l->data;
 		if ((ret = sdi->driver->dev_acquisition_start(sdi, sdi)) != SR_OK) {
@@ -276,8 +289,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)
@@ -352,6 +363,15 @@ SR_API int sr_session_stop(void)
 		}
 	}
 
+	/*
+	 * 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;
 }
 
@@ -360,10 +380,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:
@@ -372,20 +392,15 @@ static void datafeed_dump(struct sr_datafeed_packet *packet)
 	case SR_DF_TRIGGER:
 		sr_dbg("bus: received SR_DF_TRIGGER");
 		break;
-	case SR_DF_META_LOGIC:
-		sr_dbg("bus: received SR_DF_META_LOGIC");
+	case SR_DF_META:
+		sr_dbg("bus: received SR_DF_META");
 		break;
 	case SR_DF_LOGIC:
 		logic = packet->payload;
-		/* TODO: Check for logic != NULL. */
 		sr_dbg("bus: received SR_DF_LOGIC %" PRIu64 " bytes", logic->length);
 		break;
-	case SR_DF_META_ANALOG:
-		sr_dbg("bus: received SR_DF_META_ANALOG");
-		break;
 	case SR_DF_ANALOG:
 		analog = packet->payload;
-		/* TODO: Check for analog != NULL. */
 		sr_dbg("bus: received SR_DF_ANALOG %d samples", analog->num_samples);
 		break;
 	case SR_DF_END:
@@ -408,7 +423,7 @@ 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.
@@ -416,7 +431,7 @@ static void datafeed_dump(struct sr_datafeed_packet *packet)
  * @private
  */
 SR_PRIV int sr_session_send(const struct sr_dev_inst *sdi,
-			    struct sr_datafeed_packet *packet)
+			    const struct sr_datafeed_packet *packet)
 {
 	GSList *l;
 	sr_datafeed_callback_t cb;
@@ -441,6 +456,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)
 {
@@ -485,7 +512,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.
@@ -510,8 +537,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.
@@ -530,8 +555,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.
@@ -547,8 +570,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;
@@ -557,7 +579,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;
@@ -605,11 +637,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
@@ -624,8 +654,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
@@ -637,11 +665,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
@@ -652,3 +678,5 @@ SR_API int sr_session_source_remove_channel(GIOChannel *channel)
 {
 	return _sr_session_source_remove((gintptr)channel);
 }
+
+/** @} */