2 * This file is part of the libsigrok project.
4 * Copyright (C) 2013 Uwe Hermann <uwe@hermann-uwe.de>
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.
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.
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
24 * Standard API helper functions.
31 #include <libsigrok/libsigrok.h>
32 #include "libsigrok-internal.h"
35 #define LOG_PREFIX "std"
38 * Standard sr_driver_init() API helper.
40 * This function can be used to simplify most driver's init() API callback.
42 * It creates a new 'struct drv_context' (drvc), assigns sr_ctx to it, and
43 * then 'drvc' is assigned to the 'struct sr_dev_driver' (di) that is passed.
45 * @param di The driver instance to use.
46 * @param sr_ctx The libsigrok context to assign.
48 * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments.
50 SR_PRIV int std_init(struct sr_dev_driver *di, struct sr_context *sr_ctx)
52 struct drv_context *drvc;
54 drvc = g_malloc0(sizeof(struct drv_context));
55 drvc->sr_ctx = sr_ctx;
56 drvc->instances = NULL;
63 * Standard driver cleanup() callback API helper
65 * @param di The driver instance to use.
67 * Frees all device instances by calling sr_dev_clear() and then releases any
68 * resources allocated by std_init().
70 * @retval SR_OK Success
71 * @retval SR_ERR_ARG Invalid driver
74 SR_PRIV int std_cleanup(const struct sr_dev_driver *di)
78 ret = sr_dev_clear(di);
85 * Standard API helper for sending an SR_DF_HEADER packet.
87 * This function can be used to simplify most driver's
88 * dev_acquisition_start() API callback.
90 * @param sdi The device instance to use.
92 * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
93 * SR_ERR upon other errors.
95 SR_PRIV int std_session_send_df_header(const struct sr_dev_inst *sdi)
97 const char *prefix = (sdi->driver) ? sdi->driver->name : "unknown";
99 struct sr_datafeed_packet packet;
100 struct sr_datafeed_header header;
102 sr_dbg("%s: Starting acquisition.", prefix);
104 /* Send header packet to the session bus. */
105 sr_dbg("%s: Sending SR_DF_HEADER packet.", prefix);
106 packet.type = SR_DF_HEADER;
107 packet.payload = (uint8_t *)&header;
108 header.feed_version = 1;
109 gettimeofday(&header.starttime, NULL);
111 if ((ret = sr_session_send(sdi, &packet)) < 0) {
112 sr_err("%s: Failed to send header packet: %d.", prefix, ret);
120 * Standard API helper for sending an SR_DF_END packet.
122 * @param sdi The device instance to use. Must not be NULL.
124 * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
125 * SR_ERR upon other errors.
127 SR_PRIV int std_session_send_df_end(const struct sr_dev_inst *sdi)
129 const char *prefix = (sdi->driver) ? sdi->driver->name : "unknown";
131 struct sr_datafeed_packet packet;
136 sr_dbg("%s: Sending SR_DF_END packet.", prefix);
138 packet.type = SR_DF_END;
139 packet.payload = NULL;
141 if ((ret = sr_session_send(sdi, &packet)) < 0) {
142 sr_err("%s: Failed to send SR_DF_END packet: %d.", prefix, ret);
149 #ifdef HAVE_LIBSERIALPORT
152 * Standard serial driver dev_open() helper.
154 * This function can be used to implement the dev_open() driver API
155 * callback in drivers that use a serial port. The port is opened
156 * with the SERIAL_RDWR flag.
158 * If the open succeeded, the status field of the given sdi is set
161 * @retval SR_OK Success.
162 * @retval SR_ERR Serial port open failed.
164 SR_PRIV int std_serial_dev_open(struct sr_dev_inst *sdi)
166 struct sr_serial_dev_inst *serial;
169 if (serial_open(serial, SERIAL_RDWR) != SR_OK)
172 sdi->status = SR_ST_ACTIVE;
178 * Standard serial driver dev_close() helper.
180 * This function can be used to implement the dev_close() driver API
181 * callback in drivers that use a serial port.
183 * After closing the port, the status field of the given sdi is set
186 * @retval SR_OK Success.
188 SR_PRIV int std_serial_dev_close(struct sr_dev_inst *sdi)
190 struct sr_serial_dev_inst *serial;
193 if (serial && sdi->status == SR_ST_ACTIVE) {
194 serial_close(serial);
195 sdi->status = SR_ST_INACTIVE;
202 * Standard sr_session_stop() API helper.
204 * This function can be used to simplify most (serial port based) driver's
205 * dev_acquisition_stop() API callback.
207 * @param sdi The device instance for which acquisition should stop.
210 * @retval SR_OK Success.
211 * @retval SR_ERR_ARG Invalid arguments.
212 * @retval SR_ERR_DEV_CLOSED Device is closed.
213 * @retval SR_ERR Other errors.
215 SR_PRIV int std_serial_dev_acquisition_stop(struct sr_dev_inst *sdi)
217 struct sr_serial_dev_inst *serial = sdi->conn;
218 const char *prefix = sdi->driver->name;
221 if (sdi->status != SR_ST_ACTIVE) {
222 sr_err("%s: Device inactive, can't stop acquisition.", prefix);
223 return SR_ERR_DEV_CLOSED;
226 sr_dbg("%s: Stopping acquisition.", prefix);
228 if ((ret = serial_source_remove(sdi->session, serial)) < 0) {
229 sr_err("%s: Failed to remove source: %d.", prefix, ret);
233 if ((ret = sdi->driver->dev_close(sdi)) < 0) {
234 sr_err("%s: Failed to close device: %d.", prefix, ret);
238 std_session_send_df_end(sdi);
246 * Standard driver dev_clear() helper.
248 * Clear driver, this means, close all instances.
250 * This function can be used to implement the dev_clear() driver API
251 * callback. dev_close() is called before every sr_dev_inst is cleared.
253 * The only limitation is driver-specific device contexts (sdi->priv).
254 * These are freed, but any dynamic allocation within structs stored
255 * there cannot be freed.
257 * @param driver The driver which will have its instances released.
258 * @param clear_private If not NULL, this points to a function called
259 * with sdi->priv as argument. The function can then clear any device
260 * instance-specific resources kept there. It must also clear the struct
261 * pointed to by sdi->priv.
263 * @return SR_OK on success.
265 SR_PRIV int std_dev_clear(const struct sr_dev_driver *driver,
266 std_dev_clear_callback clear_private)
268 struct drv_context *drvc;
269 struct sr_dev_inst *sdi;
273 if (!(drvc = driver->context))
274 /* Driver was never initialized, nothing to do. */
278 for (l = drvc->instances; l; l = l->next) {
279 if (!(sdi = l->data)) {
283 if (driver->dev_close)
284 driver->dev_close(sdi);
287 #ifdef HAVE_LIBSERIALPORT
288 if (sdi->inst_type == SR_INST_SERIAL)
289 sr_serial_dev_inst_free(sdi->conn);
291 #ifdef HAVE_LIBUSB_1_0
292 if (sdi->inst_type == SR_INST_USB)
293 sr_usb_dev_inst_free(sdi->conn);
295 if (sdi->inst_type == SR_INST_SCPI)
296 sr_scpi_free(sdi->conn);
297 if (sdi->inst_type == SR_INST_MODBUS)
298 sr_modbus_free(sdi->conn);
301 /* The helper function is responsible for freeing
302 * its own sdi->priv! */
303 clear_private(sdi->priv);
307 sr_dev_inst_free(sdi);
310 g_slist_free(drvc->instances);
311 drvc->instances = NULL;
317 * Standard implementation for the driver dev_list() callback
319 * This function can be used as the dev_list callback by most drivers that use
320 * the standard helper functions. It returns the devices contained in the driver
321 * context instances list.
323 * @param di The driver instance to use.
325 * @return The list of devices/instances of this driver, or NULL upon errors
326 * or if the list is empty.
328 SR_PRIV GSList *std_dev_list(const struct sr_dev_driver *di)
330 struct drv_context *drvc = di->context;
332 return drvc->instances;
336 * Standard scan() callback API helper.
338 * This function can be used to perform common tasks required by a driver's
339 * scan() callback. It will initialize the driver for each device on the list
340 * and add the devices on the list to the driver's device instance list.
341 * Usually it should be used as the last step in the scan() callback, right
344 * Note: This function can only be used if std_init() has been called
345 * previously by the driver.
349 * static GSList *scan(struct sr_dev_driver *di, GSList *options)
351 * struct GSList *device;
352 * struct sr_dev_inst *sdi;
354 * sdi = g_new0(sr_dev_inst, 1);
357 * devices = g_slist_append(devices, sdi);
359 * return std_scan_complete(di, devices);
363 * @param di The driver instance to use. Must not be NULL.
364 * @param devices List of newly discovered devices (struct sr_dev_inst).
366 * @return The @p devices list.
368 SR_PRIV GSList *std_scan_complete(struct sr_dev_driver *di, GSList *devices)
370 struct drv_context *drvc;
374 sr_err("Invalid driver instance (di), cannot complete scan.");
380 for (l = devices; l; l = l->next) {
381 struct sr_dev_inst *sdi = l->data;
383 sr_err("Invalid driver instance, cannot complete scan.");
389 drvc->instances = g_slist_concat(drvc->instances, g_slist_copy(devices));