2 * This file is part of the libsigrok project.
4 * Copyright (C) 2010-2012 Bert Vermeulen <bert@biot.com>
6 * This program is free software: you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation, either version 3 of the License, or
9 * (at your option) any later version.
11 * This program is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU General Public License for more details.
16 * You should have received a copy of the GNU General Public License
17 * along with this program. If not, see <http://www.gnu.org/licenses/>.
25 #include "libsigrok.h"
26 #include "libsigrok-internal.h"
29 #define LOG_PREFIX "session"
35 * Creating, using, or destroying libsigrok sessions.
39 * @defgroup grp_session Session handling
41 * Creating, using, or destroying libsigrok sessions.
48 sr_receive_data_callback cb;
51 /* This is used to keep track of the object (fd, pollfd or channel) which is
52 * being polled and will be used to match the source when removing it again.
57 struct datafeed_callback {
58 sr_datafeed_callback cb;
63 * Create a new session.
65 * @param new_session This will contain a pointer to the newly created
66 * session if the return value is SR_OK, otherwise the value
67 * is undefined and should not be used. Must not be NULL.
69 * @retval SR_OK Success.
70 * @retval SR_ERR_ARG Invalid argument.
74 SR_API int sr_session_new(struct sr_session **new_session)
76 struct sr_session *session;
81 session = g_malloc0(sizeof(struct sr_session));
83 session->source_timeout = -1;
84 session->running = FALSE;
85 session->abort_session = FALSE;
86 g_mutex_init(&session->stop_mutex);
88 *new_session = session;
95 * This frees up all memory used by the session.
97 * @param session The session to destroy. Must not be NULL.
99 * @retval SR_OK Success.
100 * @retval SR_ERR_ARG Invalid session passed.
104 SR_API int sr_session_destroy(struct sr_session *session)
107 sr_err("%s: session was NULL", __func__);
111 sr_session_dev_remove_all(session);
112 g_mutex_clear(&session->stop_mutex);
113 if (session->trigger)
114 sr_trigger_free(session->trigger);
116 g_slist_free_full(session->owned_devs, (GDestroyNotify)sr_dev_inst_free);
124 * Remove all the devices from a session.
126 * The session itself (i.e., the struct sr_session) is not free'd and still
127 * exists after this function returns.
129 * @param session The session to use. Must not be NULL.
131 * @retval SR_OK Success.
132 * @retval SR_ERR_BUG Invalid session passed.
136 SR_API int sr_session_dev_remove_all(struct sr_session *session)
138 struct sr_dev_inst *sdi;
142 sr_err("%s: session was NULL", __func__);
146 for (l = session->devs; l; l = l->next) {
147 sdi = (struct sr_dev_inst *) l->data;
151 g_slist_free(session->devs);
152 session->devs = NULL;
158 * Add a device instance to a session.
160 * @param session The session to add to. Must not be NULL.
161 * @param sdi The device instance to add to a session. Must not
162 * be NULL. Also, sdi->driver and sdi->driver->dev_open must
165 * @retval SR_OK Success.
166 * @retval SR_ERR_ARG Invalid argument.
170 SR_API int sr_session_dev_add(struct sr_session *session,
171 struct sr_dev_inst *sdi)
176 sr_err("%s: sdi was NULL", __func__);
181 sr_err("%s: session was NULL", __func__);
185 /* If sdi->session is not NULL, the device is already in this or
186 * another session. */
188 sr_err("%s: already assigned to session", __func__);
192 /* If sdi->driver is NULL, this is a virtual device. */
194 /* Just add the device, don't run dev_open(). */
195 session->devs = g_slist_append(session->devs, (gpointer)sdi);
196 sdi->session = session;
200 /* sdi->driver is non-NULL (i.e. we have a real device). */
201 if (!sdi->driver->dev_open) {
202 sr_err("%s: sdi->driver->dev_open was NULL", __func__);
206 session->devs = g_slist_append(session->devs, (gpointer)sdi);
207 sdi->session = session;
209 if (session->running) {
210 /* Adding a device to a running session. Commit settings
211 * and start acquisition on that device now. */
212 if ((ret = sr_config_commit(sdi)) != SR_OK) {
213 sr_err("Failed to commit device settings before "
214 "starting acquisition in running session (%s)",
218 if ((ret = sdi->driver->dev_acquisition_start(sdi,
219 (void *)sdi)) != SR_OK) {
220 sr_err("Failed to start acquisition of device in "
221 "running session (%s)", sr_strerror(ret));
230 * List all device instances attached to a session.
232 * @param session The session to use. Must not be NULL.
233 * @param devlist A pointer where the device instance list will be
234 * stored on return. If no devices are in the session,
235 * this will be NULL. Each element in the list points
236 * to a struct sr_dev_inst *.
237 * The list must be freed by the caller, but not the
238 * elements pointed to.
240 * @retval SR_OK Success.
241 * @retval SR_ERR_ARG Invalid argument.
245 SR_API int sr_session_dev_list(struct sr_session *session, GSList **devlist)
253 *devlist = g_slist_copy(session->devs);
259 * Remove all datafeed callbacks in a session.
261 * @param session The session to use. Must not be NULL.
263 * @retval SR_OK Success.
264 * @retval SR_ERR_ARG Invalid session passed.
268 SR_API int sr_session_datafeed_callback_remove_all(struct sr_session *session)
271 sr_err("%s: session was NULL", __func__);
275 g_slist_free_full(session->datafeed_callbacks, g_free);
276 session->datafeed_callbacks = NULL;
282 * Add a datafeed callback to a session.
284 * @param session The session to use. Must not be NULL.
285 * @param cb Function to call when a chunk of data is received.
287 * @param cb_data Opaque pointer passed in by the caller.
289 * @retval SR_OK Success.
290 * @retval SR_ERR_BUG No session exists.
294 SR_API int sr_session_datafeed_callback_add(struct sr_session *session,
295 sr_datafeed_callback cb, void *cb_data)
297 struct datafeed_callback *cb_struct;
300 sr_err("%s: session was NULL", __func__);
305 sr_err("%s: cb was NULL", __func__);
309 cb_struct = g_malloc0(sizeof(struct datafeed_callback));
311 cb_struct->cb_data = cb_data;
313 session->datafeed_callbacks =
314 g_slist_append(session->datafeed_callbacks, cb_struct);
320 * Get the trigger assigned to this session.
322 * @param session The session to use.
324 * @retval NULL Invalid (NULL) session was passed to the function.
325 * @retval other The trigger assigned to this session (can be NULL).
329 SR_API struct sr_trigger *sr_session_trigger_get(struct sr_session *session)
334 return session->trigger;
338 * Set the trigger of this session.
340 * @param session The session to use. Must not be NULL.
341 * @param trig The trigger to assign to this session. Can be NULL.
343 * @retval SR_OK Success.
344 * @retval SR_ERR_ARG Invalid argument.
348 SR_API int sr_session_trigger_set(struct sr_session *session, struct sr_trigger *trig)
353 session->trigger = trig;
359 * Call every device in the current session's callback.
361 * For sessions not driven by select loops such as sr_session_run(),
362 * but driven by another scheduler, this can be used to poll the devices
363 * from within that scheduler.
365 * @param session The session to use. Must not be NULL.
366 * @param block If TRUE, this call will wait for any of the session's
367 * sources to fire an event on the file descriptors, or
368 * any of their timeouts to activate. In other words, this
369 * can be used as a select loop.
370 * If FALSE, all sources have their callback run, regardless
371 * of file descriptor or timeout status.
373 * @retval SR_OK Success.
374 * @retval SR_ERR Error occured.
376 static int sr_session_iteration(struct sr_session *session, gboolean block)
381 ret = g_poll(session->pollfds, session->num_sources,
382 block ? session->source_timeout : 0);
383 for (i = 0; i < session->num_sources; i++) {
384 if (session->pollfds[i].revents > 0 || (ret == 0
385 && session->source_timeout == session->sources[i].timeout)) {
387 * Invoke the source's callback on an event,
388 * or if the poll timed out and this source
389 * asked for that timeout.
391 if (!session->sources[i].cb(session->pollfds[i].fd,
392 session->pollfds[i].revents,
393 session->sources[i].cb_data))
394 sr_session_source_remove(session,
395 session->sources[i].poll_object);
398 * We want to take as little time as possible to stop
399 * the session if we have been told to do so. Therefore,
400 * we check the flag after processing every source, not
401 * just once per main event loop.
403 g_mutex_lock(&session->stop_mutex);
404 if (session->abort_session) {
405 sr_session_stop_sync(session);
406 /* But once is enough. */
407 session->abort_session = FALSE;
409 g_mutex_unlock(&session->stop_mutex);
415 static int verify_trigger(struct sr_trigger *trigger)
417 struct sr_trigger_stage *stage;
418 struct sr_trigger_match *match;
421 if (!trigger->stages) {
422 sr_err("No trigger stages defined.");
426 sr_spew("Checking trigger:");
427 for (l = trigger->stages; l; l = l->next) {
429 if (!stage->matches) {
430 sr_err("Stage %d has no matches defined.", stage->stage);
433 for (m = stage->matches; m; m = m->next) {
435 if (!match->channel) {
436 sr_err("Stage %d match has no channel.", stage->stage);
440 sr_err("Stage %d match is not defined.", stage->stage);
443 sr_spew("Stage %d match on channel %s, match %d", stage->stage,
444 match->channel->name, match->match);
453 * @param session The session to use. Must not be NULL.
455 * @retval SR_OK Success.
456 * @retval SR_ERR_ARG Invalid session passed.
460 SR_API int sr_session_start(struct sr_session *session)
462 struct sr_dev_inst *sdi;
463 struct sr_channel *ch;
465 int enabled_channels, ret;
468 sr_err("%s: session was NULL", __func__);
472 if (!session->devs) {
473 sr_err("%s: session->devs was NULL; a session "
474 "cannot be started without devices.", __func__);
478 if (session->trigger && verify_trigger(session->trigger) != SR_OK)
481 sr_info("Starting.");
484 for (l = session->devs; l; l = l->next) {
486 enabled_channels = 0;
487 for (c = sdi->channels; c; c = c->next) {
494 if (enabled_channels == 0) {
496 sr_err("%s using connection %s has no enabled channels!",
497 sdi->driver->name, sdi->connection_id);
501 if ((ret = sr_config_commit(sdi)) != SR_OK) {
502 sr_err("Failed to commit device settings before "
503 "starting acquisition (%s)", sr_strerror(ret));
506 if ((ret = sdi->driver->dev_acquisition_start(sdi, sdi)) != SR_OK) {
507 sr_err("%s: could not start an acquisition "
508 "(%s)", __func__, sr_strerror(ret));
513 /* TODO: What if there are multiple devices? Which return code? */
521 * @param session The session to use. Must not be NULL.
523 * @retval SR_OK Success.
524 * @retval SR_ERR_ARG Invalid session passed.
528 SR_API int sr_session_run(struct sr_session *session)
531 sr_err("%s: session was NULL", __func__);
535 if (!session->devs) {
536 /* TODO: Actually the case? */
537 sr_err("%s: session->devs was NULL; a session "
538 "cannot be run without devices.", __func__);
541 session->running = TRUE;
545 /* Do we have real sources? */
546 if (session->num_sources == 1 && session->pollfds[0].fd == -1) {
547 /* Dummy source, freewheel over it. */
548 while (session->num_sources)
549 session->sources[0].cb(-1, 0, session->sources[0].cb_data);
551 /* Real sources, use g_poll() main loop. */
552 while (session->num_sources)
553 sr_session_iteration(session, TRUE);
562 * The session is stopped immediately, with all acquisition sessions stopped
563 * and hardware drivers cleaned up.
565 * This must be called from within the session thread, to prevent freeing
566 * resources that the session thread will try to use.
568 * @param session The session to use. Must not be NULL.
570 * @retval SR_OK Success.
571 * @retval SR_ERR_ARG Invalid session passed.
575 SR_PRIV int sr_session_stop_sync(struct sr_session *session)
577 struct sr_dev_inst *sdi;
581 sr_err("%s: session was NULL", __func__);
585 sr_info("Stopping.");
587 for (l = session->devs; l; l = l->next) {
590 if (sdi->driver->dev_acquisition_stop)
591 sdi->driver->dev_acquisition_stop(sdi, sdi);
594 session->running = FALSE;
602 * The session is stopped immediately, with all acquisition sessions being
603 * stopped and hardware drivers cleaned up.
605 * If the session is run in a separate thread, this function will not block
606 * until the session is finished executing. It is the caller's responsibility
607 * to wait for the session thread to return before assuming that the session is
608 * completely decommissioned.
610 * @param session The session to use. Must not be NULL.
612 * @retval SR_OK Success.
613 * @retval SR_ERR_ARG Invalid session passed.
617 SR_API int sr_session_stop(struct sr_session *session)
620 sr_err("%s: session was NULL", __func__);
624 g_mutex_lock(&session->stop_mutex);
625 session->abort_session = TRUE;
626 g_mutex_unlock(&session->stop_mutex);
634 * @param packet The packet to show debugging information for.
636 static void datafeed_dump(const struct sr_datafeed_packet *packet)
638 const struct sr_datafeed_logic *logic;
639 const struct sr_datafeed_analog *analog;
640 const struct sr_datafeed_analog2 *analog2;
642 switch (packet->type) {
644 sr_dbg("bus: Received SR_DF_HEADER packet.");
647 sr_dbg("bus: Received SR_DF_TRIGGER packet.");
650 sr_dbg("bus: Received SR_DF_META packet.");
653 logic = packet->payload;
654 sr_dbg("bus: Received SR_DF_LOGIC packet (%" PRIu64 " bytes, "
655 "unitsize = %d).", logic->length, logic->unitsize);
658 analog = packet->payload;
659 sr_dbg("bus: Received SR_DF_ANALOG packet (%d samples).",
660 analog->num_samples);
663 analog2 = packet->payload;
664 sr_dbg("bus: Received SR_DF_ANALOG2 packet (%d samples).",
665 analog2->num_samples);
668 sr_dbg("bus: Received SR_DF_END packet.");
670 case SR_DF_FRAME_BEGIN:
671 sr_dbg("bus: Received SR_DF_FRAME_BEGIN packet.");
673 case SR_DF_FRAME_END:
674 sr_dbg("bus: Received SR_DF_FRAME_END packet.");
677 sr_dbg("bus: Received unknown packet type: %d.", packet->type);
683 * Send a packet to whatever is listening on the datafeed bus.
685 * Hardware drivers use this to send a data packet to the frontend.
688 * @param packet The datafeed packet to send to the session bus.
690 * @retval SR_OK Success.
691 * @retval SR_ERR_ARG Invalid argument.
695 SR_PRIV int sr_session_send(const struct sr_dev_inst *sdi,
696 const struct sr_datafeed_packet *packet)
699 struct datafeed_callback *cb_struct;
702 sr_err("%s: sdi was NULL", __func__);
707 sr_err("%s: packet was NULL", __func__);
712 sr_err("%s: session was NULL", __func__);
716 for (l = sdi->session->datafeed_callbacks; l; l = l->next) {
717 if (sr_log_loglevel_get() >= SR_LOG_DBG)
718 datafeed_dump(packet);
720 cb_struct->cb(sdi, packet, cb_struct->cb_data);
727 * Add an event source for a file descriptor.
729 * @param session The session to use. Must not be NULL.
730 * @param pollfd The GPollFD.
731 * @param[in] timeout Max time to wait before the callback is called,
733 * @param cb Callback function to add. Must not be NULL.
734 * @param cb_data Data for the callback function. Can be NULL.
735 * @param poll_object TODO.
737 * @retval SR_OK Success.
738 * @retval SR_ERR_ARG Invalid argument.
740 static int _sr_session_source_add(struct sr_session *session, GPollFD *pollfd,
741 int timeout, sr_receive_data_callback cb, void *cb_data, gintptr poll_object)
743 struct source *new_sources, *s;
744 GPollFD *new_pollfds;
747 sr_err("%s: cb was NULL", __func__);
751 /* Note: cb_data can be NULL, that's not a bug. */
753 new_pollfds = g_realloc(session->pollfds,
754 sizeof(GPollFD) * (session->num_sources + 1));
755 new_sources = g_realloc(session->sources, sizeof(struct source) *
756 (session->num_sources + 1));
758 new_pollfds[session->num_sources] = *pollfd;
759 s = &new_sources[session->num_sources++];
760 s->timeout = timeout;
762 s->cb_data = cb_data;
763 s->poll_object = poll_object;
764 session->pollfds = new_pollfds;
765 session->sources = new_sources;
767 if (timeout != session->source_timeout && timeout > 0
768 && (session->source_timeout == -1 || timeout < session->source_timeout))
769 session->source_timeout = timeout;
775 * Add an event source for a file descriptor.
777 * @param session The session to use. Must not be NULL.
778 * @param fd The file descriptor.
779 * @param events Events to check for.
780 * @param timeout Max time to wait before the callback is called, ignored if 0.
781 * @param cb Callback function to add. Must not be NULL.
782 * @param cb_data Data for the callback function. Can be NULL.
784 * @retval SR_OK Success.
785 * @retval SR_ERR_ARG Invalid argument.
789 SR_API int sr_session_source_add(struct sr_session *session, int fd,
790 int events, int timeout, sr_receive_data_callback cb, void *cb_data)
797 return _sr_session_source_add(session, &p, timeout, cb, cb_data, (gintptr)fd);
801 * Add an event source for a GPollFD.
803 * @param session The session to use. Must not be NULL.
804 * @param pollfd The GPollFD.
805 * @param timeout Max time to wait before the callback is called, ignored if 0.
806 * @param cb Callback function to add. Must not be NULL.
807 * @param cb_data Data for the callback function. Can be NULL.
809 * @retval SR_OK Success.
810 * @retval SR_ERR_ARG Invalid argument.
814 SR_API int sr_session_source_add_pollfd(struct sr_session *session,
815 GPollFD *pollfd, int timeout, sr_receive_data_callback cb,
818 return _sr_session_source_add(session, pollfd, timeout, cb,
819 cb_data, (gintptr)pollfd);
823 * Add an event source for a GIOChannel.
825 * @param session The session to use. Must not be NULL.
826 * @param channel The GIOChannel.
827 * @param events Events to poll on.
828 * @param timeout Max time to wait before the callback is called, ignored if 0.
829 * @param cb Callback function to add. Must not be NULL.
830 * @param cb_data Data for the callback function. Can be NULL.
832 * @retval SR_OK Success.
833 * @retval SR_ERR_ARG Invalid argument.
837 SR_API int sr_session_source_add_channel(struct sr_session *session,
838 GIOChannel *channel, int events, int timeout,
839 sr_receive_data_callback cb, void *cb_data)
844 g_io_channel_win32_make_pollfd(channel, events, &p);
846 p.fd = g_io_channel_unix_get_fd(channel);
850 return _sr_session_source_add(session, &p, timeout, cb, cb_data, (gintptr)channel);
854 * Remove the source belonging to the specified channel.
856 * @param session The session to use. Must not be NULL.
857 * @param poll_object The channel for which the source should be removed.
859 * @retval SR_OK Success
860 * @retval SR_ERR_ARG Invalid arguments
861 * @retval SR_ERR_BUG Internal error
863 static int _sr_session_source_remove(struct sr_session *session, gintptr poll_object)
867 if (!session->sources || !session->num_sources) {
868 sr_err("%s: sources was NULL", __func__);
872 for (old = 0; old < session->num_sources; old++) {
873 if (session->sources[old].poll_object == poll_object)
877 /* fd not found, nothing to do */
878 if (old == session->num_sources)
881 session->num_sources--;
883 if (old != session->num_sources) {
884 memmove(&session->pollfds[old], &session->pollfds[old + 1],
885 (session->num_sources - old) * sizeof(GPollFD));
886 memmove(&session->sources[old], &session->sources[old + 1],
887 (session->num_sources - old) * sizeof(struct source));
890 session->pollfds = g_realloc(session->pollfds, sizeof(GPollFD) * session->num_sources);
891 session->sources = g_realloc(session->sources, sizeof(struct source) * session->num_sources);
897 * Remove the source belonging to the specified file descriptor.
899 * @param session The session to use. Must not be NULL.
900 * @param fd The file descriptor for which the source should be removed.
902 * @retval SR_OK Success
903 * @retval SR_ERR_ARG Invalid argument
904 * @retval SR_ERR_BUG Internal error.
908 SR_API int sr_session_source_remove(struct sr_session *session, int fd)
910 return _sr_session_source_remove(session, (gintptr)fd);
914 * Remove the source belonging to the specified poll descriptor.
916 * @param session The session to use. Must not be NULL.
917 * @param pollfd The poll descriptor for which the source should be removed.
919 * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
920 * SR_ERR_MALLOC upon memory allocation errors, SR_ERR_BUG upon
925 SR_API int sr_session_source_remove_pollfd(struct sr_session *session,
928 return _sr_session_source_remove(session, (gintptr)pollfd);
932 * Remove the source belonging to the specified channel.
934 * @param session The session to use. Must not be NULL.
935 * @param channel The channel for which the source should be removed.
937 * @retval SR_OK Success.
938 * @retval SR_ERR_ARG Invalid argument.
939 * @return SR_ERR_BUG Internal error.
943 SR_API int sr_session_source_remove_channel(struct sr_session *session,
946 return _sr_session_source_remove(session, (gintptr)channel);
949 static void *copy_src(struct sr_config *src)
951 struct sr_config *new_src;
953 new_src = g_malloc(sizeof(struct sr_config));
954 memcpy(new_src, src, sizeof(struct sr_config));
955 g_variant_ref(src->data);
960 SR_PRIV int sr_packet_copy(const struct sr_datafeed_packet *packet,
961 struct sr_datafeed_packet **copy)
963 const struct sr_datafeed_meta *meta;
964 struct sr_datafeed_meta *meta_copy;
965 const struct sr_datafeed_logic *logic;
966 struct sr_datafeed_logic *logic_copy;
967 const struct sr_datafeed_analog *analog;
968 struct sr_datafeed_analog *analog_copy;
971 *copy = g_malloc0(sizeof(struct sr_datafeed_packet));
972 (*copy)->type = packet->type;
974 switch (packet->type) {
980 payload = g_malloc(sizeof(struct sr_datafeed_header));
981 memcpy(payload, packet->payload, sizeof(struct sr_datafeed_header));
982 (*copy)->payload = payload;
985 meta = packet->payload;
986 meta_copy = g_malloc(sizeof(struct sr_datafeed_meta));
987 meta_copy->config = g_slist_copy_deep(meta->config,
988 (GCopyFunc)copy_src, NULL);
989 (*copy)->payload = meta_copy;
992 logic = packet->payload;
993 logic_copy = g_malloc(sizeof(logic));
994 logic_copy->length = logic->length;
995 logic_copy->unitsize = logic->unitsize;
996 memcpy(logic_copy->data, logic->data, logic->length * logic->unitsize);
997 (*copy)->payload = logic_copy;
1000 analog = packet->payload;
1001 analog_copy = g_malloc(sizeof(analog));
1002 analog_copy->channels = g_slist_copy(analog->channels);
1003 analog_copy->num_samples = analog->num_samples;
1004 analog_copy->mq = analog->mq;
1005 analog_copy->unit = analog->unit;
1006 analog_copy->mqflags = analog->mqflags;
1007 memcpy(analog_copy->data, analog->data,
1008 analog->num_samples * sizeof(float));
1009 (*copy)->payload = analog_copy;
1012 sr_err("Unknown packet type %d", packet->type);
1019 void sr_packet_free(struct sr_datafeed_packet *packet)
1021 const struct sr_datafeed_meta *meta;
1022 const struct sr_datafeed_logic *logic;
1023 const struct sr_datafeed_analog *analog;
1024 struct sr_config *src;
1027 switch (packet->type) {
1033 /* Payload is a simple struct. */
1034 g_free((void *)packet->payload);
1037 meta = packet->payload;
1038 for (l = meta->config; l; l = l->next) {
1040 g_variant_unref(src->data);
1043 g_slist_free(meta->config);
1044 g_free((void *)packet->payload);
1047 logic = packet->payload;
1048 g_free(logic->data);
1049 g_free((void *)packet->payload);
1052 analog = packet->payload;
1053 g_slist_free(analog->channels);
1054 g_free(analog->data);
1055 g_free((void *)packet->payload);
1058 sr_err("Unknown packet type %d", packet->type);