session.c

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