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:
 396                 sr_dbg("bus: received SR_DF_META");
 397                 break;
 398         case SR_DF_LOGIC:
 399                 logic = packet->payload;
 400                 sr_dbg("bus: received SR_DF_LOGIC %" PRIu64 " bytes", logic->length);
 401                 break;
 402         case SR_DF_ANALOG:
 403                 analog = packet->payload;
 404                 sr_dbg("bus: received SR_DF_ANALOG %d samples", analog->num_samples);
 405                 break;
 406         case SR_DF_END:
 407                 sr_dbg("bus: received SR_DF_END");
 408                 break;
 409         case SR_DF_FRAME_BEGIN:
 410                 sr_dbg("bus: received SR_DF_FRAME_BEGIN");
 411                 break;
 412         case SR_DF_FRAME_END:
 413                 sr_dbg("bus: received SR_DF_FRAME_END");
 414                 break;
 415         default:
 416                 sr_dbg("bus: received unknown packet type %d", packet->type);
 417                 break;
 418         }
 419 }
 420
 421 /**
 422  * Send a packet to whatever is listening on the datafeed bus.
 423  *
 424  * Hardware drivers use this to send a data packet to the frontend.
 425  *
 426  * @param sdi TODO.
 427  * @param packet The datafeed packet to send to the session bus.
 428  *
 429  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments.
 430  *
 431  * @private
 432  */
 433 SR_PRIV int sr_session_send(const struct sr_dev_inst *sdi,
 434                             const struct sr_datafeed_packet *packet)
 435 {
 436         GSList *l;
 437         sr_datafeed_callback_t cb;
 438
 439         if (!sdi) {
 440                 sr_err("session: %s: sdi was NULL", __func__);
 441                 return SR_ERR_ARG;
 442         }
 443
 444         if (!packet) {
 445                 sr_err("session: %s: packet was NULL", __func__);
 446                 return SR_ERR_ARG;
 447         }
 448
 449         for (l = session->datafeed_callbacks; l; l = l->next) {
 450                 if (sr_log_loglevel_get() >= SR_LOG_DBG)
 451                         datafeed_dump(packet);
 452                 cb = l->data;
 453                 cb(sdi, packet);
 454         }
 455
 456         return SR_OK;
 457 }
 458
 459 /**
 460  * Add an event source for a file descriptor.
 461  *
 462  * @param pollfd The GPollFD.
 463  * @param timeout Max time to wait before the callback is called, ignored if 0.
 464  * @param cb Callback function to add. Must not be NULL.
 465  * @param cb_data Data for the callback function. Can be NULL.
 466  * @param poll_object TODO.
 467  *
 468  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
 469  *         SR_ERR_MALLOC upon memory allocation errors.
 470  */
 471 static int _sr_session_source_add(GPollFD *pollfd, int timeout,
 472         sr_receive_data_callback_t cb, void *cb_data, gintptr poll_object)
 473 {
 474         struct source *new_sources, *s;
 475         GPollFD *new_pollfds;
 476
 477         if (!cb) {
 478                 sr_err("session: %s: cb was NULL", __func__);
 479                 return SR_ERR_ARG;
 480         }
 481
 482         /* Note: cb_data can be NULL, that's not a bug. */
 483
 484         new_pollfds = g_try_realloc(session->pollfds,
 485                         sizeof(GPollFD) * (session->num_sources + 1));
 486         if (!new_pollfds) {
 487                 sr_err("session: %s: new_pollfds malloc failed", __func__);
 488                 return SR_ERR_MALLOC;
 489         }
 490
 491         new_sources = g_try_realloc(session->sources, sizeof(struct source) *
 492                         (session->num_sources + 1));
 493         if (!new_sources) {
 494                 sr_err("session: %s: new_sources malloc failed", __func__);
 495                 return SR_ERR_MALLOC;
 496         }
 497
 498         new_pollfds[session->num_sources] = *pollfd;
 499         s = &new_sources[session->num_sources++];
 500         s->timeout = timeout;
 501         s->cb = cb;
 502         s->cb_data = cb_data;
 503         s->poll_object = poll_object;
 504         session->pollfds = new_pollfds;
 505         session->sources = new_sources;
 506
 507         if (timeout != session->source_timeout && timeout > 0
 508             && (session->source_timeout == -1 || timeout < session->source_timeout))
 509                 session->source_timeout = timeout;
 510
 511         return SR_OK;
 512 }
 513
 514 /**
 515  * Add an event source for a file descriptor.
 516  *
 517  * @param fd The file descriptor.
 518  * @param events Events to check for.
 519  * @param timeout Max time to wait before the callback is called, ignored if 0.
 520  * @param cb Callback function to add. Must not be NULL.
 521  * @param cb_data Data for the callback function. Can be NULL.
 522  *
 523  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
 524  *         SR_ERR_MALLOC upon memory allocation errors.
 525  */
 526 SR_API int sr_session_source_add(int fd, int events, int timeout,
 527                 sr_receive_data_callback_t cb, void *cb_data)
 528 {
 529         GPollFD p;
 530
 531         p.fd = fd;
 532         p.events = events;
 533
 534         return _sr_session_source_add(&p, timeout, cb, cb_data, (gintptr)fd);
 535 }
 536
 537 /**
 538  * Add an event source for a GPollFD.
 539  *
 540  * @param pollfd The GPollFD.
 541  * @param timeout Max time to wait before the callback is called, ignored if 0.
 542  * @param cb Callback function to add. Must not be NULL.
 543  * @param cb_data Data for the callback function. Can be NULL.
 544  *
 545  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
 546  *         SR_ERR_MALLOC upon memory allocation errors.
 547  */
 548 SR_API int sr_session_source_add_pollfd(GPollFD *pollfd, int timeout,
 549                 sr_receive_data_callback_t cb, void *cb_data)
 550 {
 551         return _sr_session_source_add(pollfd, timeout, cb,
 552                                       cb_data, (gintptr)pollfd);
 553 }
 554
 555 /**
 556  * Add an event source for a GIOChannel.
 557  *
 558  * @param channel The GIOChannel.
 559  * @param events Events to poll on.
 560  * @param timeout Max time to wait before the callback is called, ignored if 0.
 561  * @param cb Callback function to add. Must not be NULL.
 562  * @param cb_data Data for the callback function. Can be NULL.
 563  *
 564  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
 565  *         SR_ERR_MALLOC upon memory allocation errors.
 566  */
 567 SR_API int sr_session_source_add_channel(GIOChannel *channel, int events,
 568                 int timeout, sr_receive_data_callback_t cb, void *cb_data)
 569 {
 570         GPollFD p;
 571
 572 #ifdef _WIN32
 573         g_io_channel_win32_make_pollfd(channel, events, &p);
 574 #else
 575         p.fd = g_io_channel_unix_get_fd(channel);
 576         p.events = events;
 577 #endif
 578
 579         return _sr_session_source_add(&p, timeout, cb, cb_data, (gintptr)channel);
 580 }
 581
 582 /**
 583  * Remove the source belonging to the specified channel.
 584  *
 585  * @todo Add more error checks and logging.
 586  *
 587  * @param channel The channel for which the source should be removed.
 588  *
 589  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
 590  *         SR_ERR_MALLOC upon memory allocation errors, SR_ERR_BUG upon
 591  *         internal errors.
 592  */
 593 static int _sr_session_source_remove(gintptr poll_object)
 594 {
 595         struct source *new_sources;
 596         GPollFD *new_pollfds;
 597         unsigned int old;
 598
 599         if (!session->sources || !session->num_sources) {
 600                 sr_err("session: %s: sources was NULL", __func__);
 601                 return SR_ERR_BUG;
 602         }
 603
 604         for (old = 0; old < session->num_sources; old++) {
 605                 if (session->sources[old].poll_object == poll_object)
 606                         break;
 607         }
 608
 609         /* fd not found, nothing to do */
 610         if (old == session->num_sources)
 611                 return SR_OK;
 612
 613         session->num_sources -= 1;
 614
 615         if (old != session->num_sources) {
 616                 memmove(&session->pollfds[old], &session->pollfds[old+1],
 617                         (session->num_sources - old) * sizeof(GPollFD));
 618                 memmove(&session->sources[old], &session->sources[old+1],
 619                         (session->num_sources - old) * sizeof(struct source));
 620         }
 621
 622         new_pollfds = g_try_realloc(session->pollfds, sizeof(GPollFD) * session->num_sources);
 623         if (!new_pollfds && session->num_sources > 0) {
 624                 sr_err("session: %s: new_pollfds malloc failed", __func__);
 625                 return SR_ERR_MALLOC;
 626         }
 627
 628         new_sources = g_try_realloc(session->sources, sizeof(struct source) * session->num_sources);
 629         if (!new_sources && session->num_sources > 0) {
 630                 sr_err("session: %s: new_sources malloc failed", __func__);
 631                 return SR_ERR_MALLOC;
 632         }
 633
 634         session->pollfds = new_pollfds;
 635         session->sources = new_sources;
 636
 637         return SR_OK;
 638 }
 639
 640 /**
 641  * Remove the source belonging to the specified file descriptor.
 642  *
 643  * @param fd The file descriptor for which the source should be removed.
 644  *
 645  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
 646  *         SR_ERR_MALLOC upon memory allocation errors, SR_ERR_BUG upon
 647  *         internal errors.
 648  */
 649 SR_API int sr_session_source_remove(int fd)
 650 {
 651         return _sr_session_source_remove((gintptr)fd);
 652 }
 653
 654 /**
 655  * Remove the source belonging to the specified poll descriptor.
 656  *
 657  * @param pollfd The poll descriptor for which the source should be removed.
 658  *
 659  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
 660  *         SR_ERR_MALLOC upon memory allocation errors, SR_ERR_BUG upon
 661  *         internal errors.
 662  */
 663 SR_API int sr_session_source_remove_pollfd(GPollFD *pollfd)
 664 {
 665         return _sr_session_source_remove((gintptr)pollfd);
 666 }
 667
 668 /**
 669  * Remove the source belonging to the specified channel.
 670  *
 671  * @param channel The channel for which the source should be removed.
 672  *
 673  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
 674  *         SR_ERR_MALLOC upon memory allocation errors, SR_ERR_BUG upon
 675  *         internal errors.
 676  */
 677 SR_API int sr_session_source_remove_channel(GIOChannel *channel)
 678 {
 679         return _sr_session_source_remove((gintptr)channel);
 680 }
 681
 682 /** @} */