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         for (l = session->devs; l; l = l->next) {
 275                 sdi = l->data;
 276                 if ((ret = sdi->driver->dev_acquisition_start(sdi, sdi)) != SR_OK) {
 277                         sr_err("session: %s: could not start an acquisition "
 278                                "(%d)", __func__, ret);
 279                         break;
 280                 }
 281         }
 282
 283         /* TODO: What if there are multiple devices? Which return code? */
 284
 285         return ret;
 286 }
 287
 288 /**
 289  * Run the session.
 290  *
 291  * @return SR_OK upon success, SR_ERR_BUG upon errors.
 292  */
 293 SR_API int sr_session_run(void)
 294 {
 295         if (!session) {
 296                 sr_err("session: %s: session was NULL; a session must be "
 297                        "created first, before running it.", __func__);
 298                 return SR_ERR_BUG;
 299         }
 300
 301         if (!session->devs) {
 302                 /* TODO: Actually the case? */
 303                 sr_err("session: %s: session->devs was NULL; a session "
 304                        "cannot be run without devices.", __func__);
 305                 return SR_ERR_BUG;
 306         }
 307
 308         sr_info("session: running");
 309
 310         /* Do we have real sources? */
 311         if (session->num_sources == 1 && session->pollfds[0].fd == -1) {
 312                 /* Dummy source, freewheel over it. */
 313                 while (session->num_sources)
 314                         session->sources[0].cb(-1, 0, session->sources[0].cb_data);
 315         } else {
 316                 /* Real sources, use g_poll() main loop. */
 317                 sr_session_run_poll();
 318         }
 319
 320         return SR_OK;
 321 }
 322
 323 /**
 324  * Halt the current session.
 325  *
 326  * This function is deprecated and should not be used in new code, use
 327  * sr_session_stop() instead. The behaviour of this function is identical to
 328  * sr_session_stop().
 329  *
 330  * @return SR_OK upon success, SR_ERR_BUG if no session exists.
 331  */
 332 SR_API int sr_session_halt(void)
 333 {
 334         return sr_session_stop();
 335 }
 336
 337 /**
 338  * Stop the current session.
 339  *
 340  * The current session is stopped immediately, with all acquisition sessions
 341  * being stopped and hardware drivers cleaned up.
 342  *
 343  * @return SR_OK upon success, SR_ERR_BUG if no session exists.
 344  */
 345 SR_API int sr_session_stop(void)
 346 {
 347         struct sr_dev_inst *sdi;
 348         GSList *l;
 349
 350         if (!session) {
 351                 sr_err("session: %s: session was NULL", __func__);
 352                 return SR_ERR_BUG;
 353         }
 354
 355         sr_info("session: stopping");
 356
 357         for (l = session->devs; l; l = l->next) {
 358                 sdi = l->data;
 359                 if (sdi->driver) {
 360                         if (sdi->driver->dev_acquisition_stop)
 361                                 sdi->driver->dev_acquisition_stop(sdi, sdi);
 362                 }
 363         }
 364
 365         /*
 366          * Some sources may not be necessarily associated with a device.
 367          * Those sources may still be present even after stopping all devices.
 368          * We need to make sure all sources are removed, or we risk running the
 369          * session in an infinite loop.
 370          */
 371         while (session->num_sources)
 372                 sr_session_source_remove(session->sources[0].poll_object);
 373
 374         return SR_OK;
 375 }
 376
 377 /**
 378  * Debug helper.
 379  *
 380  * @param packet The packet to show debugging information for.
 381  */
 382 static void datafeed_dump(const struct sr_datafeed_packet *packet)
 383 {
 384         const struct sr_datafeed_logic *logic;
 385         const struct sr_datafeed_analog *analog;
 386
 387         switch (packet->type) {
 388         case SR_DF_HEADER:
 389                 sr_dbg("bus: received SR_DF_HEADER");
 390                 break;
 391         case SR_DF_TRIGGER:
 392                 sr_dbg("bus: received SR_DF_TRIGGER");
 393                 break;
 394         case SR_DF_META_LOGIC:
 395                 sr_dbg("bus: received SR_DF_META_LOGIC");
 396                 break;
 397         case SR_DF_LOGIC:
 398                 logic = packet->payload;
 399                 /* TODO: Check for logic != NULL. */
 400                 sr_dbg("bus: received SR_DF_LOGIC %" PRIu64 " bytes", logic->length);
 401                 break;
 402         case SR_DF_META_ANALOG:
 403                 sr_dbg("bus: received SR_DF_META_ANALOG");
 404                 break;
 405         case SR_DF_ANALOG:
 406                 analog = packet->payload;
 407                 /* TODO: Check for analog != NULL. */
 408                 sr_dbg("bus: received SR_DF_ANALOG %d samples", analog->num_samples);
 409                 break;
 410         case SR_DF_END:
 411                 sr_dbg("bus: received SR_DF_END");
 412                 break;
 413         case SR_DF_FRAME_BEGIN:
 414                 sr_dbg("bus: received SR_DF_FRAME_BEGIN");
 415                 break;
 416         case SR_DF_FRAME_END:
 417                 sr_dbg("bus: received SR_DF_FRAME_END");
 418                 break;
 419         default:
 420                 sr_dbg("bus: received unknown packet type %d", packet->type);
 421                 break;
 422         }
 423 }
 424
 425 /**
 426  * Send a packet to whatever is listening on the datafeed bus.
 427  *
 428  * Hardware drivers use this to send a data packet to the frontend.
 429  *
 430  * @param sdi TODO.
 431  * @param packet The datafeed packet to send to the session bus.
 432  *
 433  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments.
 434  *
 435  * @private
 436  */
 437 SR_PRIV int sr_session_send(const struct sr_dev_inst *sdi,
 438                             const struct sr_datafeed_packet *packet)
 439 {
 440         GSList *l;
 441         sr_datafeed_callback_t cb;
 442
 443         if (!sdi) {
 444                 sr_err("session: %s: sdi was NULL", __func__);
 445                 return SR_ERR_ARG;
 446         }
 447
 448         if (!packet) {
 449                 sr_err("session: %s: packet was NULL", __func__);
 450                 return SR_ERR_ARG;
 451         }
 452
 453         for (l = session->datafeed_callbacks; l; l = l->next) {
 454                 if (sr_log_loglevel_get() >= SR_LOG_DBG)
 455                         datafeed_dump(packet);
 456                 cb = l->data;
 457                 cb(sdi, packet);
 458         }
 459
 460         return SR_OK;
 461 }
 462
 463 /**
 464  * Add an event source for a file descriptor.
 465  *
 466  * @param pollfd The GPollFD.
 467  * @param timeout Max time to wait before the callback is called, ignored if 0.
 468  * @param cb Callback function to add. Must not be NULL.
 469  * @param cb_data Data for the callback function. Can be NULL.
 470  * @param poll_object TODO.
 471  *
 472  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
 473  *         SR_ERR_MALLOC upon memory allocation errors.
 474  */
 475 static int _sr_session_source_add(GPollFD *pollfd, int timeout,
 476         sr_receive_data_callback_t cb, void *cb_data, gintptr poll_object)
 477 {
 478         struct source *new_sources, *s;
 479         GPollFD *new_pollfds;
 480
 481         if (!cb) {
 482                 sr_err("session: %s: cb was NULL", __func__);
 483                 return SR_ERR_ARG;
 484         }
 485
 486         /* Note: cb_data can be NULL, that's not a bug. */
 487
 488         new_pollfds = g_try_realloc(session->pollfds,
 489                         sizeof(GPollFD) * (session->num_sources + 1));
 490         if (!new_pollfds) {
 491                 sr_err("session: %s: new_pollfds malloc failed", __func__);
 492                 return SR_ERR_MALLOC;
 493         }
 494
 495         new_sources = g_try_realloc(session->sources, sizeof(struct source) *
 496                         (session->num_sources + 1));
 497         if (!new_sources) {
 498                 sr_err("session: %s: new_sources malloc failed", __func__);
 499                 return SR_ERR_MALLOC;
 500         }
 501
 502         new_pollfds[session->num_sources] = *pollfd;
 503         s = &new_sources[session->num_sources++];
 504         s->timeout = timeout;
 505         s->cb = cb;
 506         s->cb_data = cb_data;
 507         s->poll_object = poll_object;
 508         session->pollfds = new_pollfds;
 509         session->sources = new_sources;
 510
 511         if (timeout != session->source_timeout && timeout > 0
 512             && (session->source_timeout == -1 || timeout < session->source_timeout))
 513                 session->source_timeout = timeout;
 514
 515         return SR_OK;
 516 }
 517
 518 /**
 519  * Add an event source for a file descriptor.
 520  *
 521  * @param fd The file descriptor.
 522  * @param events Events to check for.
 523  * @param timeout Max time to wait before the callback is called, ignored if 0.
 524  * @param cb Callback function to add. Must not be NULL.
 525  * @param cb_data Data for the callback function. Can be NULL.
 526  *
 527  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
 528  *         SR_ERR_MALLOC upon memory allocation errors.
 529  */
 530 SR_API int sr_session_source_add(int fd, int events, int timeout,
 531                 sr_receive_data_callback_t cb, void *cb_data)
 532 {
 533         GPollFD p;
 534
 535         p.fd = fd;
 536         p.events = events;
 537
 538         return _sr_session_source_add(&p, timeout, cb, cb_data, (gintptr)fd);
 539 }
 540
 541 /**
 542  * Add an event source for a GPollFD.
 543  *
 544  * @param pollfd The GPollFD.
 545  * @param timeout Max time to wait before the callback is called, ignored if 0.
 546  * @param cb Callback function to add. Must not be NULL.
 547  * @param cb_data Data for the callback function. Can be NULL.
 548  *
 549  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
 550  *         SR_ERR_MALLOC upon memory allocation errors.
 551  */
 552 SR_API int sr_session_source_add_pollfd(GPollFD *pollfd, int timeout,
 553                 sr_receive_data_callback_t cb, void *cb_data)
 554 {
 555         return _sr_session_source_add(pollfd, timeout, cb,
 556                                       cb_data, (gintptr)pollfd);
 557 }
 558
 559 /**
 560  * Add an event source for a GIOChannel.
 561  *
 562  * @param channel The GIOChannel.
 563  * @param events Events to poll on.
 564  * @param timeout Max time to wait before the callback is called, ignored if 0.
 565  * @param cb Callback function to add. Must not be NULL.
 566  * @param cb_data Data for the callback function. Can be NULL.
 567  *
 568  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
 569  *         SR_ERR_MALLOC upon memory allocation errors.
 570  */
 571 SR_API int sr_session_source_add_channel(GIOChannel *channel, int events,
 572                 int timeout, sr_receive_data_callback_t cb, void *cb_data)
 573 {
 574         GPollFD p;
 575
 576 #ifdef _WIN32
 577         g_io_channel_win32_make_pollfd(channel, events, &p);
 578 #else
 579         p.fd = g_io_channel_unix_get_fd(channel);
 580         p.events = events;
 581 #endif
 582
 583         return _sr_session_source_add(&p, timeout, cb, cb_data, (gintptr)channel);
 584 }
 585
 586 /**
 587  * Remove the source belonging to the specified channel.
 588  *
 589  * @todo Add more error checks and logging.
 590  *
 591  * @param channel The channel for which the source should be removed.
 592  *
 593  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
 594  *         SR_ERR_MALLOC upon memory allocation errors, SR_ERR_BUG upon
 595  *         internal errors.
 596  */
 597 static int _sr_session_source_remove(gintptr poll_object)
 598 {
 599         struct source *new_sources;
 600         GPollFD *new_pollfds;
 601         unsigned int old;
 602
 603         if (!session->sources || !session->num_sources) {
 604                 sr_err("session: %s: sources was NULL", __func__);
 605                 return SR_ERR_BUG;
 606         }
 607
 608         for (old = 0; old < session->num_sources; old++) {
 609                 if (session->sources[old].poll_object == poll_object)
 610                         break;
 611         }
 612
 613         /* fd not found, nothing to do */
 614         if (old == session->num_sources)
 615                 return SR_OK;
 616
 617         session->num_sources -= 1;
 618
 619         if (old != session->num_sources) {
 620                 memmove(&session->pollfds[old], &session->pollfds[old+1],
 621                         (session->num_sources - old) * sizeof(GPollFD));
 622                 memmove(&session->sources[old], &session->sources[old+1],
 623                         (session->num_sources - old) * sizeof(struct source));
 624         }
 625
 626         new_pollfds = g_try_realloc(session->pollfds, sizeof(GPollFD) * session->num_sources);
 627         if (!new_pollfds && session->num_sources > 0) {
 628                 sr_err("session: %s: new_pollfds malloc failed", __func__);
 629                 return SR_ERR_MALLOC;
 630         }
 631
 632         new_sources = g_try_realloc(session->sources, sizeof(struct source) * session->num_sources);
 633         if (!new_sources && session->num_sources > 0) {
 634                 sr_err("session: %s: new_sources malloc failed", __func__);
 635                 return SR_ERR_MALLOC;
 636         }
 637
 638         session->pollfds = new_pollfds;
 639         session->sources = new_sources;
 640
 641         return SR_OK;
 642 }
 643
 644 /**
 645  * Remove the source belonging to the specified file descriptor.
 646  *
 647  * @param fd The file descriptor for which the source should be removed.
 648  *
 649  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
 650  *         SR_ERR_MALLOC upon memory allocation errors, SR_ERR_BUG upon
 651  *         internal errors.
 652  */
 653 SR_API int sr_session_source_remove(int fd)
 654 {
 655         return _sr_session_source_remove((gintptr)fd);
 656 }
 657
 658 /**
 659  * Remove the source belonging to the specified poll descriptor.
 660  *
 661  * @param pollfd The poll descriptor for which the source should be removed.
 662  *
 663  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
 664  *         SR_ERR_MALLOC upon memory allocation errors, SR_ERR_BUG upon
 665  *         internal errors.
 666  */
 667 SR_API int sr_session_source_remove_pollfd(GPollFD *pollfd)
 668 {
 669         return _sr_session_source_remove((gintptr)pollfd);
 670 }
 671
 672 /**
 673  * Remove the source belonging to the specified channel.
 674  *
 675  * @param channel The channel for which the source should be removed.
 676  *
 677  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
 678  *         SR_ERR_MALLOC upon memory allocation errors, SR_ERR_BUG upon
 679  *         internal errors.
 680  */
 681 SR_API int sr_session_source_remove_channel(GIOChannel *channel)
 682 {
 683         return _sr_session_source_remove((gintptr)channel);
 684 }
 685
 686 /** @} */