src/serial_hid.c

   1 /*
   2  * This file is part of the libsigrok project.
   3  *
   4  * Copyright (C) 2017-2019 Gerhard Sittig <gerhard.sittig@gmx.net>
   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 "config.h"
  21 #include <glib.h>
  22 #ifdef HAVE_LIBHIDAPI
  23 #include <hidapi.h>
  24 #endif
  25 #include <libsigrok/libsigrok.h>
  26 #include "libsigrok-internal.h"
  27 #include "serial_hid.h"
  28 #include <stdlib.h>
  29 #include <string.h>
  30 #ifdef G_OS_WIN32
  31 #include <windows.h> /* for HANDLE */
  32 #endif
  33
  34 /** @cond PRIVATE */
  35 #define LOG_PREFIX "serial-hid"
  36 /** @endcond */
  37
  38 #ifdef HAVE_SERIAL_COMM
  39
  40 /**
  41  * @file
  42  *
  43  * Serial port handling, HIDAPI library specific support code.
  44  */
  45
  46 /**
  47  * @defgroup grp_serial_hid Serial port handling, HID group
  48  *
  49  * Make serial-over-HID communication appear like a regular serial port.
  50  *
  51  * @{
  52  */
  53
  54 #ifdef HAVE_LIBHIDAPI
  55 /* {{{ helper routines */
  56
  57 /* Strip off parity bits for "odd" data bit counts like in 7e1 frames. */
  58 static void ser_hid_mask_databits(struct sr_serial_dev_inst *serial,
  59         uint8_t *data, size_t len)
  60 {
  61         uint32_t mask32;
  62         uint8_t mask;
  63         size_t idx;
  64
  65         if ((serial->comm_params.data_bits % 8) == 0)
  66                 return;
  67
  68         mask32 = (1UL << serial->comm_params.data_bits) - 1;
  69         mask = mask32 & 0xff;
  70         for (idx = 0; idx < len; idx++)
  71                 data[idx] &= mask;
  72 }
  73
  74 /* }}} */
  75 /* {{{ open/close/list/find HIDAPI connection, exchange HID requests and data */
  76
  77 /*
  78  * Convert a HIDAPI path (which depends on the target platform, and may
  79  * depend on one of several available API variants on that platform) to
  80  * something that is usable as a "port name" in conn= specs.
  81  *
  82  * Since conn= is passed with -d where multiple options (among them conn=)
  83  * are separated by colons, port names themselves cannot contain colons.
  84  *
  85  * Just replace colons by a period in the simple case (Linux platform,
  86  * hidapi-libusb implementation, bus/address/interface). Prefix the
  87  * HIDAPI path in the complex cases (Linux hidapi-hidraw, Windows, Mac).
  88  * Paths with colons outside of libusb based implementations are unhandled
  89  * here, but were not yet seen on any sigrok supported platform either.
  90  * So just reject them.
  91  */
  92 static char *get_hidapi_path_copy(const char *path)
  93 {
  94         static const char *accept = "0123456789abcdefABCDEF:";
  95         static const char *keep = "0123456789abcdefABCDEF";
  96
  97         int has_colon;
  98         int is_hex_colon;
  99         char *name;
 100
 101         has_colon = strchr(path, ':') != NULL;
 102         is_hex_colon = strspn(path, accept) == strlen(path);
 103         if (has_colon && !is_hex_colon) {
 104                 sr_err("Unsupported HIDAPI path format: %s", path);
 105                 return NULL;
 106         }
 107         if (is_hex_colon) {
 108                 name = g_strdup_printf("%s%s", SER_HID_USB_PREFIX, path);
 109                 g_strcanon(name + strlen(SER_HID_USB_PREFIX), keep, '.');
 110         } else {
 111                 name = g_strdup_printf("%s%s", SER_HID_RAW_PREFIX, path);
 112         }
 113
 114         return name;
 115 }
 116
 117 /*
 118  * Undo the port name construction that was done during scan. Extract
 119  * the HIDAPI path from a conn= input spec (the part after the hid/
 120  * prefix and chip type).
 121  *
 122  * Strip off the "raw" prefix, or undo colon substitution. See @ref
 123  * get_hidapi_path_copy() for details.
 124  */
 125 static const char *extract_hidapi_path(char *buffer)
 126 {
 127         static const char *keep = "0123456789abcdefABCDEF:";
 128
 129         const char *p;
 130
 131         p = buffer;
 132         if (!p || !*p)
 133                 return NULL;
 134
 135         if (strncmp(p, SER_HID_RAW_PREFIX, strlen(SER_HID_RAW_PREFIX)) == 0) {
 136                 p += strlen(SER_HID_RAW_PREFIX);
 137                 return p;
 138         }
 139         if (strncmp(p, SER_HID_USB_PREFIX, strlen(SER_HID_USB_PREFIX)) == 0) {
 140                 p += strlen(SER_HID_USB_PREFIX);
 141                 g_strcanon(buffer, keep, ':');
 142                 return p;
 143         }
 144
 145         return NULL;
 146 }
 147
 148 /*
 149  * The HIDAPI specific list() callback, invoked by common serial.c code.
 150  * Enumerate all devices (no VID:PID is involved).
 151  * Invoke an 'append' callback with "path" and "name".
 152  */
 153 static GSList *ser_hid_hidapi_list(GSList *list, sr_ser_list_append_t append)
 154 {
 155         struct hid_device_info *devs, *curdev;
 156         const char *chipname;
 157         char *path, *name;
 158         wchar_t *manuf, *prod, *serno;
 159         uint16_t vid, pid;
 160         GString *desc;
 161
 162         devs = hid_enumerate(0x0000, 0x0000);
 163         for (curdev = devs; curdev; curdev = curdev->next) {
 164                 /*
 165                  * Determine the chip name from VID:PID (if it's one of
 166                  * the supported types with an ID known to us).
 167                  */
 168                 vid = curdev->vendor_id;
 169                 pid = curdev->product_id;
 170                 sr_dbg("DIAG: hidapi enum, vid:pid %04x:%04x, path %s\n",
 171                         curdev->vendor_id, curdev->product_id, curdev->path);
 172                 chipname = ser_hid_chip_find_name_vid_pid(vid, pid);
 173                 if (!chipname)
 174                         chipname = "<chip>";
 175
 176                 /*
 177                  * Prefix port names such that open() calls with this
 178                  * conn= spec will end up here and contain all details
 179                  * that are essential for processing.
 180                  */
 181                 path = get_hidapi_path_copy(curdev->path);
 182                 if (!path)
 183                         continue;
 184                 name = g_strdup_printf("%s/%s/%s",
 185                         SER_HID_CONN_PREFIX, chipname, path);
 186                 g_free(path);
 187
 188                 /*
 189                  * Print whatever information was available. Construct
 190                  * the description text from pieces. Absence of fields
 191                  * is not fatal, we have seen perfectly usable cables
 192                  * that only had a VID and PID (permissions were not an
 193                  * issue).
 194                  */
 195                 manuf = curdev->manufacturer_string;
 196                 prod = curdev->product_string;
 197                 serno = curdev->serial_number;
 198                 vid = curdev->vendor_id;
 199                 pid = curdev->product_id;
 200                 desc = g_string_sized_new(128);
 201                 g_string_append_printf(desc, "HID");
 202                 if (manuf)
 203                         g_string_append_printf(desc, " %ls", manuf);
 204                 if (prod)
 205                         g_string_append_printf(desc, " %ls", prod);
 206                 if (serno)
 207                         g_string_append_printf(desc, " %ls", serno);
 208                 if (vid && pid)
 209                         g_string_append_printf(desc, " %04hx:%04hx", vid, pid);
 210                 list = append(list, name, desc->str);
 211                 g_string_free(desc, TRUE);
 212                 g_free(name);
 213         }
 214         hid_free_enumeration(devs);
 215
 216         return list;
 217 }
 218
 219 /*
 220  * The HIDAPI specific find_usb() callback, invoked by common serial.c code.
 221  * Enumerate devices for the specified VID:PID pair.
 222  * Invoke an "append" callback with 'path' for the device.
 223  */
 224 static GSList *ser_hid_hidapi_find_usb(GSList *list, sr_ser_find_append_t append,
 225                 uint16_t vendor_id, uint16_t product_id)
 226 {
 227         struct hid_device_info *devs, *curdev;
 228         const char *name;
 229
 230         devs = hid_enumerate(vendor_id, product_id);
 231         for (curdev = devs; curdev; curdev = curdev->next) {
 232                 name = curdev->path;
 233                 list = append(list, name);
 234         }
 235         hid_free_enumeration(devs);
 236
 237         return list;
 238 }
 239
 240 /* Get the serial number of a device specified by path. */
 241 static int ser_hid_hidapi_get_serno(const char *path, char *buf, size_t blen)
 242 {
 243         char *usbpath;
 244         const char *hidpath;
 245         hid_device *dev;
 246         wchar_t *serno_wch;
 247         int rc;
 248
 249         if (!path || !*path)
 250                 return SR_ERR_ARG;
 251         usbpath = g_strdup(path);
 252         hidpath = extract_hidapi_path(usbpath);
 253         dev = hidpath ? hid_open_path(hidpath) : NULL;
 254         g_free(usbpath);
 255         if (!dev)
 256                 return SR_ERR_IO;
 257
 258         serno_wch = g_malloc0(blen * sizeof(*serno_wch));
 259         rc = hid_get_serial_number_string(dev, serno_wch, blen - 1);
 260         hid_close(dev);
 261         if (rc != 0) {
 262                 g_free(serno_wch);
 263                 return SR_ERR_IO;
 264         }
 265
 266         snprintf(buf, blen, "%ls", serno_wch);
 267         g_free(serno_wch);
 268
 269         return SR_OK;
 270 }
 271
 272 /* Get the VID and PID of a device specified by path. */
 273 static int ser_hid_hidapi_get_vid_pid(const char *path,
 274         uint16_t *vid, uint16_t *pid)
 275 {
 276 #if 0
 277         /*
 278          * Bummer! It would have been most reliable to just open the
 279          * device by the specified path, and grab its VID:PID. But
 280          * there is no way to get these parameters, neither in the
 281          * HIDAPI itself, nor when cheating and reaching behind the API
 282          * and accessing the libusb handle in dirty ways. :(
 283          */
 284         hid_device *dev;
 285
 286         if (!path || !*path)
 287                 return SR_ERR_ARG;
 288         dev = hid_open_path(path);
 289         if (!dev)
 290                 return SR_ERR_IO;
 291         if (vid)
 292                 *vid = dev->vendor_id;
 293         if (pid)
 294                 *pid = dev->product_id;
 295         hid_close(dev);
 296
 297         return SR_OK;
 298 #else
 299         /*
 300          * The fallback approach. Enumerate all devices, compare the
 301          * enumerated USB path, and grab the VID:PID. Unfortunately the
 302          * caller can provide path specs that differ from enumerated
 303          * paths yet mean the same (address the same device). This needs
 304          * more attention. Though the specific format of the path and
 305          * its meaning are said to be OS specific, which is why we may
 306          * not assume anything about it...
 307          */
 308         char *usbpath;
 309         const char *hidpath;
 310         struct hid_device_info *devs, *dev;
 311         int found;
 312
 313         usbpath = g_strdup(path);
 314         hidpath = extract_hidapi_path(usbpath);
 315         if (!hidpath) {
 316                 g_free(usbpath);
 317                 return SR_ERR_NA;
 318         }
 319
 320         devs = hid_enumerate(0x0000, 0x0000);
 321         found = 0;
 322         for (dev = devs; dev; dev = dev->next) {
 323                 if (strcmp(dev->path, hidpath) != 0)
 324                         continue;
 325                 if (vid)
 326                         *vid = dev->vendor_id;
 327                 if (pid)
 328                         *pid = dev->product_id;
 329                 found = 1;
 330                 break;
 331         }
 332         hid_free_enumeration(devs);
 333         g_free(usbpath);
 334
 335         return found ? SR_OK : SR_ERR_NA;
 336 #endif
 337 }
 338
 339 static int ser_hid_hidapi_open_dev(struct sr_serial_dev_inst *serial)
 340 {
 341         hid_device *hid_dev;
 342
 343         if (!serial->usb_path || !*serial->usb_path)
 344                 return SR_ERR_ARG;
 345
 346         /*
 347          * A path is available, assume that either a GUI or a
 348          * user has copied what a previous listing has provided.
 349          * Or a scan determined a matching device's USB path.
 350          */
 351         if (!serial->hid_path)
 352                 serial->hid_path = extract_hidapi_path(serial->usb_path);
 353         hid_dev = hid_open_path(serial->hid_path);
 354         sr_dbg("DBG: %s(), hid_open_path(\"%s\") => %p", __func__,
 355                         serial->hid_path, hid_dev);
 356         if (!hid_dev) {
 357                 serial->hid_path = NULL;
 358                 return SR_ERR_IO;
 359         }
 360
 361         serial->hid_dev = hid_dev;
 362         hid_set_nonblocking(hid_dev, 1);
 363
 364         return SR_OK;
 365 }
 366
 367 static void ser_hid_hidapi_close_dev(struct sr_serial_dev_inst *serial)
 368 {
 369         if (serial->hid_dev) {
 370                 hid_close(serial->hid_dev);
 371                 serial->hid_dev = NULL;
 372                 serial->hid_path = NULL;
 373         }
 374         g_slist_free_full(serial->hid_source_args, g_free);
 375         serial->hid_source_args = NULL;
 376 }
 377
 378 struct hidapi_source_args_t {
 379         /* Application callback. */
 380         sr_receive_data_callback cb;
 381         void *cb_data;
 382         /* The serial device, to store RX data. */
 383         struct sr_serial_dev_inst *serial;
 384 };
 385
 386 /*
 387  * Gets periodically invoked by the glib main loop. "Drives" (checks)
 388  * progress of USB communication, and invokes the application's callback
 389  * which processes RX data (when some has become available), as well as
 390  * handles application level timeouts.
 391  */
 392 static int hidapi_source_cb(int fd, int revents, void *cb_data)
 393 {
 394         struct hidapi_source_args_t *args;
 395         uint8_t rx_buf[SER_HID_CHUNK_SIZE];
 396         int rc;
 397
 398         sr_dbg("DBG: %s() fd %d, evt 0x%x, data %p.", __func__, fd, revents, cb_data);
 399         args = cb_data;
 400
 401         /*
 402          * Drain receive data which the chip might have pending. This is
 403          * "a copy" of the "background part" of ser_hid_read(), without
 404          * the timeout support code, and not knowing how much data the
 405          * application is expecting.
 406          */
 407         do {
 408                 rc = args->serial->hid_chip_funcs->read_bytes(args->serial,
 409                                 rx_buf, sizeof(rx_buf), 0);
 410                 if (rc > 0) {
 411                         sr_dbg("DBG: %s() queueing %d bytes.", __func__, rc);
 412                         ser_hid_mask_databits(args->serial, rx_buf, rc);
 413                         sr_ser_queue_rx_data(args->serial, rx_buf, rc);
 414                 }
 415         } while (rc > 0);
 416
 417         /*
 418          * When RX data became available (now or earlier), pass this
 419          * condition to the application callback. Always periodically
 420          * run the application callback, since it handles timeouts and
 421          * might carry out other tasks as well like signalling progress.
 422          */
 423         if (sr_ser_has_queued_data(args->serial))
 424                 revents |= G_IO_IN;
 425         rc = args->cb(fd, revents, args->cb_data);
 426         sr_dbg("DBG: %s() rc %d.", __func__, rc);
 427
 428         return rc;
 429 }
 430
 431 #define WITH_MAXIMUM_TIMEOUT_VALUE      10
 432 static int ser_hid_hidapi_setup_source_add(struct sr_session *session,
 433         struct sr_serial_dev_inst *serial, int events, int timeout,
 434         sr_receive_data_callback cb, void *cb_data)
 435 {
 436         struct hidapi_source_args_t *args;
 437         int rc;
 438
 439         sr_dbg("DBG: %s() evt 0x%x, to %d.", __func__, events, timeout);
 440         (void)events;
 441
 442         /* Optionally enforce a minimum poll period. */
 443         if (WITH_MAXIMUM_TIMEOUT_VALUE && timeout > WITH_MAXIMUM_TIMEOUT_VALUE)
 444                 timeout = WITH_MAXIMUM_TIMEOUT_VALUE;
 445
 446         /* Allocate status container for background data reception. */
 447         args = g_malloc0(sizeof(*args));
 448         args->cb = cb;
 449         args->cb_data = cb_data;
 450         args->serial = serial;
 451
 452         /*
 453          * Have a periodic timer installed. Register the allocated block
 454          * with the serial device, since the GSource's finalizer won't
 455          * free the memory, and we haven't bothered to create a custom
 456          * HIDAPI specific GSource.
 457          */
 458         rc = sr_session_source_add(session, -1, events, timeout,
 459                         hidapi_source_cb, args);
 460         sr_dbg("DBG: %s() added, rc %d.", __func__, rc);
 461         if (rc != SR_OK) {
 462                 g_free(args);
 463                 return rc;
 464         }
 465         serial->hid_source_args = g_slist_append(serial->hid_source_args, args);
 466
 467         return SR_OK;
 468 }
 469
 470 static int ser_hid_hidapi_setup_source_remove(struct sr_session *session,
 471         struct sr_serial_dev_inst *serial)
 472 {
 473         (void)serial;
 474
 475         sr_dbg("DBG: %s().", __func__);
 476         (void)sr_session_source_remove(session, -1);
 477         /*
 478          * Release callback args here already? Can there be more than
 479          * one source registered at any time, given that we pass fd -1
 480          * which is used as the key for the session?
 481          */
 482
 483         return SR_OK;
 484 }
 485
 486 SR_PRIV int ser_hid_hidapi_get_report(struct sr_serial_dev_inst *serial,
 487         uint8_t *data, size_t len)
 488 {
 489         int rc;
 490
 491         rc = hid_get_feature_report(serial->hid_dev, data, len);
 492         if (rc < 0)
 493                 return SR_ERR_IO;
 494
 495         return rc;
 496 }
 497
 498 SR_PRIV int ser_hid_hidapi_set_report(struct sr_serial_dev_inst *serial,
 499         const uint8_t *data, size_t len)
 500 {
 501         int rc;
 502         const wchar_t *err_text;
 503
 504         rc = hid_send_feature_report(serial->hid_dev, data, len);
 505         if (rc < 0) {
 506                 err_text = hid_error(serial->hid_dev);
 507                 sr_dbg("%s() hidapi error: %ls", __func__, err_text);
 508                 return SR_ERR_IO;
 509         }
 510
 511         return rc;
 512 }
 513
 514 SR_PRIV int ser_hid_hidapi_get_data(struct sr_serial_dev_inst *serial,
 515         uint8_t ep, uint8_t *data, size_t len, int timeout)
 516 {
 517         int rc;
 518
 519         (void)ep;
 520
 521         if (timeout)
 522                 rc = hid_read_timeout(serial->hid_dev, data, len, timeout);
 523         else
 524                 rc = hid_read(serial->hid_dev, data, len);
 525         if (rc < 0)
 526                 return SR_ERR_IO;
 527         if (rc == 0)
 528                 return 0;
 529
 530         return rc;
 531 }
 532
 533 SR_PRIV int ser_hid_hidapi_set_data(struct sr_serial_dev_inst *serial,
 534         uint8_t ep, const uint8_t *data, size_t len, int timeout)
 535 {
 536         int rc;
 537
 538         (void)ep;
 539         (void)timeout;
 540
 541         rc = hid_write(serial->hid_dev, data, len);
 542         if (rc < 0)
 543                 return SR_ERR_IO;
 544
 545         return rc;
 546 }
 547
 548 /* }}} */
 549 /* {{{ support for serial-over-HID chips */
 550
 551 static struct ser_hid_chip_functions **chips[SER_HID_CHIP_LAST] = {
 552         [SER_HID_CHIP_UNKNOWN] = NULL,
 553         [SER_HID_CHIP_BTC_BU86X] = &ser_hid_chip_funcs_bu86x,
 554         [SER_HID_CHIP_SIL_CP2110] = &ser_hid_chip_funcs_cp2110,
 555         [SER_HID_CHIP_WCH_CH9325] = &ser_hid_chip_funcs_ch9325,
 556 };
 557
 558 static struct ser_hid_chip_functions *get_hid_chip_funcs(enum ser_hid_chip_t chip)
 559 {
 560         struct ser_hid_chip_functions *funcs;
 561
 562         if (chip >= ARRAY_SIZE(chips))
 563                 return NULL;
 564         if (!chips[chip])
 565                 return NULL;
 566         funcs = *chips[chip];
 567         if (!funcs)
 568                 return NULL;
 569
 570         return funcs;
 571 }
 572
 573 static int ser_hid_setup_funcs(struct sr_serial_dev_inst *serial)
 574 {
 575
 576         if (!serial)
 577                 return -1;
 578
 579         if (serial->hid_chip && !serial->hid_chip_funcs) {
 580                 serial->hid_chip_funcs = get_hid_chip_funcs(serial->hid_chip);
 581                 if (!serial->hid_chip_funcs)
 582                         return -1;
 583         }
 584
 585         return 0;
 586 }
 587
 588 /*
 589  * Takes a pointer to the chip spec with potentially trailing data,
 590  * returns the chip index and advances the spec pointer upon match,
 591  * returns SER_HID_CHIP_UNKNOWN upon mismatch.
 592  */
 593 static enum ser_hid_chip_t ser_hid_chip_find_enum(char **spec_p)
 594 {
 595         gchar *spec;
 596         enum ser_hid_chip_t idx;
 597         struct ser_hid_chip_functions *desc;
 598
 599         if (!spec_p || !*spec_p)
 600                 return SER_HID_CHIP_UNKNOWN;
 601         spec = *spec_p;
 602         if (!*spec)
 603                 return SER_HID_CHIP_UNKNOWN;
 604         for (idx = 0; idx < SER_HID_CHIP_LAST; idx++) {
 605                 desc = get_hid_chip_funcs(idx);
 606                 if (!desc)
 607                         continue;
 608                 if (!desc->chipname)
 609                         continue;
 610                 if (!g_str_has_prefix(spec, desc->chipname))
 611                         continue;
 612                 spec += strlen(desc->chipname);
 613                 *spec_p = spec;
 614                 return idx;
 615         }
 616
 617         return SER_HID_CHIP_UNKNOWN;
 618 }
 619
 620 /* See if we can find a chip name for a VID:PID spec. */
 621 SR_PRIV const char *ser_hid_chip_find_name_vid_pid(uint16_t vid, uint16_t pid)
 622 {
 623         size_t chip_idx;
 624         struct ser_hid_chip_functions *desc;
 625         const struct vid_pid_item *vid_pids;
 626
 627         for (chip_idx = 0; chip_idx < SER_HID_CHIP_LAST; chip_idx++) {
 628                 desc = get_hid_chip_funcs(chip_idx);
 629                 if (!desc)
 630                         continue;
 631                 if (!desc->chipname)
 632                         continue;
 633                 vid_pids = desc->vid_pid_items;
 634                 if (!vid_pids)
 635                         continue;
 636                 while (vid_pids->vid) {
 637                         if (vid_pids->vid == vid && vid_pids->pid == pid) {
 638                                 return desc->chipname;
 639                         }
 640                         vid_pids++;
 641                 }
 642         }
 643
 644         return NULL;
 645 }
 646
 647 static const char *ser_hid_chip_get_text(enum ser_hid_chip_t idx)
 648 {
 649         struct ser_hid_chip_functions *desc;
 650
 651         desc = get_hid_chip_funcs(idx);
 652         if (!desc)
 653                 return NULL;
 654
 655         return desc->chipdesc;
 656 }
 657
 658 /**
 659  * See if a text string is a valid USB path for a HID device.
 660  * @param[in] serial The serial port that is about to get opened.
 661  * @param[in] path The (assumed) USB path specification.
 662  * @return SR_OK upon success, SR_ERR* upon failure.
 663  */
 664 static int try_open_path(struct sr_serial_dev_inst *serial, const char *path)
 665 {
 666         int rc;
 667
 668         serial->usb_path = g_strdup(path);
 669         rc = ser_hid_hidapi_open_dev(serial);
 670         ser_hid_hidapi_close_dev(serial);
 671         g_free(serial->usb_path);
 672         serial->usb_path = NULL;
 673
 674         return rc;
 675 }
 676
 677 /**
 678  * Parse conn= specs for serial over HID communication.
 679  *
 680  * @param[in] serial The serial port that is about to get opened.
 681  * @param[in] spec The caller provided conn= specification.
 682  * @param[out] chip_ref Pointer to a chip type (enum).
 683  * @param[out] path_ref Pointer to a USB path (text string).
 684  * @param[out] serno_ref Pointer to a serial number (text string).
 685  *
 686  * @return 0 upon success, non-zero upon failure. Fills the *_ref output
 687  * values.
 688  *
 689  * @internal
 690  *
 691  * Summary of parsing rules as they are implemented:
 692  * - Insist on the "hid" prefix. Accept "hid" alone without any other
 693  *   additional field.
 694  * - The first field that follows can be a chip spec, yet is optional.
 695  * - Any other field is assumed to be either a USB path or a serial
 696  *   number. There is no point in specifying both of these, as either
 697  *   of them uniquely identifies a device.
 698  *
 699  * Supported formats resulting from these rules:
 700  *   hid[/<chip>]
 701  *   hid[/<chip>]/usb=<bus>.<dev>[.<if>]
 702  *   hid[/<chip>]/raw=<path>    (may contain slashes!)
 703  *   hid[/<chip>]/sn=serno
 704  *
 705  * This routine just parses the conn= spec, which either was provided by
 706  * a user, or may reflect (cite) an item of a previously gathered listing
 707  * (clipboard provided by CLI clients, or selected from a GUI form).
 708  * Another routine will fill in the blanks, and do the cable selection
 709  * when a filter was specified.
 710  *
 711  * Users will want to use short forms when they need to come up with the
 712  * specs by themselves. The "verbose" or seemingly redundant forms (chip
 713  * _and_ path/serno spec) are useful when the cable uses non-standard or
 714  * not-yet-supported VID:PID items when automatic chip detection fails.
 715  */
 716 static int ser_hid_parse_conn_spec(
 717         struct sr_serial_dev_inst *serial, const char *spec,
 718         enum ser_hid_chip_t *chip_ref, char **path_ref, char **serno_ref)
 719 {
 720         const char *p;
 721         enum ser_hid_chip_t chip;
 722         char *path, *serno;
 723         int rc;
 724
 725         if (chip_ref)
 726                 *chip_ref = SER_HID_CHIP_UNKNOWN;
 727         if (path_ref)
 728                 *path_ref = NULL;
 729         if (serno_ref)
 730                 *serno_ref = NULL;
 731         chip = SER_HID_CHIP_UNKNOWN;
 732         path = serno = NULL;
 733
 734         if (!serial || !spec || !*spec)
 735                 return SR_ERR_ARG;
 736         sr_dbg("DBG: %s(), input spec: %s", __func__, spec);
 737         p = spec;
 738
 739         /* The "hid" prefix is mandatory. */
 740         if (!g_str_has_prefix(p, SER_HID_CONN_PREFIX)) {
 741                 sr_dbg("DBG: %s(), not a HID port", __func__);
 742                 return SR_ERR_ARG;
 743         }
 744         p += strlen(SER_HID_CONN_PREFIX);
 745
 746         /*
 747          * Check for prefixed fields, assume chip type spec otherwise.
 748          * Paths and serial numbers "are greedy" (span to the end of
 749          * the input spec). Chip types are optional, and cannot repeat
 750          * multiple times.
 751          */
 752         while (*p) {
 753                 if (*p == '/')
 754                         p++;
 755                 if (!*p)
 756                         break;
 757                 if (g_str_has_prefix(p, SER_HID_USB_PREFIX)) {
 758                         rc = try_open_path(serial, p);
 759                         sr_dbg("DBG: %s(), open usb path %s => rc %d", __func__, p, rc);
 760                         if (rc != SR_OK)
 761                                 return rc;
 762                         path = g_strdup(p);
 763                         p += strlen(p);
 764                 } else if (g_str_has_prefix(p, SER_HID_RAW_PREFIX)) {
 765                         rc = try_open_path(serial, p);
 766                         sr_dbg("DBG: %s(), open raw path %s => rc %d", __func__, p, rc);
 767                         if (rc != SR_OK)
 768                                 return rc;
 769                         path = g_strdup(p);
 770                         p += strlen(p);
 771                 } else if (g_str_has_prefix(p, SER_HID_SNR_PREFIX)) {
 772                         p += strlen(SER_HID_SNR_PREFIX);
 773                         sr_dbg("DBG: %s(), snr %s", __func__, p);
 774                         serno = g_strdup(p);
 775                         p += strlen(p);
 776                 } else if (!chip) {
 777                         char *copy, *endptr;
 778                         const char *name;
 779                         copy = g_strdup(p);
 780                         endptr = copy;
 781                         chip = ser_hid_chip_find_enum(&endptr);
 782                         sr_dbg("DBG: %s(), chip search, %s => %u", __func__, p, chip);
 783                         if (!chip) {
 784                                 g_free(copy);
 785                                 return SR_ERR_ARG;
 786                         }
 787                         p += endptr - copy;
 788                         g_free(copy);
 789                         name = ser_hid_chip_get_text(chip);
 790                         sr_dbg("DBG: %s(), chip %s", __func__, name);
 791                 } else {
 792                         sr_err("unsupported conn= spec %s, error at %s", spec, p);
 793                         return SR_ERR_ARG;
 794                 }
 795                 if (*p == '/')
 796                         p++;
 797                 if (path || serno)
 798                         break;
 799         }
 800
 801         sr_dbg("DBG: %s() done, chip %d, path %s, serno %s", __func__, chip, path, serno);
 802         if (chip_ref)
 803                 *chip_ref = chip;
 804         if (path_ref && path)
 805                 *path_ref = path;
 806         if (serno_ref && serno)
 807                 *serno_ref = serno;
 808
 809         return SR_OK;
 810 }
 811
 812 /* Get and compare serial number. Boolean return value. */
 813 static int check_serno(const char *path, const char *serno_want)
 814 {
 815         char *usb_path;
 816         const char *hid_path;
 817         char serno_got[128];
 818         int rc;
 819
 820         sr_dbg("DBG: %s(\"%s\", \"%s\")", __func__, path, serno_want);
 821
 822         usb_path = g_strdup(path);
 823         hid_path = extract_hidapi_path(usb_path);
 824         rc = ser_hid_hidapi_get_serno(hid_path, serno_got, sizeof(serno_got));
 825         sr_dbg("DBG: %s(), usb %s, hidapi %s => rc %d", __func__, usb_path, hid_path, rc);
 826         g_free(usb_path);
 827         if (rc) {
 828                 sr_dbg("DBG: %s(), could not get serial number", __func__);
 829                 return 0;
 830         }
 831         sr_dbg("DBG: %s(), got serno \"%s\"", __func__, serno_got);
 832
 833         rc = strcmp(serno_got, serno_want) == 0;
 834         sr_dbg("DBG: %s(), return %d", __func__, rc);
 835
 836         return rc;
 837 }
 838
 839 static GSList *append_find(GSList *devs, const char *path)
 840 {
 841         char *copy;
 842
 843         if (!path || !*path)
 844                 return devs;
 845
 846         copy = g_strdup(path);
 847         devs = g_slist_append(devs, copy);
 848
 849         return devs;
 850 }
 851
 852 static GSList *list_paths_for_vids_pids(const struct vid_pid_item *vid_pids)
 853 {
 854         GSList *list;
 855         size_t idx;
 856         uint16_t vid, pid;
 857
 858         list = NULL;
 859         for (idx = 0; /* EMPTY */; idx++) {
 860                 if (!vid_pids) {
 861                         vid = pid = 0;
 862                 } else if (!vid_pids[idx].vid) {
 863                         break;
 864                 } else {
 865                         vid = vid_pids[idx].vid;
 866                         pid = vid_pids[idx].pid;
 867                 }
 868                 sr_dbg("DBG: %s(), searching VID:PID %04hx:%04hx",
 869                                 __func__, vid, pid);
 870                 list = ser_hid_hidapi_find_usb(list, append_find, vid, pid);
 871                 if (!vid_pids)
 872                         break;
 873         }
 874
 875         return list;
 876 }
 877
 878 /**
 879  * Search for a matching USB device for HID communication.
 880  *
 881  * @param[inout] chip The HID chip type (enum).
 882  * @param[inout] usbpath The USB path for the device (string).
 883  * @param[in] serno The serial number to search for.
 884  *
 885  * @retval SR_OK upon success
 886  * @retval SR_ERR_* upon failure.
 887  *
 888  * @internal
 889  *
 890  * This routine fills in blanks which the conn= spec parser left open.
 891  * When not specified yet, the HID chip type gets determined. When a
 892  * serial number was specified, then search the corresponding device.
 893  * Upon completion, the chip type and USB path for the device shall be
 894  * known, as these are essential for subsequent operation.
 895  */
 896 static int ser_hid_chip_search(enum ser_hid_chip_t *chip_ref,
 897         char **path_ref, const char *serno)
 898 {
 899         enum ser_hid_chip_t chip;
 900         char *path;
 901         int have_chip, have_path, have_serno;
 902         struct ser_hid_chip_functions *chip_funcs;
 903         int rc;
 904         int serno_matched;
 905         uint16_t vid, pid;
 906         const char *name;
 907         const struct vid_pid_item *vid_pids;
 908         GSList *list, *matched, *matched2, *tmplist;
 909
 910         if (!chip_ref)
 911                 return SR_ERR_ARG;
 912         chip = *chip_ref;
 913         if (!path_ref)
 914                 return SR_ERR_ARG;
 915         path = *path_ref;
 916         sr_dbg("DBG: %s() enter, chip %d, path %s, serno %s", __func__,
 917                         chip, path, serno ? serno : "<none>");
 918
 919         /*
 920          * Simplify the more complex conditions somewhat by assigning
 921          * to local variables. Handle the easiest conditions first.
 922          * - Either path or serial number can be specified, but not both
 923          *   at the same time.
 924          * - When a USB path is given, immediately see which HID chip
 925          *   the device has, without the need for enumeration.
 926          * - When a serial number is given, enumerate the devices and
 927          *   search for that number. Either enumerate all devices of the
 928          *   specified HID chip type (try the VID:PID pairs that we are
 929          *   aware of), or try all HID devices for unknown chip types.
 930          *   Not finding the serial number is fatal.
 931          * - When no path was found yet, enumerate the devices and pick
 932          *   one of them. Try known VID:PID pairs for a HID chip, or all
 933          *   devices for unknown chips. Make sure to pick a device of a
 934          *   supported chip type if the chip was not specified.
 935          * - Determine the chip type if not yet known. There should be
 936          *   a USB path by now, determined in one of the above blocks.
 937          */
 938         have_chip = (chip != SER_HID_CHIP_UNKNOWN) ? 1 : 0;
 939         have_path = (path && *path) ? 1 : 0;
 940         have_serno = (serno && *serno) ? 1 : 0;
 941         sr_dbg("DBG: %s(), have chip %d, path %d, serno %d", __func__,
 942                         have_chip, have_path, have_serno);
 943         if (have_path && have_serno) {
 944                 sr_err("Unsupported combination of USB path and serno");
 945                 return SR_ERR_ARG;
 946         }
 947         chip_funcs = have_chip ? get_hid_chip_funcs(chip) : NULL;
 948         if (have_chip && !chip_funcs)
 949                 return SR_ERR_NA;
 950         if (have_chip && !chip_funcs->vid_pid_items)
 951                 return SR_ERR_NA;
 952         if (have_path && !have_chip) {
 953                 sr_dbg("DBG: %s(), searching chip for path %s", __func__, path);
 954                 vid = pid = 0;
 955                 rc = ser_hid_hidapi_get_vid_pid(path, &vid, &pid);
 956                 sr_dbg("DBG: %s(), rc %d, VID:PID %04x:%04x", __func__, rc, vid, pid);
 957                 if (rc != SR_OK)
 958                         return rc;
 959                 name = ser_hid_chip_find_name_vid_pid(vid, pid);
 960                 sr_dbg("DBG: %s(), name %s", __func__, name);
 961                 if (!name || !*name)
 962                         return SR_ERR_NA;
 963                 chip = ser_hid_chip_find_enum((char **)&name);
 964                 sr_dbg("DBG: %s(), chip %d", __func__, chip);
 965                 if (chip == SER_HID_CHIP_UNKNOWN)
 966                         return SR_ERR_NA;
 967                 have_chip = 1;
 968         }
 969         if (have_serno) {
 970                 sr_dbg("DBG: %s(), searching path for serno %s", __func__, serno);
 971                 vid_pids = have_chip ? chip_funcs->vid_pid_items : NULL;
 972                 list = list_paths_for_vids_pids(vid_pids);
 973                 sr_dbg("DBG: %s(), vid/pid list for chip type %p", __func__, list);
 974                 if (!list)
 975                         return SR_ERR_NA;
 976                 matched = NULL;
 977                 for (tmplist = list; tmplist; tmplist = tmplist->next) {
 978                         path = get_hidapi_path_copy(tmplist->data);
 979                         sr_dbg("DBG: %s(), checking %s", __func__, path);
 980                         serno_matched = check_serno(path, serno);
 981                         g_free(path);
 982                         if (!serno_matched)
 983                                 continue;
 984                         matched = tmplist;
 985                         break;
 986                 }
 987                 if (!matched)
 988                         return SR_ERR_NA;
 989                 path = g_strdup(matched->data);
 990                 sr_dbg("DBG: %s(), match, path %s", __func__, path);
 991                 have_path = 1;
 992                 g_slist_free_full(list, g_free);
 993         }
 994         if (!have_path) {
 995                 sr_dbg("DBG: %s(), searching path, chip %d", __func__, chip);
 996                 vid_pids = have_chip ? chip_funcs->vid_pid_items : NULL;
 997                 list = list_paths_for_vids_pids(vid_pids);
 998                 if (!list)
 999                         return SR_ERR_NA;
1000                 for (tmplist = list; tmplist; tmplist = tmplist->next) {
1001                         path = tmplist->data;
1002                         sr_dbg("DBG: %s(), path %s", __func__, path);
1003                 }
1004                 matched = matched2 = NULL;
1005                 if (have_chip) {
1006                         /* List already only contains specified chip. */
1007                         matched = list;
1008                         path = matched->data;
1009                         sr_dbg("DBG: %s(), match 1 %s", __func__, path);
1010                         matched2 = list->next;
1011                         if (matched2) {
1012                                 path = matched2->data;
1013                                 sr_dbg("DBG: %s(), match 2 %s", __func__, path);
1014                         }
1015                 }
1016                 /* Works for lists with one or multiple chips. Saves indentation. */
1017                 for (tmplist = list; tmplist; tmplist = tmplist->next) {
1018                         if (have_chip)
1019                                 break;
1020                         path = tmplist->data;
1021                         rc = ser_hid_hidapi_get_vid_pid(path, &vid, &pid);
1022                         if (rc || !ser_hid_chip_find_name_vid_pid(vid, pid))
1023                                 continue;
1024                         if (!matched) {
1025                                 matched = tmplist;
1026                                 sr_dbg("DBG: %s(), match 1 %s", __func__, path);
1027                                 continue;
1028                         }
1029                         if (!matched2) {
1030                                 matched2 = tmplist;
1031                                 sr_dbg("DBG: %s(), match 2 %s", __func__, path);
1032                                 break;
1033                         }
1034                 }
1035                 if (!matched) {
1036                         g_slist_free_full(list, g_free);
1037                         return SR_ERR_NA;
1038                 }
1039                 /*
1040                  * TODO Optionally fail harder, expect users to provide
1041                  * unambiguous cable specs.
1042                  */
1043                 if (matched2)
1044                         sr_info("More than one cable matches, random pick.");
1045                 path = get_hidapi_path_copy(matched->data);
1046                 sr_dbg("DBG: %s(), match, path %s", __func__, path);
1047                 have_path = 1;
1048                 g_slist_free_full(list, g_free);
1049         }
1050         if (have_path && !have_chip) {
1051                 sr_dbg("DBG: %s(), searching chip for path %s", __func__, path);
1052                 vid = pid = 0;
1053                 rc = ser_hid_hidapi_get_vid_pid(path, &vid, &pid);
1054                 sr_dbg("DBG: %s(), rc %d, VID:PID %04x:%04x", __func__, rc, vid, pid);
1055                 if (rc != SR_OK)
1056                         return rc;
1057                 name = ser_hid_chip_find_name_vid_pid(vid, pid);
1058                 sr_dbg("DBG: %s(), name %s", __func__, name);
1059                 if (!name || !*name)
1060                         return SR_ERR_NA;
1061                 chip = ser_hid_chip_find_enum((char **)&name);
1062                 sr_dbg("DBG: %s(), chip %d", __func__, chip);
1063                 if (chip == SER_HID_CHIP_UNKNOWN)
1064                         return SR_ERR_NA;
1065                 have_chip = 1;
1066         }
1067
1068         sr_dbg("DBG: %s() leave, chip %d, path %s", __func__, chip, path);
1069         if (chip_ref)
1070                 *chip_ref = chip;
1071         if (path_ref)
1072                 *path_ref = path;
1073
1074         return SR_OK;
1075 }
1076
1077 /* }}} */
1078 /* {{{ transport methods called by the common serial.c code */
1079
1080 /* See if a serial port's name refers to an HID type. */
1081 SR_PRIV int ser_name_is_hid(struct sr_serial_dev_inst *serial)
1082 {
1083         size_t off;
1084         char sep;
1085
1086         if (!serial)
1087                 return 0;
1088         if (!serial->port || !*serial->port)
1089                 return 0;
1090
1091         /* Accept either "hid" alone, or "hid/" as a prefix. */
1092         if (!g_str_has_prefix(serial->port, SER_HID_CONN_PREFIX))
1093                 return 0;
1094         off = strlen(SER_HID_CONN_PREFIX);
1095         sep = serial->port[off];
1096         if (sep != '\0' && sep != '/')
1097                 return 0;
1098
1099         return 1;
1100 }
1101
1102 static int ser_hid_open(struct sr_serial_dev_inst *serial, int flags)
1103 {
1104         enum ser_hid_chip_t chip;
1105         char *usbpath, *serno;
1106         int rc;
1107
1108         (void)flags;
1109
1110         if (ser_hid_setup_funcs(serial) != 0) {
1111                 sr_err("Cannot determine HID communication library.");
1112                 return SR_ERR_NA;
1113         }
1114
1115         rc = ser_hid_parse_conn_spec(serial, serial->port,
1116                         &chip, &usbpath, &serno);
1117         if (rc != SR_OK)
1118                 return SR_ERR_ARG;
1119
1120         /*
1121          * When a serial number was specified, or when the chip type or
1122          * the USB path were not specified, do a search to determine the
1123          * device's USB path.
1124          */
1125         if (!chip || !usbpath || serno) {
1126                 sr_dbg("DBG: %s(), searching ...", __func__);
1127                 rc = ser_hid_chip_search(&chip, &usbpath, serno);
1128                 if (rc != 0)
1129                         return SR_ERR_NA;
1130         }
1131
1132         /*
1133          * Open the HID device. Only store chip type and device handle
1134          * when open completes successfully.
1135          */
1136         serial->hid_chip = chip;
1137         if (ser_hid_setup_funcs(serial) != 0) {
1138                 sr_err("Cannot determine HID chip specific routines.");
1139                 return SR_ERR_NA;
1140         }
1141         if (usbpath && *usbpath)
1142                 serial->usb_path = usbpath;
1143         if (serno && *serno)
1144                 serial->usb_serno = serno;
1145
1146         rc = ser_hid_hidapi_open_dev(serial);
1147         if (rc) {
1148                 sr_err("Failed to open HID device.");
1149                 serial->hid_chip = 0;
1150                 g_free(serial->usb_path);
1151                 serial->usb_path = NULL;
1152                 g_free(serial->usb_serno);
1153                 serial->usb_serno = NULL;
1154                 return SR_ERR_IO;
1155         }
1156         sr_dbg("DBG: %s() done, OK", __func__);
1157
1158         if (!serial->rcv_buffer)
1159                 serial->rcv_buffer = g_string_sized_new(SER_HID_CHUNK_SIZE);
1160
1161         return SR_OK;
1162 }
1163
1164 static int ser_hid_close(struct sr_serial_dev_inst *serial)
1165 {
1166         sr_dbg("DBG: %s()", __func__);
1167         ser_hid_hidapi_close_dev(serial);
1168
1169         return SR_OK;
1170 }
1171
1172 static int ser_hid_set_params(struct sr_serial_dev_inst *serial,
1173         int baudrate, int bits, int parity, int stopbits,
1174         int flowcontrol, int rts, int dtr)
1175 {
1176         int rc;
1177
1178         sr_dbg("DBG: %s() enter", __func__);
1179         if (ser_hid_setup_funcs(serial) != 0)
1180                 return SR_ERR_NA;
1181         sr_dbg("DBG: %s() chip funcs set", __func__);
1182         if (!serial->hid_chip_funcs || !serial->hid_chip_funcs->set_params)
1183                 return SR_ERR_NA;
1184         sr_dbg("DBG: %s() set params avail", __func__);
1185         rc = serial->hid_chip_funcs->set_params(serial,
1186                 baudrate, bits, parity, stopbits,
1187                 flowcontrol, rts, dtr);
1188         sr_dbg("DBG: %s() set params rc %d", __func__, rc);
1189
1190         return rc;
1191 }
1192
1193 static int ser_hid_setup_source_add(struct sr_session *session,
1194         struct sr_serial_dev_inst *serial, int events, int timeout,
1195         sr_receive_data_callback cb, void *cb_data)
1196 {
1197         return ser_hid_hidapi_setup_source_add(session, serial,
1198                 events, timeout, cb, cb_data);
1199 }
1200
1201 static int ser_hid_setup_source_remove(struct sr_session *session,
1202         struct sr_serial_dev_inst *serial)
1203 {
1204         return ser_hid_hidapi_setup_source_remove(session, serial);
1205 }
1206
1207 static GSList *ser_hid_list(GSList *list, sr_ser_list_append_t append)
1208 {
1209         return ser_hid_hidapi_list(list, append);
1210 }
1211
1212 static GSList *ser_hid_find_usb(GSList *list, sr_ser_find_append_t append,
1213         uint16_t vendor_id, uint16_t product_id)
1214 {
1215         return ser_hid_hidapi_find_usb(list, append, vendor_id, product_id);
1216 }
1217
1218 static int ser_hid_flush(struct sr_serial_dev_inst *serial)
1219 {
1220         if (!serial->hid_chip_funcs || !serial->hid_chip_funcs->flush)
1221                 return SR_ERR_NA;
1222
1223         return serial->hid_chip_funcs->flush(serial);
1224 }
1225
1226 static int ser_hid_drain(struct sr_serial_dev_inst *serial)
1227 {
1228         if (!serial->hid_chip_funcs || !serial->hid_chip_funcs->drain)
1229                 return SR_ERR_NA;
1230
1231         return serial->hid_chip_funcs->drain(serial);
1232 }
1233
1234 static int ser_hid_write(struct sr_serial_dev_inst *serial,
1235         const void *buf, size_t count,
1236         int nonblocking, unsigned int timeout_ms)
1237 {
1238         int total, max_chunk, chunk_len;
1239         int rc;
1240
1241         if (!serial->hid_chip_funcs || !serial->hid_chip_funcs->write_bytes)
1242                 return SR_ERR_NA;
1243         if (!serial->hid_chip_funcs->max_bytes_per_request)
1244                 return SR_ERR_NA;
1245
1246         sr_dbg("DBG: %s() shall send %zu bytes TX data.", __func__, count);
1247         total = 0;
1248         max_chunk = serial->hid_chip_funcs->max_bytes_per_request;
1249         while (count > 0) {
1250                 chunk_len = count;
1251                 if (max_chunk && chunk_len > max_chunk)
1252                         chunk_len = max_chunk;
1253                 rc = serial->hid_chip_funcs->write_bytes(serial, buf, chunk_len);
1254                 if (rc < 0) {
1255                         sr_err("Error sending transmit data to HID device.");
1256                         return total;
1257                 }
1258                 if (rc != chunk_len) {
1259                         sr_warn("Short transmission to HID device (%d/%d bytes)?",
1260                                         rc, chunk_len);
1261                         return total;
1262                 }
1263                 buf += chunk_len;
1264                 count -= chunk_len;
1265                 total += chunk_len;
1266                 /* TODO
1267                  * Need we wait here? For data to drain through the slow
1268                  * UART. Not all UART-over-HID chips will have FIFOs.
1269                  */
1270                 if (!nonblocking) {
1271                         (void)timeout_ms;
1272                         /* TODO */
1273                 }
1274         }
1275
1276         return total;
1277 }
1278
1279 static int ser_hid_read(struct sr_serial_dev_inst *serial,
1280         void *buf, size_t count,
1281         int nonblocking, unsigned int timeout_ms)
1282 {
1283         gint64 deadline_us, now_us;
1284         uint8_t buffer[SER_HID_CHUNK_SIZE];
1285         int rc;
1286         unsigned int got;
1287
1288         sr_dbg("DBG: %s() count %zd, block %d, to %u", __func__,
1289                         count, !nonblocking, timeout_ms);
1290
1291         if (!serial->hid_chip_funcs || !serial->hid_chip_funcs->read_bytes)
1292                 return SR_ERR_NA;
1293         if (!serial->hid_chip_funcs->max_bytes_per_request)
1294                 return SR_ERR_NA;
1295
1296         /*
1297          * Immediately satisfy the caller's request from the RX buffer
1298          * if the requested amount of data is available already.
1299          */
1300         if (sr_ser_has_queued_data(serial) >= count) {
1301                 rc = sr_ser_unqueue_rx_data(serial, buf, count);
1302                 return rc;
1303         }
1304
1305         /*
1306          * When a timeout was specified, then determine the deadline
1307          * where to stop reception.
1308          */
1309         deadline_us = 0;
1310         now_us = 0;             /* Silence a (false) compiler warning. */
1311         if (timeout_ms) {
1312                 now_us = g_get_monotonic_time();
1313                 deadline_us = now_us + timeout_ms * 1000;
1314         }
1315
1316         /*
1317          * Keep receiving from the port until the caller's requested
1318          * amount of data has become available, or the timeout has
1319          * expired. In the absence of a timeout, stop reading when an
1320          * attempt no longer yields receive data.
1321          *
1322          * This implementation assumes that applications will call the
1323          * read routine often enough, or that reception continues in
1324          * background, such that data is not lost and hardware and
1325          * software buffers won't overrun.
1326          */
1327         while (TRUE) {
1328                 /*
1329                  * Determine the timeout (in milliseconds) for this
1330                  * iteration. The 'now_us' timestamp was initially
1331                  * determined above, and gets updated at the bottom of
1332                  * the loop.
1333                  */
1334                 if (deadline_us) {
1335                         timeout_ms = (deadline_us - now_us) / 1000;
1336                         if (!timeout_ms)
1337                                 timeout_ms = 1;
1338                 } else if (nonblocking) {
1339                         timeout_ms = 10;
1340                 } else {
1341                         timeout_ms = 0;
1342                 }
1343
1344                 /*
1345                  * Check the HID transport for the availability of more
1346                  * receive data.
1347                  */
1348                 rc = serial->hid_chip_funcs->read_bytes(serial,
1349                                 buffer, sizeof(buffer), timeout_ms);
1350                 if (rc < 0) {
1351                         sr_dbg("DBG: %s() read error %d.", __func__, rc);
1352                         return SR_ERR;
1353                 }
1354                 if (rc) {
1355                         sr_dbg("DBG: %s() queueing %d bytes.", __func__, rc);
1356                         ser_hid_mask_databits(serial, buffer, rc);
1357                         sr_ser_queue_rx_data(serial, buffer, rc);
1358                 }
1359                 got = sr_ser_has_queued_data(serial);
1360
1361                 /*
1362                  * Stop reading when the requested amount is available,
1363                  * or when the timeout has expired.
1364                  *
1365                  * TODO Consider whether grabbing all RX data is more
1366                  * desirable. Implementing this approach requires a cheap
1367                  * check for the availability of more data on the USB level.
1368                  */
1369                 if (got >= count)
1370                         break;
1371                 if (nonblocking && !rc)
1372                         break;
1373                 if (deadline_us) {
1374                         now_us = g_get_monotonic_time();
1375                         if (now_us >= deadline_us) {
1376                                 sr_dbg("DBG: %s() read loop timeout.", __func__);
1377                                 break;
1378                         }
1379                 }
1380         }
1381
1382         /*
1383          * Satisfy the caller's demand for receive data from previously
1384          * queued incoming data.
1385          */
1386         if (got > count)
1387                 got = count;
1388         sr_dbg("DBG: %s() passing %d bytes.", __func__, got);
1389         rc = sr_ser_unqueue_rx_data(serial, buf, count);
1390
1391         return rc;
1392 }
1393
1394 static struct ser_lib_functions serlib_hid = {
1395         .open = ser_hid_open,
1396         .close = ser_hid_close,
1397         .flush = ser_hid_flush,
1398         .drain = ser_hid_drain,
1399         .write = ser_hid_write,
1400         .read = ser_hid_read,
1401         .set_params = ser_hid_set_params,
1402         .setup_source_add = ser_hid_setup_source_add,
1403         .setup_source_remove = ser_hid_setup_source_remove,
1404         .list = ser_hid_list,
1405         .find_usb = ser_hid_find_usb,
1406         .get_frame_format = NULL,
1407 };
1408 SR_PRIV struct ser_lib_functions *ser_lib_funcs_hid = &serlib_hid;
1409
1410 /* }}} */
1411 #else
1412
1413 SR_PRIV int ser_name_is_hid(struct sr_serial_dev_inst *serial)
1414 {
1415         (void)serial;
1416
1417         return 0;
1418 }
1419
1420 SR_PRIV struct ser_lib_functions *ser_lib_funcs_hid = NULL;
1421
1422 #endif
1423 #endif
1424 /** @} */