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