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