2 * This file is part of the libsigrok project.
4 * Copyright (C) 2014 Aurelien Jacobs <aurel@gnuage.org>
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.
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, see <http://www.gnu.org/licenses/>.
22 #include <libsigrok/libsigrok.h>
23 #include "libsigrok-internal.h"
26 #define LOG_PREFIX "scpi_usbtmc"
28 #define MAX_TRANSFER_LENGTH 2048
29 #define TRANSFER_TIMEOUT 1000
31 struct scpi_usbtmc_libusb {
32 struct sr_context *ctx;
33 struct sr_usb_dev_inst *usb;
34 int detached_kernel_driver;
39 uint8_t usbtmc_int_cap;
40 uint8_t usbtmc_dev_cap;
41 uint8_t usb488_dev_cap;
43 uint8_t bulkin_attributes;
44 uint8_t buffer[MAX_TRANSFER_LENGTH];
46 int response_bytes_read;
50 /* Some USBTMC-specific enums, as defined in the USBTMC standard. */
51 #define SUBCLASS_USBTMC 0x03
52 #define USBTMC_USB488 0x01
55 /* USBTMC control requests */
56 INITIATE_ABORT_BULK_OUT = 1,
57 CHECK_ABORT_BULK_OUT_STATUS = 2,
58 INITIATE_ABORT_BULK_IN = 3,
59 CHECK_ABORT_BULK_IN_STATUS = 4,
61 CHECK_CLEAR_STATUS = 6,
65 /* USB488 control requests */
66 READ_STATUS_BYTE = 128,
72 /* USBTMC status codes */
73 #define USBTMC_STATUS_SUCCESS 0x01
75 /* USBTMC capabilities */
76 #define USBTMC_INT_CAP_LISTEN_ONLY 0x01
77 #define USBTMC_INT_CAP_TALK_ONLY 0x02
78 #define USBTMC_INT_CAP_INDICATOR 0x04
80 #define USBTMC_DEV_CAP_TERMCHAR 0x01
82 #define USB488_DEV_CAP_DT1 0x01
83 #define USB488_DEV_CAP_RL1 0x02
84 #define USB488_DEV_CAP_SR1 0x04
85 #define USB488_DEV_CAP_SCPI 0x08
87 /* Bulk messages constants */
88 #define USBTMC_BULK_HEADER_SIZE 12
90 /* Bulk MsgID values */
91 #define DEV_DEP_MSG_OUT 1
92 #define REQUEST_DEV_DEP_MSG_IN 2
93 #define DEV_DEP_MSG_IN 2
95 /* bmTransferAttributes */
97 #define TERM_CHAR_ENABLED 0x02
99 struct usbtmc_blacklist {
104 /* Devices that publish RL1 support, but don't support it. */
105 static struct usbtmc_blacklist blacklist_remote[] = {
106 { 0x1ab1, 0x0588 }, /* Rigol DS1000 series */
107 { 0x1ab1, 0x04b0 }, /* Rigol DS2000 series */
108 { 0x1ab1, 0x04b1 }, /* Rigol DS4000 series */
109 { 0x0957, 0x0588 }, /* Agilent DSO1000 series (rebadged Rigol DS1000) */
110 { 0x0b21, 0xffff }, /* All Yokogawa devices */
111 { 0xf4ec, 0xffff }, /* All Siglent SDS devices */
115 /* Devices that shall get reset during open(). */
116 static struct usbtmc_blacklist whitelist_usb_reset[] = {
117 { 0xf4ec, 0xffff }, /* All Siglent SDS devices */
121 static GSList *scpi_usbtmc_libusb_scan(struct drv_context *drvc)
123 struct libusb_device **devlist;
124 struct libusb_device_descriptor des;
125 struct libusb_config_descriptor *confdes;
126 const struct libusb_interface_descriptor *intfdes;
127 GSList *resources = NULL;
128 int confidx, intfidx, ret, i;
131 ret = libusb_get_device_list(drvc->sr_ctx->libusb_ctx, &devlist);
133 sr_err("Failed to get device list: %s.",
134 libusb_error_name(ret));
137 for (i = 0; devlist[i]; i++) {
138 libusb_get_device_descriptor(devlist[i], &des);
140 for (confidx = 0; confidx < des.bNumConfigurations; confidx++) {
141 if ((ret = libusb_get_config_descriptor(devlist[i], confidx, &confdes)) < 0) {
142 if (ret != LIBUSB_ERROR_NOT_FOUND)
143 sr_dbg("Failed to get configuration descriptor: %s, "
144 "ignoring device.", libusb_error_name(ret));
147 for (intfidx = 0; intfidx < confdes->bNumInterfaces; intfidx++) {
148 intfdes = confdes->interface[intfidx].altsetting;
149 if (intfdes->bInterfaceClass != LIBUSB_CLASS_APPLICATION ||
150 intfdes->bInterfaceSubClass != SUBCLASS_USBTMC ||
151 intfdes->bInterfaceProtocol != USBTMC_USB488)
153 sr_dbg("Found USBTMC device (VID:PID = %04x:%04x, "
154 "bus.address = %d.%d).", des.idVendor, des.idProduct,
155 libusb_get_bus_number(devlist[i]),
156 libusb_get_device_address(devlist[i]));
157 res = g_strdup_printf("usbtmc/%d.%d",
158 libusb_get_bus_number(devlist[i]),
159 libusb_get_device_address(devlist[i]));
160 resources = g_slist_append(resources, res);
162 libusb_free_config_descriptor(confdes);
165 libusb_free_device_list(devlist, 1);
167 /* No log message for #devices found (caller will log that). */
172 static int scpi_usbtmc_libusb_dev_inst_new(void *priv, struct drv_context *drvc,
173 const char *resource, char **params, const char *serialcomm)
175 struct scpi_usbtmc_libusb *uscpi = priv;
181 if (!params || !params[1]) {
182 sr_err("Invalid parameters.");
186 uscpi->ctx = drvc->sr_ctx;
187 devices = sr_usb_find(uscpi->ctx->libusb_ctx, params[1]);
188 if (g_slist_length(devices) != 1) {
189 sr_err("Failed to find USB device '%s'.", params[1]);
190 g_slist_free_full(devices, (GDestroyNotify)sr_usb_dev_inst_free);
193 uscpi->usb = devices->data;
194 g_slist_free(devices);
199 static int check_usbtmc_blacklist(struct usbtmc_blacklist *blacklist,
200 uint16_t vid, uint16_t pid)
204 for (i = 0; blacklist[i].vid; i++) {
205 if ((blacklist[i].vid == vid && blacklist[i].pid == 0xFFFF) ||
206 (blacklist[i].vid == vid && blacklist[i].pid == pid))
213 static int scpi_usbtmc_remote(struct scpi_usbtmc_libusb *uscpi)
215 struct sr_usb_dev_inst *usb = uscpi->usb;
216 struct libusb_device *dev;
217 struct libusb_device_descriptor des;
221 if (!(uscpi->usb488_dev_cap & USB488_DEV_CAP_RL1))
224 dev = libusb_get_device(usb->devhdl);
225 libusb_get_device_descriptor(dev, &des);
226 if (check_usbtmc_blacklist(blacklist_remote, des.idVendor, des.idProduct))
229 sr_dbg("Locking out local control.");
230 ret = libusb_control_transfer(usb->devhdl, LIBUSB_ENDPOINT_IN |
231 LIBUSB_REQUEST_TYPE_CLASS | LIBUSB_RECIPIENT_INTERFACE,
232 REN_CONTROL, 1, uscpi->interface, &status, 1, TRANSFER_TIMEOUT);
233 if (ret < 0 || status != USBTMC_STATUS_SUCCESS) {
235 sr_dbg("Failed to enter REN state: %s.", libusb_error_name(ret));
237 sr_dbg("Failed to enter REN state: USBTMC status %d.", status);
241 ret = libusb_control_transfer(usb->devhdl, LIBUSB_ENDPOINT_IN |
242 LIBUSB_REQUEST_TYPE_CLASS | LIBUSB_RECIPIENT_INTERFACE,
243 LOCAL_LOCKOUT, 0, uscpi->interface, &status, 1,
245 if (ret < 0 || status != USBTMC_STATUS_SUCCESS) {
247 sr_dbg("Failed to enter local lockout state: %s.",
248 libusb_error_name(ret));
250 sr_dbg("Failed to enter local lockout state: USBTMC "
251 "status %d.", status);
258 static void scpi_usbtmc_local(struct scpi_usbtmc_libusb *uscpi)
260 struct sr_usb_dev_inst *usb = uscpi->usb;
261 struct libusb_device *dev;
262 struct libusb_device_descriptor des;
266 if (!(uscpi->usb488_dev_cap & USB488_DEV_CAP_RL1))
269 dev = libusb_get_device(usb->devhdl);
270 libusb_get_device_descriptor(dev, &des);
271 if (check_usbtmc_blacklist(blacklist_remote, des.idVendor, des.idProduct))
274 sr_dbg("Returning local control.");
275 ret = libusb_control_transfer(usb->devhdl, LIBUSB_ENDPOINT_IN |
276 LIBUSB_REQUEST_TYPE_CLASS | LIBUSB_RECIPIENT_INTERFACE,
277 GO_TO_LOCAL, 0, uscpi->interface, &status, 1, TRANSFER_TIMEOUT);
278 if (ret < 0 || status != USBTMC_STATUS_SUCCESS) {
280 sr_dbg("Failed to clear local lockout state: %s.",
281 libusb_error_name(ret));
283 sr_dbg("Failed to clear local lockout state: USBTMC "
284 "status %d.", status);
290 static int scpi_usbtmc_libusb_open(struct sr_scpi_dev_inst *scpi)
292 struct scpi_usbtmc_libusb *uscpi = scpi->priv;
293 struct sr_usb_dev_inst *usb = uscpi->usb;
294 struct libusb_device *dev;
295 struct libusb_device_descriptor des;
296 struct libusb_config_descriptor *confdes;
297 const struct libusb_interface_descriptor *intfdes;
298 const struct libusb_endpoint_descriptor *ep;
299 int confidx, intfidx, epidx, config = 0, current_config;
300 uint8_t capabilities[24];
307 if (sr_usb_open(uscpi->ctx->libusb_ctx, usb) != SR_OK)
310 dev = libusb_get_device(usb->devhdl);
311 libusb_get_device_descriptor(dev, &des);
313 for (confidx = 0; confidx < des.bNumConfigurations; confidx++) {
314 if ((ret = libusb_get_config_descriptor(dev, confidx, &confdes)) < 0) {
315 if (ret != LIBUSB_ERROR_NOT_FOUND)
316 sr_dbg("Failed to get configuration descriptor: %s, "
317 "ignoring device.", libusb_error_name(ret));
320 for (intfidx = 0; intfidx < confdes->bNumInterfaces; intfidx++) {
321 intfdes = confdes->interface[intfidx].altsetting;
322 if (intfdes->bInterfaceClass != LIBUSB_CLASS_APPLICATION ||
323 intfdes->bInterfaceSubClass != SUBCLASS_USBTMC ||
324 intfdes->bInterfaceProtocol != USBTMC_USB488)
326 uscpi->interface = intfdes->bInterfaceNumber;
327 config = confdes->bConfigurationValue;
328 sr_dbg("Interface %d configuration %d.", uscpi->interface, config);
329 for (epidx = 0; epidx < intfdes->bNumEndpoints; epidx++) {
330 ep = &intfdes->endpoint[epidx];
331 if (ep->bmAttributes == LIBUSB_TRANSFER_TYPE_BULK &&
332 !(ep->bEndpointAddress & (LIBUSB_ENDPOINT_DIR_MASK))) {
333 uscpi->bulk_out_ep = ep->bEndpointAddress;
334 sr_dbg("Bulk OUT EP %d", uscpi->bulk_out_ep);
336 if (ep->bmAttributes == LIBUSB_TRANSFER_TYPE_BULK &&
337 ep->bEndpointAddress & (LIBUSB_ENDPOINT_DIR_MASK)) {
338 uscpi->bulk_in_ep = ep->bEndpointAddress;
339 sr_dbg("Bulk IN EP %d", uscpi->bulk_in_ep & 0x7f);
341 if (ep->bmAttributes == LIBUSB_TRANSFER_TYPE_INTERRUPT &&
342 ep->bEndpointAddress & (LIBUSB_ENDPOINT_DIR_MASK)) {
343 uscpi->interrupt_ep = ep->bEndpointAddress;
344 sr_dbg("Interrupt EP %d", uscpi->interrupt_ep & 0x7f);
349 libusb_free_config_descriptor(confdes);
355 sr_err("Failed to find USBTMC interface.");
359 if (libusb_kernel_driver_active(usb->devhdl, uscpi->interface) == 1) {
360 if ((ret = libusb_detach_kernel_driver(usb->devhdl,
361 uscpi->interface)) < 0) {
362 sr_err("Failed to detach kernel driver: %s.",
363 libusb_error_name(ret));
366 uscpi->detached_kernel_driver = 1;
369 if (libusb_get_configuration(usb->devhdl, ¤t_config) == 0
370 && current_config != config) {
371 if ((ret = libusb_set_configuration(usb->devhdl, config)) < 0) {
372 sr_err("Failed to set configuration: %s.",
373 libusb_error_name(ret));
378 if ((ret = libusb_claim_interface(usb->devhdl, uscpi->interface)) < 0) {
379 sr_err("Failed to claim interface: %s.",
380 libusb_error_name(ret));
384 /* Optionally reset the USB device. */
385 do_reset = check_usbtmc_blacklist(whitelist_usb_reset,
386 des.idVendor, des.idProduct);
388 libusb_reset_device(usb->devhdl);
390 /* Get capabilities. */
391 ret = libusb_control_transfer(usb->devhdl, LIBUSB_ENDPOINT_IN |
392 LIBUSB_REQUEST_TYPE_CLASS | LIBUSB_RECIPIENT_INTERFACE,
393 GET_CAPABILITIES, 0, uscpi->interface, capabilities,
394 sizeof(capabilities), TRANSFER_TIMEOUT);
395 if (ret == sizeof(capabilities)) {
396 uscpi->usbtmc_int_cap = capabilities[ 4];
397 uscpi->usbtmc_dev_cap = capabilities[ 5];
398 uscpi->usb488_dev_cap = capabilities[15];
400 sr_dbg("Device capabilities: %s%s%s%s%s, %s, %s",
401 uscpi->usb488_dev_cap & USB488_DEV_CAP_SCPI ? "SCPI, " : "",
402 uscpi->usbtmc_dev_cap & USBTMC_DEV_CAP_TERMCHAR ? "TermChar, ": "",
403 uscpi->usbtmc_int_cap & USBTMC_INT_CAP_LISTEN_ONLY ? "L3, " :
404 uscpi->usbtmc_int_cap & USBTMC_INT_CAP_TALK_ONLY ? "" : "L4, ",
405 uscpi->usbtmc_int_cap & USBTMC_INT_CAP_TALK_ONLY ? "T5, " :
406 uscpi->usbtmc_int_cap & USBTMC_INT_CAP_LISTEN_ONLY ? "" : "T6, ",
407 uscpi->usb488_dev_cap & USB488_DEV_CAP_SR1 ? "SR1" : "SR0",
408 uscpi->usb488_dev_cap & USB488_DEV_CAP_RL1 ? "RL1" : "RL0",
409 uscpi->usb488_dev_cap & USB488_DEV_CAP_DT1 ? "DT1" : "DT0");
411 scpi_usbtmc_remote(uscpi);
416 static int scpi_usbtmc_libusb_source_add(struct sr_session *session,
417 void *priv, int events, int timeout, sr_receive_data_callback cb,
420 struct scpi_usbtmc_libusb *uscpi = priv;
422 return usb_source_add(session, uscpi->ctx, timeout, cb, cb_data);
425 static int scpi_usbtmc_libusb_source_remove(struct sr_session *session,
428 struct scpi_usbtmc_libusb *uscpi = priv;
429 return usb_source_remove(session, uscpi->ctx);
432 static void usbtmc_bulk_out_header_write(void *header, uint8_t MsgID,
434 uint32_t TransferSize,
435 uint8_t bmTransferAttributes,
438 W8(header + 0, MsgID);
439 W8(header + 1, bTag);
440 W8(header + 2, ~bTag);
442 WL32(header + 4, TransferSize);
443 W8(header + 8, bmTransferAttributes);
444 W8(header + 9, TermChar);
445 WL16(header + 10, 0);
448 static int usbtmc_bulk_in_header_read(void *header, uint8_t MsgID,
450 int32_t *TransferSize,
451 uint8_t *bmTransferAttributes)
453 if (R8(header + 0) != MsgID ||
454 R8(header + 1) != bTag ||
455 R8(header + 2) != (unsigned char)~bTag)
458 *TransferSize = RL32(header + 4);
459 if (bmTransferAttributes)
460 *bmTransferAttributes = R8(header + 8);
465 static int scpi_usbtmc_bulkout(struct scpi_usbtmc_libusb *uscpi,
466 uint8_t msg_id, const void *data, int32_t size,
467 uint8_t transfer_attributes)
469 struct sr_usb_dev_inst *usb = uscpi->usb;
470 int padded_size, ret, transferred;
472 if (data && (size + USBTMC_BULK_HEADER_SIZE + 3) > (int)sizeof(uscpi->buffer)) {
473 sr_err("USBTMC bulk out transfer is too big.");
478 uscpi->bTag += !uscpi->bTag; /* bTag == 0 is invalid so avoid it. */
480 usbtmc_bulk_out_header_write(uscpi->buffer, msg_id, uscpi->bTag,
481 size, transfer_attributes, 0);
483 memcpy(uscpi->buffer + USBTMC_BULK_HEADER_SIZE, data, size);
486 size += USBTMC_BULK_HEADER_SIZE;
487 padded_size = (size + 3) & ~0x3;
488 memset(uscpi->buffer + size, 0, padded_size - size);
490 ret = libusb_bulk_transfer(usb->devhdl, uscpi->bulk_out_ep,
491 uscpi->buffer, padded_size, &transferred,
494 sr_err("USBTMC bulk out transfer error: %s.",
495 libusb_error_name(ret));
499 if (transferred < padded_size) {
500 sr_dbg("USBTMC bulk out partial transfer (%d/%d bytes).",
501 transferred, padded_size);
505 return transferred - USBTMC_BULK_HEADER_SIZE;
508 static int scpi_usbtmc_bulkin_start(struct scpi_usbtmc_libusb *uscpi,
509 uint8_t msg_id, void *data, int32_t size,
510 uint8_t *transfer_attributes)
512 struct sr_usb_dev_inst *usb = uscpi->usb;
513 int ret, transferred, message_size;
515 ret = libusb_bulk_transfer(usb->devhdl, uscpi->bulk_in_ep, data, size,
516 &transferred, TRANSFER_TIMEOUT);
518 sr_err("USBTMC bulk in transfer error: %s.",
519 libusb_error_name(ret));
523 if (usbtmc_bulk_in_header_read(data, msg_id, uscpi->bTag, &message_size,
524 transfer_attributes) != SR_OK) {
525 sr_err("USBTMC invalid bulk in header.");
529 message_size += USBTMC_BULK_HEADER_SIZE;
530 uscpi->response_length = MIN(transferred, message_size);
531 uscpi->response_bytes_read = USBTMC_BULK_HEADER_SIZE;
532 uscpi->remaining_length = message_size - uscpi->response_length;
534 return transferred - USBTMC_BULK_HEADER_SIZE;
537 static int scpi_usbtmc_bulkin_continue(struct scpi_usbtmc_libusb *uscpi,
538 void *data, int size)
540 struct sr_usb_dev_inst *usb = uscpi->usb;
541 int ret, transferred;
543 ret = libusb_bulk_transfer(usb->devhdl, uscpi->bulk_in_ep, data, size,
544 &transferred, TRANSFER_TIMEOUT);
546 sr_err("USBTMC bulk in transfer error: %s.",
547 libusb_error_name(ret));
551 uscpi->response_length = MIN(transferred, uscpi->remaining_length);
552 uscpi->response_bytes_read = 0;
553 uscpi->remaining_length -= uscpi->response_length;
558 static int scpi_usbtmc_libusb_send(void *priv, const char *command)
560 struct scpi_usbtmc_libusb *uscpi = priv;
562 if (scpi_usbtmc_bulkout(uscpi, DEV_DEP_MSG_OUT,
563 command, strlen(command), EOM) <= 0)
566 sr_spew("Successfully sent SCPI command: '%s'.", command);
571 static int scpi_usbtmc_libusb_read_begin(void *priv)
573 struct scpi_usbtmc_libusb *uscpi = priv;
575 uscpi->remaining_length = 0;
577 if (scpi_usbtmc_bulkout(uscpi, REQUEST_DEV_DEP_MSG_IN,
578 NULL, INT32_MAX, 0) < 0)
580 if (scpi_usbtmc_bulkin_start(uscpi, DEV_DEP_MSG_IN,
581 uscpi->buffer, sizeof(uscpi->buffer),
582 &uscpi->bulkin_attributes) < 0)
588 static int scpi_usbtmc_libusb_read_data(void *priv, char *buf, int maxlen)
590 struct scpi_usbtmc_libusb *uscpi = priv;
593 if (uscpi->response_bytes_read >= uscpi->response_length) {
594 if (uscpi->remaining_length > 0) {
595 if (scpi_usbtmc_bulkin_continue(uscpi, uscpi->buffer,
596 sizeof(uscpi->buffer)) <= 0)
599 if (uscpi->bulkin_attributes & EOM)
601 if (scpi_usbtmc_libusb_read_begin(uscpi) < 0)
606 read_length = MIN(uscpi->response_length - uscpi->response_bytes_read, maxlen);
608 memcpy(buf, uscpi->buffer + uscpi->response_bytes_read, read_length);
610 uscpi->response_bytes_read += read_length;
615 static int scpi_usbtmc_libusb_read_complete(void *priv)
617 struct scpi_usbtmc_libusb *uscpi = priv;
618 return uscpi->response_bytes_read >= uscpi->response_length &&
619 uscpi->remaining_length <= 0 &&
620 uscpi->bulkin_attributes & EOM;
623 static int scpi_usbtmc_libusb_close(struct sr_scpi_dev_inst *scpi)
625 struct scpi_usbtmc_libusb *uscpi = scpi->priv;
626 struct sr_usb_dev_inst *usb = uscpi->usb;
632 scpi_usbtmc_local(uscpi);
634 if ((ret = libusb_release_interface(usb->devhdl, uscpi->interface)) < 0)
635 sr_err("Failed to release interface: %s.",
636 libusb_error_name(ret));
638 if (uscpi->detached_kernel_driver) {
639 if ((ret = libusb_attach_kernel_driver(usb->devhdl,
640 uscpi->interface)) < 0)
641 sr_err("Failed to re-attach kernel driver: %s.",
642 libusb_error_name(ret));
644 uscpi->detached_kernel_driver = 0;
651 static void scpi_usbtmc_libusb_free(void *priv)
653 struct scpi_usbtmc_libusb *uscpi = priv;
654 sr_usb_dev_inst_free(uscpi->usb);
657 SR_PRIV const struct sr_scpi_dev_inst scpi_usbtmc_libusb_dev = {
660 .priv_size = sizeof(struct scpi_usbtmc_libusb),
661 .scan = scpi_usbtmc_libusb_scan,
662 .dev_inst_new = scpi_usbtmc_libusb_dev_inst_new,
663 .open = scpi_usbtmc_libusb_open,
664 .source_add = scpi_usbtmc_libusb_source_add,
665 .source_remove = scpi_usbtmc_libusb_source_remove,
666 .send = scpi_usbtmc_libusb_send,
667 .read_begin = scpi_usbtmc_libusb_read_begin,
668 .read_data = scpi_usbtmc_libusb_read_data,
669 .read_complete = scpi_usbtmc_libusb_read_complete,
670 .close = scpi_usbtmc_libusb_close,
671 .free = scpi_usbtmc_libusb_free,