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