X-Git-Url: https://sigrok.org/gitweb/?a=blobdiff_plain;f=src%2Fstd.c;h=c6ff4ccef96cc07d758b13f4936db374eb2631f2;hb=db944f1622479a91c257315ad368b63c5b58149c;hp=35da70884a700a8256f461480c4a6223d1c9c7ce;hpb=7e463623382e1f574fde150b3fc88a65eaebb578;p=libsigrok.git diff --git a/src/std.c b/src/std.c index 35da7088..c6ff4cce 100644 --- a/src/std.c +++ b/src/std.c @@ -34,22 +34,28 @@ #define LOG_PREFIX "std" /** - * Standard sr_driver_init() API helper. + * Standard driver init() callback API helper. * * This function can be used to simplify most driver's init() API callback. * - * It creates a new 'struct drv_context' (drvc), assigns sr_ctx to it, and - * then 'drvc' is assigned to the 'struct sr_dev_driver' (di) that is passed. + * Create a new 'struct drv_context' (drvc), assign sr_ctx to it, and + * then assign 'drvc' to the 'struct sr_dev_driver' (di) that is passed. * - * @param di The driver instance to use. - * @param sr_ctx The libsigrok context to assign. + * @param[in] di The driver instance to use. Must not be NULL. + * @param[in] sr_ctx The libsigrok context to assign. May be NULL. * - * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments. + * @retval SR_OK Success. + * @retval SR_ERR_ARG Invalid argument. */ SR_PRIV int std_init(struct sr_dev_driver *di, struct sr_context *sr_ctx) { struct drv_context *drvc; + if (!di) { + sr_err("%s: Invalid argument.", __func__); + return SR_ERR_ARG; + } + drvc = g_malloc0(sizeof(struct drv_context)); drvc->sr_ctx = sr_ctx; drvc->instances = NULL; @@ -59,45 +65,116 @@ SR_PRIV int std_init(struct sr_dev_driver *di, struct sr_context *sr_ctx) } /** - * Standard driver cleanup() callback API helper + * Standard driver cleanup() callback API helper. * - * @param di The driver instance to use. + * This function can be used to simplify most driver's cleanup() API callback. * - * Frees all device instances by calling sr_dev_clear() and then releases any + * Free all device instances by calling sr_dev_clear() and then release any * resources allocated by std_init(). * - * @retval SR_OK Success - * @retval SR_ERR_ARG Invalid driver + * @param[in] di The driver instance to use. Must not be NULL. * -*/ + * @retval SR_OK Success. + * @retval SR_ERR_ARG Invalid argument. + * @retval other Other error. + */ SR_PRIV int std_cleanup(const struct sr_dev_driver *di) { int ret; + if (!di) { + sr_err("%s: Invalid argument.", __func__); + return SR_ERR_ARG; + } + ret = sr_dev_clear(di); g_free(di->context); return ret; } +/** + * Dummmy driver dev_open() callback API helper. + * + * @param[in] sdi The device instance to use. May be NULL (unused). + * + * @retval SR_OK Success. + */ +SR_PRIV int std_dummy_dev_open(struct sr_dev_inst *sdi) +{ + (void)sdi; + + return SR_OK; +} + +/** + * Dummmy driver dev_close() callback API helper. + * + * @param[in] sdi The device instance to use. May be NULL (unused). + * + * @retval SR_OK Success. + */ +SR_PRIV int std_dummy_dev_close(struct sr_dev_inst *sdi) +{ + (void)sdi; + + return SR_OK; +} + +/** + * Dummmy driver dev_acquisition_start() callback API helper. + * + * @param[in] sdi The device instance to use. May be NULL (unused). + * + * @retval SR_OK Success. + */ +SR_PRIV int std_dummy_dev_acquisition_start(const struct sr_dev_inst *sdi) +{ + (void)sdi; + + return SR_OK; +} + +/** + * Dummmy driver dev_acquisition_stop() callback API helper. + * + * @param[in] sdi The device instance to use. May be NULL (unused). + * + * @retval SR_OK Success. + */ +SR_PRIV int std_dummy_dev_acquisition_stop(struct sr_dev_inst *sdi) +{ + (void)sdi; + + return SR_OK; +} + /** * Standard API helper for sending an SR_DF_HEADER packet. * - * This function can be used to simplify most driver's + * This function can be used to simplify most drivers' * dev_acquisition_start() API callback. * - * @param sdi The device instance to use. + * @param[in] sdi The device instance to use. Must not be NULL. * - * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or - * SR_ERR upon other errors. + * @retval SR_OK Success. + * @retval SR_ERR_ARG Invalid argument. + * @retval other Other error. */ SR_PRIV int std_session_send_df_header(const struct sr_dev_inst *sdi) { - const char *prefix = (sdi->driver) ? sdi->driver->name : "unknown"; + const char *prefix; int ret; struct sr_datafeed_packet packet; struct sr_datafeed_header header; + if (!sdi) { + sr_err("%s: Invalid argument.", __func__); + return SR_ERR_ARG; + } + + prefix = (sdi->driver) ? sdi->driver->name : "unknown"; + /* Send header packet to the session bus. */ sr_dbg("%s: Sending SR_DF_HEADER packet.", prefix); packet.type = SR_DF_HEADER; @@ -106,7 +183,7 @@ SR_PRIV int std_session_send_df_header(const struct sr_dev_inst *sdi) gettimeofday(&header.starttime, NULL); if ((ret = sr_session_send(sdi, &packet)) < 0) { - sr_err("%s: Failed to send header packet: %d.", prefix, ret); + sr_err("%s: Failed to send SR_DF_HEADER packet: %d.", prefix, ret); return ret; } @@ -116,19 +193,27 @@ SR_PRIV int std_session_send_df_header(const struct sr_dev_inst *sdi) /** * Standard API helper for sending an SR_DF_END packet. * - * @param sdi The device instance to use. Must not be NULL. + * This function can be used to simplify most drivers' + * dev_acquisition_stop() API callback. + * + * @param[in] sdi The device instance to use. Must not be NULL. * - * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or - * SR_ERR upon other errors. + * @retval SR_OK Success. + * @retval SR_ERR_ARG Invalid argument. + * @retval other Other error. */ SR_PRIV int std_session_send_df_end(const struct sr_dev_inst *sdi) { - const char *prefix = (sdi->driver) ? sdi->driver->name : "unknown"; + const char *prefix; int ret; struct sr_datafeed_packet packet; - if (!sdi) + if (!sdi) { + sr_err("%s: Invalid argument.", __func__); return SR_ERR_ARG; + } + + prefix = (sdi->driver) ? sdi->driver->name : "unknown"; sr_dbg("%s: Sending SR_DF_END packet.", prefix); @@ -146,22 +231,26 @@ SR_PRIV int std_session_send_df_end(const struct sr_dev_inst *sdi) #ifdef HAVE_LIBSERIALPORT /** - * Standard serial driver dev_open() helper. + * Standard serial driver dev_open() callback API helper. * * This function can be used to implement the dev_open() driver API * callback in drivers that use a serial port. The port is opened * with the SERIAL_RDWR flag. * + * @param[in] sdi The device instance to use. Must not be NULL. + * * @retval SR_OK Success. - * @retval SR_ERR_ARG Invalid arguments. - * @retval SR_ERR Serial port open failed. + * @retval SR_ERR_ARG Invalid argument. + * @retval other Serial port open failed. */ SR_PRIV int std_serial_dev_open(struct sr_dev_inst *sdi) { struct sr_serial_dev_inst *serial; - if (!sdi || !sdi->conn) + if (!sdi) { + sr_err("%s: Invalid argument.", __func__); return SR_ERR_ARG; + } serial = sdi->conn; @@ -169,54 +258,58 @@ SR_PRIV int std_serial_dev_open(struct sr_dev_inst *sdi) } /** - * Standard serial driver dev_close() helper. + * Standard serial driver dev_close() callback API helper. * * This function can be used to implement the dev_close() driver API * callback in drivers that use a serial port. * - * After closing the port, the status field of the given sdi is set - * to SR_ST_INACTIVE. + * @param[in] sdi The device instance to use. Must not be NULL. * * @retval SR_OK Success. - * @retval SR_ERR_ARG Invalid arguments. + * @retval SR_ERR_ARG Invalid argument. + * @retval other Serial port close failed. */ SR_PRIV int std_serial_dev_close(struct sr_dev_inst *sdi) { struct sr_serial_dev_inst *serial; - sdi->status = SR_ST_INACTIVE; - - serial = sdi->conn; - if (!serial) { - sr_err("%s: Can't close invalid serial port.", sdi->driver->name); + if (!sdi) { + sr_err("%s: Invalid argument.", __func__); return SR_ERR_ARG; } - serial_close(serial); + serial = sdi->conn; - return SR_OK; + return serial_close(serial); } /** - * Standard sr_session_stop() API helper. + * Standard serial driver dev_acquisition_stop() callback API helper. * - * This function can be used to simplify most (serial port based) driver's + * This function can be used to simplify most (serial port based) drivers' * dev_acquisition_stop() API callback. * - * @param sdi The device instance for which acquisition should stop. - * Must not be NULL. + * @param[in] sdi The device instance for which acquisition should stop. + * Must not be NULL. * * @retval SR_OK Success. - * @retval SR_ERR_ARG Invalid arguments. - * @retval SR_ERR_DEV_CLOSED Device is closed. - * @retval SR_ERR Other errors. + * @retval SR_ERR_ARG Invalid argument. + * @retval other Other error. */ SR_PRIV int std_serial_dev_acquisition_stop(struct sr_dev_inst *sdi) { - struct sr_serial_dev_inst *serial = sdi->conn; - const char *prefix = sdi->driver->name; + struct sr_serial_dev_inst *serial; + const char *prefix; int ret; + if (!sdi) { + sr_err("%s: Invalid argument.", __func__); + return SR_ERR_ARG; + } + + serial = sdi->conn; + prefix = sdi->driver->name; + if ((ret = serial_source_remove(sdi->session, serial)) < 0) { sr_err("%s: Failed to remove source: %d.", prefix, ret); return ret; @@ -227,34 +320,38 @@ SR_PRIV int std_serial_dev_acquisition_stop(struct sr_dev_inst *sdi) return ret; } - std_session_send_df_end(sdi); - - return SR_OK; + return std_session_send_df_end(sdi); } #endif /** - * Standard driver dev_clear() helper. + * Standard driver dev_clear() callback API helper. * * Clear driver, this means, close all instances. * * This function can be used to implement the dev_clear() driver API * callback. dev_close() is called before every sr_dev_inst is cleared. * - * The only limitation is driver-specific device contexts (sdi->priv). + * The only limitation is driver-specific device contexts (sdi->priv / devc). * These are freed, but any dynamic allocation within structs stored * there cannot be freed. * - * @param driver The driver which will have its instances released. - * @param clear_private If not NULL, this points to a function called - * with sdi->priv as argument. The function can then clear any device - * instance-specific resources kept there. It must also clear the struct - * pointed to by sdi->priv. + * @param[in] driver The driver which will have its instances released. + * Must not be NULL. + * @param[in] clear_private If not NULL, this points to a function called + * with sdi->priv (devc) as argument. The function can then clear + * any device instance-specific resources kept there. + * It must NOT clear the struct pointed to by sdi->priv (devc), + * since this function will always free it after clear_private() + * has run. * - * @return SR_OK on success. + * @retval SR_OK Success. + * @retval SR_ERR_ARG Invalid argument. + * @retval SR_ERR_BUG Implementation bug. + * @retval other Other error. */ -SR_PRIV int std_dev_clear(const struct sr_dev_driver *driver, +SR_PRIV int std_dev_clear_with_callback(const struct sr_dev_driver *driver, std_dev_clear_callback clear_private) { struct drv_context *drvc; @@ -262,13 +359,17 @@ SR_PRIV int std_dev_clear(const struct sr_dev_driver *driver, GSList *l; int ret; - if (!(drvc = driver->context)) - /* Driver was never initialized, nothing to do. */ - return SR_OK; + if (!driver) { + sr_err("%s: Invalid argument.", __func__); + return SR_ERR_ARG; + } + + drvc = driver->context; /* Caller checked for context != NULL. */ ret = SR_OK; for (l = drvc->instances; l; l = l->next) { if (!(sdi = l->data)) { + sr_err("%s: Invalid device instance.", __func__); ret = SR_ERR_BUG; continue; } @@ -289,12 +390,13 @@ SR_PRIV int std_dev_clear(const struct sr_dev_driver *driver, if (sdi->inst_type == SR_INST_MODBUS) sr_modbus_free(sdi->conn); } + + /* Clear driver-specific stuff, if any. */ if (clear_private) - /* The helper function is responsible for freeing - * its own sdi->priv! */ clear_private(sdi->priv); - else - g_free(sdi->priv); + + /* Clear sdi->priv (devc). */ + g_free(sdi->priv); sr_dev_inst_free(sdi); } @@ -305,27 +407,39 @@ SR_PRIV int std_dev_clear(const struct sr_dev_driver *driver, return ret; } +SR_PRIV int std_dev_clear(const struct sr_dev_driver *driver) +{ + return std_dev_clear_with_callback(driver, NULL); +} + /** - * Standard implementation for the driver dev_list() callback + * Standard driver dev_list() callback API helper. * - * This function can be used as the dev_list callback by most drivers that use - * the standard helper functions. It returns the devices contained in the driver - * context instances list. + * This function can be used as the dev_list() callback by most drivers. * - * @param di The driver instance to use. + * Return the devices contained in the driver context instances list. * - * @return The list of devices/instances of this driver, or NULL upon errors - * or if the list is empty. + * @param[in] di The driver instance to use. Must not be NULL. + * + * @retval NULL Error, or the list is empty. + * @retval other The list of device instances of this driver. */ SR_PRIV GSList *std_dev_list(const struct sr_dev_driver *di) { - struct drv_context *drvc = di->context; + struct drv_context *drvc; + + if (!di) { + sr_err("%s: Invalid argument.", __func__); + return NULL; + } + + drvc = di->context; return drvc->instances; } /** - * Standard scan() callback API helper. + * Standard driver scan() callback API helper. * * This function can be used to perform common tasks required by a driver's * scan() callback. It will initialize the driver for each device on the list @@ -352,8 +466,9 @@ SR_PRIV GSList *std_dev_list(const struct sr_dev_driver *di) * } * @endcode * - * @param di The driver instance to use. Must not be NULL. - * @param devices List of newly discovered devices (struct sr_dev_inst). + * @param[in] di The driver instance to use. Must not be NULL. + * @param[in] devices List of newly discovered devices (struct sr_dev_inst). + * May be NULL. * * @return The @p devices list. */ @@ -372,7 +487,7 @@ SR_PRIV GSList *std_scan_complete(struct sr_dev_driver *di, GSList *devices) for (l = devices; l; l = l->next) { struct sr_dev_inst *sdi = l->data; if (!sdi) { - sr_err("Invalid driver instance, cannot complete scan."); + sr_err("Invalid device instance, cannot complete scan."); return NULL; } sdi->driver = di; @@ -382,3 +497,84 @@ SR_PRIV GSList *std_scan_complete(struct sr_dev_driver *di, GSList *devices) return devices; } + +SR_PRIV int std_opts_config_list(uint32_t key, GVariant **data, + const struct sr_dev_inst *sdi, const struct sr_channel_group *cg, + const uint32_t scanopts[], size_t scansize, const uint32_t drvopts[], + size_t drvsize, const uint32_t devopts[], size_t devsize) +{ + switch (key) { + case SR_CONF_SCAN_OPTIONS: + /* Always return scanopts, regardless of sdi or cg. */ + if (!scanopts) + return SR_ERR_ARG; + *data = g_variant_new_fixed_array(G_VARIANT_TYPE_UINT32, + scanopts, scansize, sizeof(uint32_t)); + break; + case SR_CONF_DEVICE_OPTIONS: + if (!sdi) { + /* sdi == NULL: return drvopts. */ + if (!drvopts) + return SR_ERR_ARG; + *data = g_variant_new_fixed_array(G_VARIANT_TYPE_UINT32, + drvopts, drvsize, sizeof(uint32_t)); + } else if (sdi && !cg) { + /* sdi != NULL, cg == NULL: return devopts. */ + if (!devopts) + return SR_ERR_ARG; + *data = g_variant_new_fixed_array(G_VARIANT_TYPE_UINT32, + devopts, devsize, sizeof(uint32_t)); + } else { + /* + * Note: sdi != NULL, cg != NULL is not handled by + * this function since it's very driver-specific. + */ + sr_err("%s: %s: sdi/cg != NULL: not handling.", + sdi->driver->name, __func__); + return SR_ERR_ARG; + } + break; + default: + return SR_ERR_NA; + } + + return SR_OK; +} + +SR_PRIV GVariant *std_gvar_tuple_array(const uint64_t (*a)[][2], unsigned int n) +{ + unsigned int i; + GVariant *rational[2]; + GVariantBuilder gvb; + + g_variant_builder_init(&gvb, G_VARIANT_TYPE_ARRAY); + + for (i = 0; i < n; i++) { + rational[0] = g_variant_new_uint64((*a)[i][0]); + rational[1] = g_variant_new_uint64((*a)[i][1]); + + /* FIXME: Valgrind reports a memory leak here. */ + g_variant_builder_add_value(&gvb, g_variant_new_tuple(rational, 2)); + } + + return g_variant_builder_end(&gvb); +} + +SR_PRIV GVariant *std_gvar_tuple_rational(const struct sr_rational *r, unsigned int n) +{ + unsigned int i; + GVariant *rational[2]; + GVariantBuilder gvb; + + g_variant_builder_init(&gvb, G_VARIANT_TYPE_ARRAY); + + for (i = 0; i < n; i++) { + rational[0] = g_variant_new_uint64(r[i].p); + rational[1] = g_variant_new_uint64(r[i].q); + + /* FIXME: Valgrind reports a memory leak here. */ + g_variant_builder_add_value(&gvb, g_variant_new_tuple(rational, 2)); + } + + return g_variant_builder_end(&gvb); +}