libsigrok  0.2.2
sigrok hardware access and backend library
 All Data Structures Files Functions Variables Typedefs Enumerator Macros Groups Pages
session.c
Go to the documentation of this file.
1 /*
2  * This file is part of the libsigrok project.
3  *
4  * Copyright (C) 2010-2012 Bert Vermeulen <bert@biot.com>
5  *
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.
10  *
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.
15  *
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/>.
18  */
19 
20 #include <stdio.h>
21 #include <stdlib.h>
22 #include <unistd.h>
23 #include <string.h>
24 #include <glib.h>
25 #include "libsigrok.h"
26 #include "libsigrok-internal.h"
27 
28 /* Message logging helpers with subsystem-specific prefix string. */
29 #define LOG_PREFIX "session: "
30 #define sr_log(l, s, args...) sr_log(l, LOG_PREFIX s, ## args)
31 #define sr_spew(s, args...) sr_spew(LOG_PREFIX s, ## args)
32 #define sr_dbg(s, args...) sr_dbg(LOG_PREFIX s, ## args)
33 #define sr_info(s, args...) sr_info(LOG_PREFIX s, ## args)
34 #define sr_warn(s, args...) sr_warn(LOG_PREFIX s, ## args)
35 #define sr_err(s, args...) sr_err(LOG_PREFIX s, ## args)
36 
37 /**
38  * @file
39  *
40  * Creating, using, or destroying libsigrok sessions.
41  */
42 
43 /**
44  * @defgroup grp_session Session handling
45  *
46  * Creating, using, or destroying libsigrok sessions.
47  *
48  * @{
49  */
50 
51 struct source {
52  int timeout;
54  void *cb_data;
55 
56  /* This is used to keep track of the object (fd, pollfd or channel) which is
57  * being polled and will be used to match the source when removing it again.
58  */
59  gintptr poll_object;
60 };
61 
62 struct datafeed_callback {
64  void *cb_data;
65 };
66 
67 /* There can only be one session at a time. */
68 /* 'session' is not static, it's used elsewhere (via 'extern'). */
70 
71 /**
72  * Create a new session.
73  *
74  * @todo Should it use the file-global "session" variable or take an argument?
75  * The same question applies to all the other session functions.
76  *
77  * @return A pointer to the newly allocated session, or NULL upon errors.
78  */
80 {
81  if (!(session = g_try_malloc0(sizeof(struct sr_session)))) {
82  sr_err("Session malloc failed.");
83  return NULL;
84  }
85 
86  session->source_timeout = -1;
87  session->running = FALSE;
88  session->abort_session = FALSE;
89  g_mutex_init(&session->stop_mutex);
90 
91  return session;
92 }
93 
94 /**
95  * Destroy the current session.
96  *
97  * This frees up all memory used by the session.
98  *
99  * @return SR_OK upon success, SR_ERR_BUG if no session exists.
100  */
102 {
103  if (!session) {
104  sr_err("%s: session was NULL", __func__);
105  return SR_ERR_BUG;
106  }
107 
109 
110  /* TODO: Error checks needed? */
111 
112  g_mutex_clear(&session->stop_mutex);
113 
114  g_free(session);
115  session = NULL;
116 
117  return SR_OK;
118 }
119 
120 /**
121  * Remove all the devices from the current session.
122  *
123  * The session itself (i.e., the struct sr_session) is not free'd and still
124  * exists after this function returns.
125  *
126  * @return SR_OK upon success, SR_ERR_BUG if no session exists.
127  */
129 {
130  if (!session) {
131  sr_err("%s: session was NULL", __func__);
132  return SR_ERR_BUG;
133  }
134 
135  g_slist_free(session->devs);
136  session->devs = NULL;
137 
138  return SR_OK;
139 }
140 
141 /**
142  * Add a device instance to the current session.
143  *
144  * @param sdi The device instance to add to the current session. Must not
145  * be NULL. Also, sdi->driver and sdi->driver->dev_open must
146  * not be NULL.
147  *
148  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments.
149  */
150 SR_API int sr_session_dev_add(const struct sr_dev_inst *sdi)
151 {
152  int ret;
153 
154  if (!sdi) {
155  sr_err("%s: sdi was NULL", __func__);
156  return SR_ERR_ARG;
157  }
158 
159  if (!session) {
160  sr_err("%s: session was NULL", __func__);
161  return SR_ERR_BUG;
162  }
163 
164  /* If sdi->driver is NULL, this is a virtual device. */
165  if (!sdi->driver) {
166  sr_dbg("%s: sdi->driver was NULL, this seems to be "
167  "a virtual device; continuing", __func__);
168  /* Just add the device, don't run dev_open(). */
169  session->devs = g_slist_append(session->devs, (gpointer)sdi);
170  return SR_OK;
171  }
172 
173  /* sdi->driver is non-NULL (i.e. we have a real device). */
174  if (!sdi->driver->dev_open) {
175  sr_err("%s: sdi->driver->dev_open was NULL", __func__);
176  return SR_ERR_BUG;
177  }
178 
179  session->devs = g_slist_append(session->devs, (gpointer)sdi);
180 
181  if (session->running) {
182  /* Adding a device to a running session. Start acquisition
183  * on that device now. */
184  if ((ret = sdi->driver->dev_acquisition_start(sdi,
185  (void *)sdi)) != SR_OK)
186  sr_err("Failed to start acquisition of device in "
187  "running session: %d", ret);
188  }
189 
190  return SR_OK;
191 }
192 
193 /**
194  * Remove all datafeed callbacks in the current session.
195  *
196  * @return SR_OK upon success, SR_ERR_BUG if no session exists.
197  */
199 {
200  if (!session) {
201  sr_err("%s: session was NULL", __func__);
202  return SR_ERR_BUG;
203  }
204 
205  g_slist_free_full(session->datafeed_callbacks, g_free);
206  session->datafeed_callbacks = NULL;
207 
208  return SR_OK;
209 }
210 
211 /**
212  * Add a datafeed callback to the current session.
213  *
214  * @param cb Function to call when a chunk of data is received.
215  * Must not be NULL.
216  * @param cb_data Opaque pointer passed in by the caller.
217  *
218  * @return SR_OK upon success, SR_ERR_BUG if no session exists.
219  */
221 {
222  struct datafeed_callback *cb_struct;
223 
224  if (!session) {
225  sr_err("%s: session was NULL", __func__);
226  return SR_ERR_BUG;
227  }
228 
229  if (!cb) {
230  sr_err("%s: cb was NULL", __func__);
231  return SR_ERR_ARG;
232  }
233 
234  if (!(cb_struct = g_try_malloc0(sizeof(struct datafeed_callback))))
235  return SR_ERR_MALLOC;
236 
237  cb_struct->cb = cb;
238  cb_struct->cb_data = cb_data;
239 
240  session->datafeed_callbacks =
241  g_slist_append(session->datafeed_callbacks, cb_struct);
242 
243  return SR_OK;
244 }
245 
246 /**
247  * Call every device in the session's callback.
248  *
249  * For sessions not driven by select loops such as sr_session_run(),
250  * but driven by another scheduler, this can be used to poll the devices
251  * from within that scheduler.
252  *
253  * @param block If TRUE, this call will wait for any of the session's
254  * sources to fire an event on the file descriptors, or
255  * any of their timeouts to activate. In other words, this
256  * can be used as a select loop.
257  * If FALSE, all sources have their callback run, regardless
258  * of file descriptor or timeout status.
259  *
260  * @return SR_OK upon success, SR_ERR on errors.
261  */
262 static int sr_session_iteration(gboolean block)
263 {
264  unsigned int i;
265  int ret;
266 
267  ret = g_poll(session->pollfds, session->num_sources,
268  block ? session->source_timeout : 0);
269  for (i = 0; i < session->num_sources; i++) {
270  if (session->pollfds[i].revents > 0 || (ret == 0
271  && session->source_timeout == session->sources[i].timeout)) {
272  /*
273  * Invoke the source's callback on an event,
274  * or if the poll timed out and this source
275  * asked for that timeout.
276  */
277  if (!session->sources[i].cb(session->pollfds[i].fd,
278  session->pollfds[i].revents,
279  session->sources[i].cb_data))
280  sr_session_source_remove(session->sources[i].poll_object);
281  }
282  /*
283  * We want to take as little time as possible to stop
284  * the session if we have been told to do so. Therefore,
285  * we check the flag after processing every source, not
286  * just once per main event loop.
287  */
288  g_mutex_lock(&session->stop_mutex);
289  if (session->abort_session) {
290  sr_session_stop_sync();
291  /* But once is enough. */
292  session->abort_session = FALSE;
293  }
294  g_mutex_unlock(&session->stop_mutex);
295  }
296 
297  return SR_OK;
298 }
299 
300 /**
301  * Start a session.
302  *
303  * There can only be one session at a time.
304  *
305  * @return SR_OK upon success, SR_ERR upon errors.
306  */
308 {
309  struct sr_dev_inst *sdi;
310  GSList *l;
311  int ret;
312 
313  if (!session) {
314  sr_err("%s: session was NULL; a session must be "
315  "created before starting it.", __func__);
316  return SR_ERR_BUG;
317  }
318 
319  if (!session->devs) {
320  sr_err("%s: session->devs was NULL; a session "
321  "cannot be started without devices.", __func__);
322  return SR_ERR_BUG;
323  }
324 
325  sr_info("Starting.");
326 
327  ret = SR_OK;
328  for (l = session->devs; l; l = l->next) {
329  sdi = l->data;
330  if ((ret = sdi->driver->dev_acquisition_start(sdi, sdi)) != SR_OK) {
331  sr_err("%s: could not start an acquisition "
332  "(%s)", __func__, sr_strerror(ret));
333  break;
334  }
335  }
336 
337  /* TODO: What if there are multiple devices? Which return code? */
338 
339  return ret;
340 }
341 
342 /**
343  * Run the session.
344  *
345  * @return SR_OK upon success, SR_ERR_BUG upon errors.
346  */
348 {
349  if (!session) {
350  sr_err("%s: session was NULL; a session must be "
351  "created first, before running it.", __func__);
352  return SR_ERR_BUG;
353  }
354 
355  if (!session->devs) {
356  /* TODO: Actually the case? */
357  sr_err("%s: session->devs was NULL; a session "
358  "cannot be run without devices.", __func__);
359  return SR_ERR_BUG;
360  }
361  session->running = TRUE;
362 
363  sr_info("Running.");
364 
365  /* Do we have real sources? */
366  if (session->num_sources == 1 && session->pollfds[0].fd == -1) {
367  /* Dummy source, freewheel over it. */
368  while (session->num_sources)
369  session->sources[0].cb(-1, 0, session->sources[0].cb_data);
370  } else {
371  /* Real sources, use g_poll() main loop. */
372  while (session->num_sources)
373  sr_session_iteration(TRUE);
374  }
375 
376  return SR_OK;
377 }
378 
379 /**
380  * Stop the current session.
381  *
382  * The current session is stopped immediately, with all acquisition sessions
383  * being stopped and hardware drivers cleaned up.
384  *
385  * This must be called from within the session thread, to prevent freeing
386  * resources that the session thread will try to use.
387  *
388  * @return SR_OK upon success, SR_ERR_BUG if no session exists.
389  *
390  * @private
391  */
392 SR_PRIV int sr_session_stop_sync(void)
393 {
394  struct sr_dev_inst *sdi;
395  GSList *l;
396 
397  if (!session) {
398  sr_err("%s: session was NULL", __func__);
399  return SR_ERR_BUG;
400  }
401 
402  sr_info("Stopping.");
403 
404  for (l = session->devs; l; l = l->next) {
405  sdi = l->data;
406  if (sdi->driver) {
407  if (sdi->driver->dev_acquisition_stop)
408  sdi->driver->dev_acquisition_stop(sdi, sdi);
409  }
410  }
411  session->running = FALSE;
412 
413  return SR_OK;
414 }
415 
416 /**
417  * Stop the current session.
418  *
419  * The current session is stopped immediately, with all acquisition sessions
420  * being stopped and hardware drivers cleaned up.
421  *
422  * If the session is run in a separate thread, this function will not block
423  * until the session is finished executing. It is the caller's responsibility
424  * to wait for the session thread to return before assuming that the session is
425  * completely decommissioned.
426  *
427  * @return SR_OK upon success, SR_ERR_BUG if no session exists.
428  */
430 {
431  if (!session) {
432  sr_err("%s: session was NULL", __func__);
433  return SR_ERR_BUG;
434  }
435 
436  g_mutex_lock(&session->stop_mutex);
437  session->abort_session = TRUE;
438  g_mutex_unlock(&session->stop_mutex);
439 
440  return SR_OK;
441 }
442 
443 /**
444  * Debug helper.
445  *
446  * @param packet The packet to show debugging information for.
447  */
448 static void datafeed_dump(const struct sr_datafeed_packet *packet)
449 {
450  const struct sr_datafeed_logic *logic;
451  const struct sr_datafeed_analog *analog;
452 
453  switch (packet->type) {
454  case SR_DF_HEADER:
455  sr_dbg("bus: Received SR_DF_HEADER packet.");
456  break;
457  case SR_DF_TRIGGER:
458  sr_dbg("bus: Received SR_DF_TRIGGER packet.");
459  break;
460  case SR_DF_META:
461  sr_dbg("bus: Received SR_DF_META packet.");
462  break;
463  case SR_DF_LOGIC:
464  logic = packet->payload;
465  sr_dbg("bus: Received SR_DF_LOGIC packet (%" PRIu64 " bytes).",
466  logic->length);
467  break;
468  case SR_DF_ANALOG:
469  analog = packet->payload;
470  sr_dbg("bus: Received SR_DF_ANALOG packet (%d samples).",
471  analog->num_samples);
472  break;
473  case SR_DF_END:
474  sr_dbg("bus: Received SR_DF_END packet.");
475  break;
476  case SR_DF_FRAME_BEGIN:
477  sr_dbg("bus: Received SR_DF_FRAME_BEGIN packet.");
478  break;
479  case SR_DF_FRAME_END:
480  sr_dbg("bus: Received SR_DF_FRAME_END packet.");
481  break;
482  default:
483  sr_dbg("bus: Received unknown packet type: %d.", packet->type);
484  break;
485  }
486 }
487 
488 /**
489  * Send a packet to whatever is listening on the datafeed bus.
490  *
491  * Hardware drivers use this to send a data packet to the frontend.
492  *
493  * @param sdi TODO.
494  * @param packet The datafeed packet to send to the session bus.
495  *
496  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments.
497  *
498  * @private
499  */
500 SR_PRIV int sr_session_send(const struct sr_dev_inst *sdi,
501  const struct sr_datafeed_packet *packet)
502 {
503  GSList *l;
504  struct datafeed_callback *cb_struct;
505 
506  if (!sdi) {
507  sr_err("%s: sdi was NULL", __func__);
508  return SR_ERR_ARG;
509  }
510 
511  if (!packet) {
512  sr_err("%s: packet was NULL", __func__);
513  return SR_ERR_ARG;
514  }
515 
516  for (l = session->datafeed_callbacks; l; l = l->next) {
518  datafeed_dump(packet);
519  cb_struct = l->data;
520  cb_struct->cb(sdi, packet, cb_struct->cb_data);
521  }
522 
523  return SR_OK;
524 }
525 
526 /**
527  * Add an event source for a file descriptor.
528  *
529  * @param pollfd The GPollFD.
530  * @param timeout Max time to wait before the callback is called, ignored if 0.
531  * @param cb Callback function to add. Must not be NULL.
532  * @param cb_data Data for the callback function. Can be NULL.
533  * @param poll_object TODO.
534  *
535  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
536  * SR_ERR_MALLOC upon memory allocation errors.
537  */
538 static int _sr_session_source_add(GPollFD *pollfd, int timeout,
539  sr_receive_data_callback_t cb, void *cb_data, gintptr poll_object)
540 {
541  struct source *new_sources, *s;
542  GPollFD *new_pollfds;
543 
544  if (!cb) {
545  sr_err("%s: cb was NULL", __func__);
546  return SR_ERR_ARG;
547  }
548 
549  /* Note: cb_data can be NULL, that's not a bug. */
550 
551  new_pollfds = g_try_realloc(session->pollfds,
552  sizeof(GPollFD) * (session->num_sources + 1));
553  if (!new_pollfds) {
554  sr_err("%s: new_pollfds malloc failed", __func__);
555  return SR_ERR_MALLOC;
556  }
557 
558  new_sources = g_try_realloc(session->sources, sizeof(struct source) *
559  (session->num_sources + 1));
560  if (!new_sources) {
561  sr_err("%s: new_sources malloc failed", __func__);
562  return SR_ERR_MALLOC;
563  }
564 
565  new_pollfds[session->num_sources] = *pollfd;
566  s = &new_sources[session->num_sources++];
567  s->timeout = timeout;
568  s->cb = cb;
569  s->cb_data = cb_data;
570  s->poll_object = poll_object;
571  session->pollfds = new_pollfds;
572  session->sources = new_sources;
573 
574  if (timeout != session->source_timeout && timeout > 0
575  && (session->source_timeout == -1 || timeout < session->source_timeout))
576  session->source_timeout = timeout;
577 
578  return SR_OK;
579 }
580 
581 /**
582  * Add an event source for a file descriptor.
583  *
584  * @param fd The file descriptor.
585  * @param events Events to check for.
586  * @param timeout Max time to wait before the callback is called, ignored if 0.
587  * @param cb Callback function to add. Must not be NULL.
588  * @param cb_data Data for the callback function. Can be NULL.
589  *
590  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
591  * SR_ERR_MALLOC upon memory allocation errors.
592  */
593 SR_API int sr_session_source_add(int fd, int events, int timeout,
594  sr_receive_data_callback_t cb, void *cb_data)
595 {
596  GPollFD p;
597 
598  p.fd = fd;
599  p.events = events;
600 
601  return _sr_session_source_add(&p, timeout, cb, cb_data, (gintptr)fd);
602 }
603 
604 /**
605  * Add an event source for a GPollFD.
606  *
607  * @param pollfd The GPollFD.
608  * @param timeout Max time to wait before the callback is called, ignored if 0.
609  * @param cb Callback function to add. Must not be NULL.
610  * @param cb_data Data for the callback function. Can be NULL.
611  *
612  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
613  * SR_ERR_MALLOC upon memory allocation errors.
614  */
615 SR_API int sr_session_source_add_pollfd(GPollFD *pollfd, int timeout,
616  sr_receive_data_callback_t cb, void *cb_data)
617 {
618  return _sr_session_source_add(pollfd, timeout, cb,
619  cb_data, (gintptr)pollfd);
620 }
621 
622 /**
623  * Add an event source for a GIOChannel.
624  *
625  * @param channel The GIOChannel.
626  * @param events Events to poll on.
627  * @param timeout Max time to wait before the callback is called, ignored if 0.
628  * @param cb Callback function to add. Must not be NULL.
629  * @param cb_data Data for the callback function. Can be NULL.
630  *
631  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
632  * SR_ERR_MALLOC upon memory allocation errors.
633  */
634 SR_API int sr_session_source_add_channel(GIOChannel *channel, int events,
635  int timeout, sr_receive_data_callback_t cb, void *cb_data)
636 {
637  GPollFD p;
638 
639 #ifdef _WIN32
640  g_io_channel_win32_make_pollfd(channel, events, &p);
641 #else
642  p.fd = g_io_channel_unix_get_fd(channel);
643  p.events = events;
644 #endif
645 
646  return _sr_session_source_add(&p, timeout, cb, cb_data, (gintptr)channel);
647 }
648 
649 /**
650  * Remove the source belonging to the specified channel.
651  *
652  * @todo Add more error checks and logging.
653  *
654  * @param channel The channel for which the source should be removed.
655  *
656  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
657  * SR_ERR_MALLOC upon memory allocation errors, SR_ERR_BUG upon
658  * internal errors.
659  */
660 static int _sr_session_source_remove(gintptr poll_object)
661 {
662  struct source *new_sources;
663  GPollFD *new_pollfds;
664  unsigned int old;
665 
666  if (!session->sources || !session->num_sources) {
667  sr_err("%s: sources was NULL", __func__);
668  return SR_ERR_BUG;
669  }
670 
671  for (old = 0; old < session->num_sources; old++) {
672  if (session->sources[old].poll_object == poll_object)
673  break;
674  }
675 
676  /* fd not found, nothing to do */
677  if (old == session->num_sources)
678  return SR_OK;
679 
680  session->num_sources -= 1;
681 
682  if (old != session->num_sources) {
683  memmove(&session->pollfds[old], &session->pollfds[old+1],
684  (session->num_sources - old) * sizeof(GPollFD));
685  memmove(&session->sources[old], &session->sources[old+1],
686  (session->num_sources - old) * sizeof(struct source));
687  }
688 
689  new_pollfds = g_try_realloc(session->pollfds, sizeof(GPollFD) * session->num_sources);
690  if (!new_pollfds && session->num_sources > 0) {
691  sr_err("%s: new_pollfds malloc failed", __func__);
692  return SR_ERR_MALLOC;
693  }
694 
695  new_sources = g_try_realloc(session->sources, sizeof(struct source) * session->num_sources);
696  if (!new_sources && session->num_sources > 0) {
697  sr_err("%s: new_sources malloc failed", __func__);
698  return SR_ERR_MALLOC;
699  }
700 
701  session->pollfds = new_pollfds;
702  session->sources = new_sources;
703 
704  return SR_OK;
705 }
706 
707 /**
708  * Remove the source belonging to the specified file descriptor.
709  *
710  * @param fd The file descriptor for which the source should be removed.
711  *
712  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
713  * SR_ERR_MALLOC upon memory allocation errors, SR_ERR_BUG upon
714  * internal errors.
715  */
717 {
718  return _sr_session_source_remove((gintptr)fd);
719 }
720 
721 /**
722  * Remove the source belonging to the specified poll descriptor.
723  *
724  * @param pollfd The poll descriptor for which the source should be removed.
725  *
726  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
727  * SR_ERR_MALLOC upon memory allocation errors, SR_ERR_BUG upon
728  * internal errors.
729  */
731 {
732  return _sr_session_source_remove((gintptr)pollfd);
733 }
734 
735 /**
736  * Remove the source belonging to the specified channel.
737  *
738  * @param channel The channel for which the source should be removed.
739  *
740  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
741  * SR_ERR_MALLOC upon memory allocation errors, SR_ERR_BUG upon
742  * internal errors.
743  */
744 SR_API int sr_session_source_remove_channel(GIOChannel *channel)
745 {
746  return _sr_session_source_remove((gintptr)channel);
747 }
748 
749 /** @} */