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 /* demo.c. TODO: Should not be global! */
  29 extern SR_PRIV GIOChannel channels[2];
  30
  31 struct source {
  32         int timeout;
  33         sr_receive_data_callback_t cb;
  34         void *cb_data;
  35 };
  36
  37 /* There can only be one session at a time. */
  38 /* 'session' is not static, it's used elsewhere (via 'extern'). */
  39 struct sr_session *session;
  40 static int num_sources = 0;
  41
  42 /* Both "sources" and "pollfds" are of the same size and contain pairs of
  43  * descriptor and callback function. We can not embed the GPollFD into the
  44  * source struct since we want to be able to pass the array of all poll
  45  * descriptors to g_poll.
  46  */
  47 static struct source *sources = NULL;
  48 static GPollFD *pollfds;
  49 static int source_timeout = -1;
  50
  51 /**
  52  * Create a new session.
  53  *
  54  * TODO: Should it use the file-global "session" variable or take an argument?
  55  *       The same question applies to all the other session functions.
  56  *
  57  * @return A pointer to the newly allocated session, or NULL upon errors.
  58  */
  59 SR_API struct sr_session *sr_session_new(void)
  60 {
  61         if (!(session = g_try_malloc0(sizeof(struct sr_session)))) {
  62                 sr_err("session: %s: session malloc failed", __func__);
  63                 return NULL; /* TODO: SR_ERR_MALLOC? */
  64         }
  65
  66         return session;
  67 }
  68
  69 /**
  70  * Destroy the current session.
  71  *
  72  * This frees up all memory used by the session.
  73  *
  74  * @return SR_OK upon success, SR_ERR_BUG if no session exists.
  75  */
  76 SR_API int sr_session_destroy(void)
  77 {
  78         if (!session) {
  79                 sr_err("session: %s: session was NULL", __func__);
  80                 return SR_ERR_BUG;
  81         }
  82
  83         g_slist_free(session->devs);
  84         session->devs = NULL;
  85
  86         /* TODO: Error checks needed? */
  87
  88         /* TODO: Loop over protocol decoders and free them. */
  89
  90         g_free(session);
  91         session = NULL;
  92
  93         return SR_OK;
  94 }
  95
  96 /**
  97  * Remove all the devices from the current session. TODO?
  98  *
  99  * The session itself (i.e., the struct sr_session) is not free'd and still
 100  * exists after this function returns.
 101  *
 102  * @return SR_OK upon success, SR_ERR_BUG if no session exists.
 103  */
 104 SR_API int sr_session_dev_remove_all(void)
 105 {
 106         if (!session) {
 107                 sr_err("session: %s: session was NULL", __func__);
 108                 return SR_ERR_BUG;
 109         }
 110
 111         g_slist_free(session->devs);
 112         session->devs = NULL;
 113
 114         return SR_OK;
 115 }
 116
 117 /**
 118  * Add a device to the current session.
 119  *
 120  * @param dev The device to add to the current session. Must not be NULL.
 121  *            Also, dev->driver and dev->driver->dev_open must not be NULL.
 122  *
 123  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments.
 124  */
 125 SR_API int sr_session_dev_add(struct sr_dev *dev)
 126 {
 127         int ret;
 128
 129         if (!dev) {
 130                 sr_err("session: %s: dev was NULL", __func__);
 131                 return SR_ERR_ARG;
 132         }
 133
 134         if (!session) {
 135                 sr_err("session: %s: session was NULL", __func__);
 136                 return SR_ERR_BUG;
 137         }
 138
 139         /* If dev->driver is NULL, this is a virtual device. */
 140         if (!dev->driver) {
 141                 sr_dbg("session: %s: dev->driver was NULL, this seems to be "
 142                        "a virtual device; continuing", __func__);
 143                 /* Just add the device, don't run dev_open(). */
 144                 session->devs = g_slist_append(session->devs, dev);
 145                 return SR_OK;
 146         }
 147
 148         /* dev->driver is non-NULL (i.e. we have a real device). */
 149         if (!dev->driver->dev_open) {
 150                 sr_err("session: %s: dev->driver->dev_open was NULL",
 151                        __func__);
 152                 return SR_ERR_BUG;
 153         }
 154
 155         if ((ret = dev->driver->dev_open(dev->driver_index)) != SR_OK) {
 156                 sr_err("session: %s: dev_open failed (%d)", __func__, ret);
 157                 return ret;
 158         }
 159
 160         session->devs = g_slist_append(session->devs, dev);
 161
 162         return SR_OK;
 163 }
 164
 165 /**
 166  * Remove all datafeed callbacks in the current session.
 167  *
 168  * @return SR_OK upon success, SR_ERR_BUG if no session exists.
 169  */
 170 SR_API int sr_session_datafeed_callback_remove_all(void)
 171 {
 172         if (!session) {
 173                 sr_err("session: %s: session was NULL", __func__);
 174                 return SR_ERR_BUG;
 175         }
 176
 177         g_slist_free(session->datafeed_callbacks);
 178         session->datafeed_callbacks = NULL;
 179
 180         return SR_OK;
 181 }
 182
 183 /**
 184  * Add a datafeed callback to the current session.
 185  *
 186  * @param cb Function to call when a chunk of data is received.
 187  *           Must not be NULL.
 188  *
 189  * @return SR_OK upon success, SR_ERR_BUG if no session exists.
 190  */
 191 SR_API int sr_session_datafeed_callback_add(sr_datafeed_callback_t cb)
 192 {
 193         if (!session) {
 194                 sr_err("session: %s: session was NULL", __func__);
 195                 return SR_ERR_BUG;
 196         }
 197
 198         if (!cb) {
 199                 sr_err("session: %s: cb was NULL", __func__);
 200                 return SR_ERR_ARG;
 201         }
 202
 203         session->datafeed_callbacks =
 204             g_slist_append(session->datafeed_callbacks, cb);
 205
 206         return SR_OK;
 207 }
 208
 209 /**
 210  * TODO.
 211  */
 212 static int sr_session_run_poll(void)
 213 {
 214         int ret, i;
 215
 216         while (session->running) {
 217                 ret = g_poll(pollfds, num_sources, source_timeout);
 218
 219                 for (i = 0; i < num_sources; i++) {
 220                         if (pollfds[i].revents > 0 || (ret == 0
 221                                 && source_timeout == sources[i].timeout)) {
 222                                 /*
 223                                  * Invoke the source's callback on an event,
 224                                  * or if the poll timeout out and this source
 225                                  * asked for that timeout.
 226                                  */
 227                                 if (!sources[i].cb(pollfds[i].fd, pollfds[i].revents,
 228                                                   sources[i].cb_data))
 229                                         sr_session_source_remove(pollfds[i].fd);
 230                         }
 231                 }
 232         }
 233
 234         return SR_OK;
 235 }
 236
 237 /**
 238  * Start a session.
 239  *
 240  * There can only be one session at a time.
 241  *
 242  * @return SR_OK upon success, SR_ERR upon errors.
 243  */
 244 SR_API int sr_session_start(void)
 245 {
 246         struct sr_dev *dev;
 247         GSList *l;
 248         int ret;
 249
 250         if (!session) {
 251                 sr_err("session: %s: session was NULL; a session must be "
 252                        "created first, before starting it.", __func__);
 253                 return SR_ERR_BUG;
 254         }
 255
 256         if (!session->devs) {
 257                 /* TODO: Actually the case? */
 258                 sr_err("session: %s: session->devs was NULL; a session "
 259                        "cannot be started without devices.", __func__);
 260                 return SR_ERR_BUG;
 261         }
 262
 263         /* TODO: Check driver_index validity? */
 264
 265         sr_info("session: starting");
 266
 267         for (l = session->devs; l; l = l->next) {
 268                 dev = l->data;
 269                 /* TODO: Check for dev != NULL. */
 270                 if ((ret = dev->driver->dev_acquisition_start(
 271                                 dev->driver_index, dev)) != SR_OK) {
 272                         sr_err("session: %s: could not start an acquisition "
 273                                "(%d)", __func__, ret);
 274                         break;
 275                 }
 276         }
 277
 278         /* TODO: What if there are multiple devices? Which return code? */
 279
 280         return ret;
 281 }
 282
 283 /**
 284  * Run the session.
 285  *
 286  * TODO: Various error checks etc.
 287  *
 288  * @return SR_OK upon success, SR_ERR_BUG upon errors.
 289  */
 290 SR_API int sr_session_run(void)
 291 {
 292         if (!session) {
 293                 sr_err("session: %s: session was NULL; a session must be "
 294                        "created first, before running it.", __func__);
 295                 return SR_ERR_BUG;
 296         }
 297
 298         if (!session->devs) {
 299                 /* TODO: Actually the case? */
 300                 sr_err("session: %s: session->devs was NULL; a session "
 301                        "cannot be run without devices.", __func__);
 302                 return SR_ERR_BUG;
 303         }
 304
 305         sr_info("session: running");
 306         session->running = TRUE;
 307
 308         /* Do we have real sources? */
 309         if (num_sources == 1 && pollfds[0].fd == -1) {
 310                 /* Dummy source, freewheel over it. */
 311                 while (session->running)
 312                         sources[0].cb(-1, 0, sources[0].cb_data);
 313         } else {
 314                 /* Real sources, use g_poll() main loop. */
 315                 sr_session_run_poll();
 316         }
 317
 318         return SR_OK;
 319 }
 320
 321 /**
 322  * Halt the current session.
 323  *
 324  * This requests the current session be stopped as soon as possible, for
 325  * example on receiving an SR_DF_END packet.
 326  *
 327  * @return SR_OK upon success, SR_ERR_BUG if no session exists.
 328  */
 329 SR_API int sr_session_halt(void)
 330 {
 331         if (!session) {
 332                 sr_err("session: %s: session was NULL", __func__);
 333                 return SR_ERR_BUG;
 334         }
 335
 336         sr_info("session: halting");
 337         session->running = FALSE;
 338
 339         return SR_OK;
 340 }
 341
 342 /**
 343  * Stop the current session.
 344  *
 345  * The current session is stopped immediately, with all acquisition sessions
 346  * being stopped and hardware drivers cleaned up.
 347  *
 348  * @return SR_OK upon success, SR_ERR_BUG if no session exists.
 349  */
 350 SR_API int sr_session_stop(void)
 351 {
 352         struct sr_dev *dev;
 353         GSList *l;
 354
 355         if (!session) {
 356                 sr_err("session: %s: session was NULL", __func__);
 357                 return SR_ERR_BUG;
 358         }
 359
 360         sr_info("session: stopping");
 361         session->running = FALSE;
 362
 363         for (l = session->devs; l; l = l->next) {
 364                 dev = l->data;
 365                 /* Check for dev != NULL. */
 366                 if (dev->driver) {
 367                         if (dev->driver->dev_acquisition_stop)
 368                                 dev->driver->dev_acquisition_stop(dev->driver_index, dev);
 369                         if (dev->driver->cleanup)
 370                                 dev->driver->cleanup();
 371                 }
 372         }
 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(struct sr_datafeed_packet *packet)
 383 {
 384         struct sr_datafeed_logic *logic;
 385         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_LOGIC");
 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 dev 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 SR_PRIV int sr_session_send(struct sr_dev *dev,
 436                             struct sr_datafeed_packet *packet)
 437 {
 438         GSList *l;
 439         sr_datafeed_callback_t cb;
 440
 441         if (!dev) {
 442                 sr_err("session: %s: dev was NULL", __func__);
 443                 return SR_ERR_ARG;
 444         }
 445
 446         if (!packet) {
 447                 sr_err("session: %s: packet was NULL", __func__);
 448                 return SR_ERR_ARG;
 449         }
 450
 451         for (l = session->datafeed_callbacks; l; l = l->next) {
 452                 if (sr_log_loglevel_get() >= SR_LOG_DBG)
 453                         datafeed_dump(packet);
 454                 cb = l->data;
 455                 /* TODO: Check for cb != NULL. */
 456                 cb(dev, packet);
 457         }
 458
 459         return SR_OK;
 460 }
 461
 462 /**
 463  * TODO.
 464  *
 465  * TODO: More error checks etc.
 466  *
 467  * @param fd TODO.
 468  * @param events TODO.
 469  * @param timeout TODO.
 470  * @param cb Callback function to add. Must not be NULL.
 471  * @param cb_data Data for the callback function. Can be NULL.
 472  *
 473  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
 474  *         SR_ERR_MALLOC upon memory allocation errors.
 475  */
 476 SR_API int sr_session_source_add(int fd, int events, int timeout,
 477                 sr_receive_data_callback_t cb, void *cb_data)
 478 {
 479         struct source *new_sources, *s;
 480         GPollFD *new_pollfds, *p;
 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(pollfds, sizeof(GPollFD) * (num_sources + 1));
 490         if (!new_pollfds) {
 491                 sr_err("session: %s: new_sources malloc failed", __func__);
 492                 return SR_ERR_MALLOC;
 493         }
 494
 495         new_sources = g_try_realloc(sources, sizeof(struct source) * (num_sources + 1));
 496         if (!new_sources) {
 497                 sr_err("session: %s: new_sources malloc failed", __func__);
 498                 return SR_ERR_MALLOC;
 499         }
 500
 501         p = &new_pollfds[num_sources];
 502         s = &new_sources[num_sources++];
 503 #ifdef _WIN32
 504         g_io_channel_win32_make_pollfd(&channels[0],
 505                         events, p);
 506 #else
 507         p->fd = fd;
 508         p->events = events;
 509 #endif
 510         s->timeout = timeout;
 511         s->cb = cb;
 512         s->cb_data = cb_data;
 513         pollfds = new_pollfds;
 514         sources = new_sources;
 515
 516         if (timeout != source_timeout && timeout > 0
 517             && (source_timeout == -1 || timeout < source_timeout))
 518                 source_timeout = timeout;
 519
 520         return SR_OK;
 521 }
 522
 523 /**
 524  * Remove the source belonging to the specified file descriptor.
 525  *
 526  * TODO: More error checks.
 527  *
 528  * @param fd TODO.
 529  *
 530  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
 531  *         SR_ERR_MALLOC upon memory allocation errors, SR_ERR_BUG upon
 532  *         internal errors.
 533  */
 534 SR_API int sr_session_source_remove(int fd)
 535 {
 536         struct source *new_sources;
 537         GPollFD *new_pollfds;
 538         int old;
 539
 540         if (!sources) {
 541                 sr_err("session: %s: sources was NULL", __func__);
 542                 return SR_ERR_BUG;
 543         }
 544
 545         for (old = 0; old < num_sources; old++) {
 546                 if (pollfds[old].fd == fd)
 547                         break;
 548         }
 549
 550         /* fd not found, nothing to do */
 551         if (old == num_sources)
 552                 return SR_OK;
 553
 554         num_sources -= 1;
 555
 556         if (old != num_sources) {
 557                 memmove(&pollfds[old], &pollfds[old+1],
 558                         (num_sources - old) * sizeof(GPollFD));
 559                 memmove(&sources[old], &sources[old+1],
 560                         (num_sources - old) * sizeof(struct source));
 561         }
 562
 563         new_pollfds = g_try_realloc(sources, sizeof(GPollFD) * num_sources);
 564         if (!new_pollfds && num_sources > 0) {
 565                 sr_err("session: %s: new_sources malloc failed", __func__);
 566                 return SR_ERR_MALLOC;
 567         }
 568
 569         new_sources = g_try_realloc(sources, sizeof(struct source) * num_sources);
 570         if (!new_sources && num_sources > 0) {
 571                 sr_err("session: %s: new_sources malloc failed", __func__);
 572                 return SR_ERR_MALLOC;
 573         }
 574
 575         pollfds = new_pollfds;
 576         sources = new_sources;
 577
 578         return SR_OK;
 579 }