src/std.c

   1 /*
   2  * This file is part of the libsigrok project.
   3  *
   4  * Copyright (C) 2013 Uwe Hermann <uwe@hermann-uwe.de>
   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 2 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, write to the Free Software
  18  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
  19  */
  20
  21 /** @file
  22   * Standard API helper functions.
  23   * @internal
  24   */
  25
  26 #include <config.h>
  27 #include <glib.h>
  28 #include <libsigrok/libsigrok.h>
  29 #include "libsigrok-internal.h"
  30 #include "scpi.h"
  31
  32 #define LOG_PREFIX "std"
  33
  34 /**
  35  * Standard sr_driver_init() API helper.
  36  *
  37  * This function can be used to simplify most driver's init() API callback.
  38  *
  39  * It creates a new 'struct drv_context' (drvc), assigns sr_ctx to it, and
  40  * then 'drvc' is assigned to the 'struct sr_dev_driver' (di) that is passed.
  41  *
  42  * @param di The driver instance to use.
  43  * @param sr_ctx The libsigrok context to assign.
  44  * @param[in] prefix A driver-specific prefix string used for log messages.
  45  *
  46  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments.
  47  */
  48 SR_PRIV int std_init(struct sr_dev_driver *di, struct sr_context *sr_ctx,
  49                      const char *prefix)
  50 {
  51         struct drv_context *drvc;
  52
  53         if (!di) {
  54                 sr_err("%s: Invalid driver, cannot initialize.", prefix);
  55                 return SR_ERR_ARG;
  56         }
  57
  58         drvc = g_malloc0(sizeof(struct drv_context));
  59         drvc->sr_ctx = sr_ctx;
  60         drvc->instances = NULL;
  61         di->context = drvc;
  62
  63         return SR_OK;
  64 }
  65
  66 /**
  67  * Standard driver cleanup() callback API helper
  68  *
  69  * @param di The driver instance to use.
  70  *
  71  * Frees all device instances by calling sr_dev_clear() and then releases any
  72  * resources allocated by std_init().
  73  *
  74  * @retval SR_OK Success
  75  * @retval SR_ERR_ARG Invalid driver
  76  *
  77 */
  78 SR_PRIV int std_cleanup(const struct sr_dev_driver *di)
  79 {
  80         int ret;
  81
  82         ret = sr_dev_clear(di);
  83         g_free(di->context);
  84
  85         return ret;
  86 }
  87
  88 /**
  89  * Standard API helper for sending an SR_DF_HEADER packet.
  90  *
  91  * This function can be used to simplify most driver's
  92  * dev_acquisition_start() API callback.
  93  *
  94  * @param sdi The device instance to use.
  95  * @param prefix A driver-specific prefix string used for log messages.
  96  *               Must not be NULL. An empty string is allowed.
  97  *
  98  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
  99  *         SR_ERR upon other errors.
 100  */
 101 SR_PRIV int std_session_send_df_header(const struct sr_dev_inst *sdi,
 102                                        const char *prefix)
 103 {
 104         int ret;
 105         struct sr_datafeed_packet packet;
 106         struct sr_datafeed_header header;
 107
 108         if (!prefix) {
 109                 sr_err("Invalid prefix.");
 110                 return SR_ERR_ARG;
 111         }
 112
 113         sr_dbg("%s: Starting acquisition.", prefix);
 114
 115         /* Send header packet to the session bus. */
 116         sr_dbg("%s: Sending SR_DF_HEADER packet.", prefix);
 117         packet.type = SR_DF_HEADER;
 118         packet.payload = (uint8_t *)&header;
 119         header.feed_version = 1;
 120         gettimeofday(&header.starttime, NULL);
 121
 122         if ((ret = sr_session_send(sdi, &packet)) < 0) {
 123                 sr_err("%s: Failed to send header packet: %d.", prefix, ret);
 124                 return ret;
 125         }
 126
 127         return SR_OK;
 128 }
 129
 130 /**
 131  * Standard API helper for sending an SR_DF_END packet.
 132  *
 133  * @param sdi The device instance to use. Must not be NULL.
 134  * @param prefix A driver-specific prefix string used for log messages.
 135  *               Must not be NULL. An empty string is allowed.
 136  *
 137  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
 138  *         SR_ERR upon other errors.
 139  */
 140 SR_PRIV int std_session_send_df_end(const struct sr_dev_inst *sdi,
 141                                     const char *prefix)
 142 {
 143         int ret;
 144         struct sr_datafeed_packet packet;
 145
 146         if (!sdi || !prefix)
 147                 return SR_ERR_ARG;
 148
 149         sr_dbg("%s: Sending SR_DF_END packet.", prefix);
 150
 151         packet.type = SR_DF_END;
 152         packet.payload = NULL;
 153
 154         if ((ret = sr_session_send(sdi, &packet)) < 0) {
 155                 sr_err("%s: Failed to send SR_DF_END packet: %d.", prefix, ret);
 156                 return ret;
 157         }
 158
 159         return SR_OK;
 160 }
 161
 162 #ifdef HAVE_LIBSERIALPORT
 163
 164 /**
 165  * Standard serial driver dev_open() helper.
 166  *
 167  * This function can be used to implement the dev_open() driver API
 168  * callback in drivers that use a serial port. The port is opened
 169  * with the SERIAL_RDWR flag.
 170  *
 171  * If the open succeeded, the status field of the given sdi is set
 172  * to SR_ST_ACTIVE.
 173  *
 174  * @retval SR_OK Success.
 175  * @retval SR_ERR Serial port open failed.
 176  */
 177 SR_PRIV int std_serial_dev_open(struct sr_dev_inst *sdi)
 178 {
 179         struct sr_serial_dev_inst *serial;
 180
 181         serial = sdi->conn;
 182         if (serial_open(serial, SERIAL_RDWR) != SR_OK)
 183                 return SR_ERR;
 184
 185         sdi->status = SR_ST_ACTIVE;
 186
 187         return SR_OK;
 188 }
 189
 190 /**
 191  * Standard serial driver dev_close() helper.
 192  *
 193  * This function can be used to implement the dev_close() driver API
 194  * callback in drivers that use a serial port.
 195  *
 196  * After closing the port, the status field of the given sdi is set
 197  * to SR_ST_INACTIVE.
 198  *
 199  * @retval SR_OK Success.
 200  */
 201 SR_PRIV int std_serial_dev_close(struct sr_dev_inst *sdi)
 202 {
 203         struct sr_serial_dev_inst *serial;
 204
 205         serial = sdi->conn;
 206         if (serial && sdi->status == SR_ST_ACTIVE) {
 207                 serial_close(serial);
 208                 sdi->status = SR_ST_INACTIVE;
 209         }
 210
 211         return SR_OK;
 212 }
 213
 214 /**
 215  * Standard sr_session_stop() API helper.
 216  *
 217  * This function can be used to simplify most (serial port based) driver's
 218  * dev_acquisition_stop() API callback.
 219  *
 220  * @param sdi The device instance for which acquisition should stop.
 221  *            Must not be NULL.
 222  * @param cb_data Opaque 'cb_data' pointer. Must not be NULL.
 223  * @param dev_close_fn Function pointer to the driver's dev_close().
 224  *                        Must not be NULL.
 225  * @param serial The serial device instance (struct serial_dev_inst *).
 226  *               Must not be NULL.
 227  * @param[in] prefix A driver-specific prefix string used for log messages.
 228  *               Must not be NULL. An empty string is allowed.
 229  *
 230  * @retval SR_OK Success.
 231  * @retval SR_ERR_ARG Invalid arguments.
 232  * @retval SR_ERR_DEV_CLOSED Device is closed.
 233  * @retval SR_ERR Other errors.
 234  */
 235 SR_PRIV int std_serial_dev_acquisition_stop(struct sr_dev_inst *sdi,
 236                         dev_close_callback dev_close_fn,
 237                         struct sr_serial_dev_inst *serial, const char *prefix)
 238 {
 239         int ret;
 240
 241         if (!prefix) {
 242                 sr_err("Invalid prefix.");
 243                 return SR_ERR_ARG;
 244         }
 245
 246         if (sdi->status != SR_ST_ACTIVE) {
 247                 sr_err("%s: Device inactive, can't stop acquisition.", prefix);
 248                 return SR_ERR_DEV_CLOSED;
 249         }
 250
 251         sr_dbg("%s: Stopping acquisition.", prefix);
 252
 253         if ((ret = serial_source_remove(sdi->session, serial)) < 0) {
 254                 sr_err("%s: Failed to remove source: %d.", prefix, ret);
 255                 return ret;
 256         }
 257
 258         if ((ret = dev_close_fn(sdi)) < 0) {
 259                 sr_err("%s: Failed to close device: %d.", prefix, ret);
 260                 return ret;
 261         }
 262
 263         std_session_send_df_end(sdi, prefix);
 264
 265         return SR_OK;
 266 }
 267
 268 #endif
 269
 270 /**
 271  * Standard driver dev_clear() helper.
 272  *
 273  * Clear driver, this means, close all instances.
 274  *
 275  * This function can be used to implement the dev_clear() driver API
 276  * callback. dev_close() is called before every sr_dev_inst is cleared.
 277  *
 278  * The only limitation is driver-specific device contexts (sdi->priv).
 279  * These are freed, but any dynamic allocation within structs stored
 280  * there cannot be freed.
 281  *
 282  * @param driver The driver which will have its instances released.
 283  * @param clear_private If not NULL, this points to a function called
 284  * with sdi->priv as argument. The function can then clear any device
 285  * instance-specific resources kept there. It must also clear the struct
 286  * pointed to by sdi->priv.
 287  *
 288  * @return SR_OK on success.
 289  */
 290 SR_PRIV int std_dev_clear(const struct sr_dev_driver *driver,
 291                 std_dev_clear_callback clear_private)
 292 {
 293         struct drv_context *drvc;
 294         struct sr_dev_inst *sdi;
 295         GSList *l;
 296         int ret;
 297
 298         if (!(drvc = driver->context))
 299                 /* Driver was never initialized, nothing to do. */
 300                 return SR_OK;
 301
 302         ret = SR_OK;
 303         for (l = drvc->instances; l; l = l->next) {
 304                 if (!(sdi = l->data)) {
 305                         ret = SR_ERR_BUG;
 306                         continue;
 307                 }
 308                 if (driver->dev_close)
 309                         driver->dev_close(sdi);
 310
 311                 if (sdi->conn) {
 312 #ifdef HAVE_LIBSERIALPORT
 313                         if (sdi->inst_type == SR_INST_SERIAL)
 314                                 sr_serial_dev_inst_free(sdi->conn);
 315 #endif
 316 #ifdef HAVE_LIBUSB_1_0
 317                         if (sdi->inst_type == SR_INST_USB)
 318                                 sr_usb_dev_inst_free(sdi->conn);
 319 #endif
 320                         if (sdi->inst_type == SR_INST_SCPI)
 321                                 sr_scpi_free(sdi->conn);
 322                         if (sdi->inst_type == SR_INST_MODBUS)
 323                                 sr_modbus_free(sdi->conn);
 324                 }
 325                 if (clear_private)
 326                         /* The helper function is responsible for freeing
 327                          * its own sdi->priv! */
 328                         clear_private(sdi->priv);
 329                 else
 330                         g_free(sdi->priv);
 331
 332                 sr_dev_inst_free(sdi);
 333         }
 334
 335         g_slist_free(drvc->instances);
 336         drvc->instances = NULL;
 337
 338         return ret;
 339 }
 340
 341 /**
 342  * Standard implementation for the driver dev_list() callback
 343  *
 344  * This function can be used as the dev_list callback by most drivers that use
 345  * the standard helper functions. It returns the devices contained in the driver
 346  * context instances list.
 347  *
 348  * @param di The driver instance to use.
 349  *
 350  * @return The list of devices/instances of this driver, or NULL upon errors
 351  *         or if the list is empty.
 352  */
 353 SR_PRIV GSList *std_dev_list(const struct sr_dev_driver *di)
 354 {
 355         struct drv_context *drvc = di->context;
 356
 357         return drvc->instances;
 358 }