libfprint/drivers/uru4000.c

   1 /*
   2  * Digital Persona U.are.U 4000/4000B driver for libfprint
   3  * Copyright (C) 2007 Daniel Drake <dsd@gentoo.org>
   4  *
   5  * This library is free software; you can redistribute it and/or
   6  * modify it under the terms of the GNU Lesser General Public
   7  * License as published by the Free Software Foundation; either
   8  * version 2.1 of the License, or (at your option) any later version.
   9  *
  10  * This library is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  * Lesser General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU Lesser General Public
  16  * License along with this library; if not, write to the Free Software
  17  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  18  */
  19
  20 #define FP_COMPONENT "uru4000"
  21
  22 #include <errno.h>
  23 #include <string.h>
  24 #include <unistd.h>
  25
  26 #include <usb.h>
  27
  28 #include <fp_internal.h>
  29
  30 #define EP_INTR                 (1 | USB_ENDPOINT_IN)
  31 #define EP_DATA                 (2 | USB_ENDPOINT_IN)
  32 #define USB_RQ                  0x04
  33 #define CTRL_IN                 (USB_TYPE_VENDOR | USB_ENDPOINT_IN)
  34 #define CTRL_OUT                (USB_TYPE_VENDOR | USB_ENDPOINT_OUT)
  35 #define CTRL_TIMEOUT    5000
  36 #define BULK_TIMEOUT    5000
  37 #define DATABLK1_RQLEN  0x10000
  38 #define DATABLK2_RQLEN  0xb340
  39 #define DATABLK2_EXPECT 0xb1c0
  40 #define CAPTURE_HDRLEN  64
  41 #define IRQ_LENGTH              64
  42
  43 enum {
  44         IRQDATA_SCANPWR_ON = 0x56aa,
  45         IRQDATA_FINGER_ON = 0x0101,
  46         IRQDATA_FINGER_OFF = 0x0200,
  47         IRQDATA_DEATH = 0x0800,
  48 };
  49
  50 enum {
  51         REG_HWSTAT = 0x07,
  52         REG_MODE = 0x4e,
  53         FIRMWARE_START = 0x100,
  54 };
  55
  56 enum {
  57         MODE_INIT = 0x00,
  58         MODE_AWAIT_FINGER_ON = 0x10,
  59         MODE_AWAIT_FINGER_OFF = 0x12,
  60         MODE_CAPTURE = 0x20,
  61         MODE_SHUT_UP = 0x30,
  62         MODE_READY = 0x80,
  63 };
  64
  65 enum {
  66         MS_KBD,
  67         MS_INTELLIMOUSE,
  68         MS_STANDALONE,
  69         MS_STANDALONE_V2,
  70         DP_URU4000,
  71         DP_URU4000B,
  72 };
  73
  74 static const struct uru4k_dev_profile {
  75         const char *name;
  76         uint16_t firmware_start;
  77         uint16_t fw_enc_offset;
  78 } uru4k_dev_info[] = {
  79         [MS_KBD] = {
  80                 .name = "Microsoft Keyboard with Fingerprint Reader",
  81                 .fw_enc_offset = 0x411,
  82         },
  83         [MS_INTELLIMOUSE] = {
  84                 .name = "Microsoft Wireless IntelliMouse with Fingerprint Reader",
  85                 .fw_enc_offset = 0x411,
  86         },
  87         [MS_STANDALONE] = {
  88                 .name = "Microsoft Fingerprint Reader",
  89                 .fw_enc_offset = 0x411,
  90         },
  91         [DP_URU4000] = {
  92                 .name = "Digital Persona U.are.U 4000",
  93                 .fw_enc_offset = 0x693,
  94         },
  95         [DP_URU4000B] = {
  96                 .name = "Digital Persona U.are.U 4000B",
  97                 .fw_enc_offset = 0x411,
  98         },
  99 };
 100
 101 struct uru4k_dev {
 102         const struct uru4k_dev_profile *profile;
 103         uint8_t interface;
 104 };
 105
 106 /*
 107  * HWSTAT
 108  *
 109  * This register has caused me a lot of headaches. It pretty much defines
 110  * code flow, and if you don't get it right, the pretty lights don't come on.
 111  * I think the situation is somewhat complicated by the fact that writing it
 112  * doesn't affect the read results in the way you'd expect -- but then again
 113  * it does have some obvious effects. Here's what we know
 114  *
 115  * BIT 7: LOW POWER MODE
 116  * When this bit is set, the device is partially turned off or something. Some
 117  * things, like firmware upload, need to be done in this state. But generally
 118  * we want to clear this bit during late initialization, which can sometimes
 119  * be tricky.
 120  *
 121  * BIT 2: SOMETHING WENT WRONG
 122  * Not sure about this, but see the init function, as when we detect it,
 123  * we reboot the device. Well, we mess with hwstat until this evil bit gets
 124  * cleared.
 125  *
 126  * BIT 1: IRQ PENDING
 127  * Just had a brainwave. This bit is set when the device is trying to deliver
 128  * and interrupt to the host. Maybe?
 129  */
 130
 131 static int get_hwstat(struct fp_img_dev *dev, unsigned char *data)
 132 {
 133         int r;
 134
 135         /* The windows driver uses a request of 0x0c here. We use 0x04 to be
 136          * consistent with every other command we know about. */
 137         r = usb_control_msg(dev->udev, CTRL_IN, USB_RQ, REG_HWSTAT, 0,
 138                 data, 1, CTRL_TIMEOUT);
 139         if (r < 0) {
 140                 fp_err("error %d", r);
 141                 return r;
 142         } else if (r < 1) {
 143                 fp_err("read too short (%d)", r);
 144                 return -EIO;
 145         }
 146
 147         fp_dbg("val=%02x", *data);
 148         return 0;
 149 }
 150
 151 static int set_hwstat(struct fp_img_dev *dev, unsigned char data)
 152 {
 153         int r;
 154         fp_dbg("val=%02x", data);
 155
 156         r = usb_control_msg(dev->udev, CTRL_OUT, USB_RQ, REG_HWSTAT, 0,
 157                 &data, 1, CTRL_TIMEOUT);
 158         if (r < 0) {
 159                 fp_err("error %d", r);
 160                 return r;
 161         } else if (r < 1) {
 162                 fp_err("read too short (%d)", r);
 163                 return -EIO;
 164         }
 165
 166         return 0;
 167 }
 168
 169 static int set_mode(struct fp_img_dev *dev, unsigned char mode)
 170 {
 171         int r;
 172
 173         fp_dbg("%02x", mode);
 174         r = usb_control_msg(dev->udev, CTRL_OUT, USB_RQ, REG_MODE, 0, &mode, 1,
 175                 CTRL_TIMEOUT);
 176         if (r < 0) {
 177                 fp_err("error %d", r);
 178                 return r;
 179         } else if (r < 1) {
 180                 fp_err("write too short (%d)", r);
 181                 return -EIO;
 182         }
 183
 184         return 0;
 185 }
 186
 187 static int get_irq(struct fp_img_dev *dev, unsigned char *buf, int timeout)
 188 {
 189         uint16_t type;
 190         int r;
 191         int infinite_timeout = 0;
 192
 193         if (timeout == 0) {
 194                 infinite_timeout = 1;
 195                 timeout = 1000;
 196         }
 197
 198         /* Darwin and Linux behave inconsistently with regard to infinite timeouts.
 199          * Linux accepts a timeout value of 0 as infinite timeout, whereas darwin
 200          * returns -ETIMEDOUT immediately when a 0 timeout is used. We use a
 201          * looping hack until libusb is fixed.
 202          * See http://thread.gmane.org/gmane.comp.lib.libusb.devel.general/1315 */
 203
 204 retry:
 205         r = usb_interrupt_read(dev->udev, EP_INTR, buf, IRQ_LENGTH, timeout);
 206         if (r == -ETIMEDOUT && infinite_timeout)
 207                 goto retry;
 208
 209         if (r < 0) {
 210                 if (r != -ETIMEDOUT)
 211                         fp_err("interrupt read failed, error %d", r);
 212                 return r;
 213         } else if (r < IRQ_LENGTH) {
 214                 fp_err("received %d byte IRQ!?", r);
 215                 return -EIO;
 216         }
 217
 218         type = GUINT16_FROM_BE(*((uint16_t *) buf));
 219         fp_dbg("irq type %04x", type);
 220
 221         /* The 0800 interrupt seems to indicate imminent failure (0 bytes transfer)
 222          * of the next scan. I think I've stopped it from coming up, not sure
 223          * though! */
 224         if (type == IRQDATA_DEATH)
 225                 fp_warn("oh no! got the interrupt OF DEATH! expect things to go bad");
 226
 227         return 0;
 228 }
 229
 230 enum get_irq_status {
 231         GET_IRQ_SUCCESS = 0,
 232         GET_IRQ_OVERFLOW = 1,
 233 };
 234
 235 static int get_irq_with_type(struct fp_img_dev *dev,
 236         uint16_t irqtype, int timeout)
 237 {
 238         uint16_t hdr;
 239         int discarded = 0;
 240         unsigned char irqbuf[IRQ_LENGTH];
 241
 242         fp_dbg("type=%04x", irqtype);
 243
 244         do {
 245                 int r = get_irq(dev, irqbuf, timeout);
 246                 if (r < 0)
 247                         return r;
 248
 249                 hdr = GUINT16_FROM_BE(*((uint16_t *) irqbuf));
 250                 if (hdr == irqtype)
 251                         break;
 252                 discarded++;
 253         } while (discarded < 3);
 254
 255         if (discarded > 0)
 256                 fp_dbg("discarded %d interrupts", discarded);
 257
 258         if (hdr == irqtype) {
 259                 return GET_IRQ_SUCCESS;
 260         } else {
 261                 /* I've seen several cases where we're waiting for the 56aa powerup
 262                  * interrupt, but instead we just get three 0200 interrupts and then
 263                  * nothing. My theory is that the device can only queue 3 interrupts,
 264                  * or something. So, if we discard 3, ask the caller to retry whatever
 265                  * it was doing. */
 266                 fp_dbg("possible IRQ overflow detected!");
 267                 return GET_IRQ_OVERFLOW;
 268         }
 269 }
 270
 271 static int await_finger_on(struct fp_img_dev *dev)
 272 {
 273         int r;
 274
 275 retry:
 276         r = set_mode(dev, MODE_AWAIT_FINGER_ON);
 277         if (r < 0)
 278                 return r;
 279
 280         r = get_irq_with_type(dev, IRQDATA_FINGER_ON, 0);
 281         if (r == GET_IRQ_OVERFLOW)
 282                 goto retry;
 283         else
 284                 return r;
 285 }
 286
 287 static int await_finger_off(struct fp_img_dev *dev)
 288 {
 289         int r;
 290
 291 retry:
 292         r = set_mode(dev, MODE_AWAIT_FINGER_OFF);
 293         if (r < 0)
 294                 return r;
 295
 296         r = get_irq_with_type(dev, IRQDATA_FINGER_OFF, 0);
 297         if (r == GET_IRQ_OVERFLOW)
 298                 goto retry;
 299         else
 300                 return r;
 301 }
 302
 303 static int capture(struct fp_img_dev *dev, gboolean unconditional,
 304         struct fp_img **ret)
 305 {
 306         int r;
 307         struct fp_img *img;
 308         size_t image_size = DATABLK1_RQLEN + DATABLK2_EXPECT - CAPTURE_HDRLEN;
 309         int hdr_skip = CAPTURE_HDRLEN;
 310
 311         r = set_mode(dev, MODE_CAPTURE);
 312         if (r < 0)
 313                 return r;
 314
 315         /* The image is split up into 2 blocks over 2 USB transactions, which are
 316          * joined contiguously. The image is prepended by a 64 byte header which
 317          * we completely ignore.
 318          *
 319          * We mimic the windows driver behaviour by requesting 0xb340 bytes in the
 320          * 2nd request, but we only expect 0xb1c0 in response. However, our buffers
 321          * must be set up on the offchance that we receive as much data as we
 322          * asked for. */
 323
 324         img = fpi_img_new(DATABLK1_RQLEN + DATABLK2_RQLEN);
 325
 326         r = usb_bulk_read(dev->udev, EP_DATA, img->data, DATABLK1_RQLEN,
 327                 BULK_TIMEOUT);
 328         if (r < 0) {
 329                 fp_err("part 1 capture failed, error %d", r);
 330                 goto err;
 331         } else if (r < DATABLK1_RQLEN) {
 332                 fp_err("part 1 capture too short (%d)", r);
 333                 r = -EIO;
 334                 goto err;
 335         }
 336
 337         r = usb_bulk_read(dev->udev, EP_DATA, img->data + DATABLK1_RQLEN,
 338                 DATABLK2_RQLEN, BULK_TIMEOUT);
 339         if (r < 0) {
 340                 fp_err("part 2 capture failed, error %d", r);
 341                 goto err;
 342         } else if (r != DATABLK2_EXPECT) {
 343                 if (r == DATABLK2_EXPECT - CAPTURE_HDRLEN) {
 344                         /* this is rather odd, but it happens sometimes with my MS
 345                          * keyboard */
 346                         fp_dbg("got image with no header!");
 347                         hdr_skip = 0;
 348                 } else {
 349                         fp_err("unexpected part 2 capture size (%d)", r);
 350                         r = -EIO;
 351                         goto err;
 352                 }
 353         }
 354
 355         /* remove header and shrink allocation */
 356         g_memmove(img->data, img->data + hdr_skip, image_size);
 357         img = fpi_img_resize(img, image_size);
 358         img->flags = FP_IMG_V_FLIPPED | FP_IMG_H_FLIPPED | FP_IMG_COLORS_INVERTED;
 359
 360         *ret = img;
 361         return 0;
 362 err:
 363         g_free(img);
 364         return r;
 365 }
 366
 367 static int fix_firmware(struct fp_img_dev *dev)
 368 {
 369         struct uru4k_dev *urudev = dev->priv;
 370         uint32_t enc_addr = FIRMWARE_START + urudev->profile->fw_enc_offset;
 371         unsigned char val, new;
 372         int r;
 373
 374         r = usb_control_msg(dev->udev, 0xc0, 0x0c, enc_addr, 0, &val, 1,
 375                 CTRL_TIMEOUT);
 376         if (r < 0)
 377                 return r;
 378
 379         fp_dbg("encryption byte at %x reads %02x", enc_addr, val);
 380         if (val != 0x07 && val != 0x17)
 381                 fp_dbg("strange encryption byte value, please report this");
 382
 383         new = val & 0xef;
 384         //new = 0x17;
 385         if (new == val)
 386                 return 0;
 387
 388         r = usb_control_msg(dev->udev, 0x40, 0x04, enc_addr, 0, &new, 1,
 389                 CTRL_TIMEOUT);
 390         if (r < 0)
 391                 return r;
 392
 393         fp_dbg("fixed encryption byte to %02x", new);
 394         return 1;
 395 }
 396
 397 static int do_init(struct fp_img_dev *dev)
 398 {
 399         unsigned char status;
 400         unsigned char tmp;
 401         int timeouts = 0;
 402         int i;
 403         int r;
 404
 405 retry:
 406         r = get_hwstat(dev, &status);
 407         if (r < 0)
 408                 return r;
 409
 410         /* After closing an app and setting hwstat to 0x80, my ms keyboard
 411          * gets in a confused state and returns hwstat 0x85. On next app run,
 412          * we don't get the 56aa interrupt. This is the best way I've found to
 413          * fix it: mess around with hwstat until it starts returning more
 414          * recognisable values. This doesn't happen on my other devices:
 415          * uru4000, uru4000b, ms fp rdr v2
 416          * The windows driver copes with this OK, but then again it uploads
 417          * firmware right after reading the 0x85 hwstat, allowing some time
 418          * to pass before it attempts to tweak hwstat again... */
 419         if ((status & 0x84) == 0x84) {
 420                 fp_dbg("rebooting device power");
 421                 r = set_hwstat(dev, status & 0xf);
 422                 if (r < 0)
 423                         return r;
 424
 425                 for (i = 0; i < 100; i++) {
 426                         r = get_hwstat(dev, &status);
 427                         if (r < 0)
 428                                 return r;
 429                         if (status & 0x1)
 430                                 break;
 431                         usleep(10000);
 432                 }
 433                 if ((status & 0x1) == 0) {
 434                         fp_err("could not reboot device power");
 435                         return -EIO;
 436                 }
 437         }
 438
 439         if ((status & 0x80) == 0) {
 440                 status |= 0x80;
 441                 r = set_hwstat(dev, status);
 442                 if (r < 0)
 443                         return r;
 444         }
 445
 446
 447         r = fix_firmware(dev);
 448         if (r < 0)
 449                 return r;
 450
 451         /* Power up device and wait for interrupt notification */
 452         /* The combination of both modifying firmware *and* doing C-R auth on
 453          * my ms fp v2 device causes us not to get to get the 56aa interrupt and
 454          * for the hwstat write not to take effect. We loop a few times,
 455          * authenticating each time, until the device wakes up. */
 456         for (i = 0; i < 100; i++) { /* max 1 sec */
 457                 r = set_hwstat(dev, status & 0xf);
 458                 if (r < 0)
 459                         return r;
 460
 461                 r = get_hwstat(dev, &tmp);
 462                 if (r < 0)
 463                         return r;
 464
 465                 if ((tmp & 0x80) == 0)
 466                         break;
 467
 468                 usleep(10000);
 469
 470                 /* FIXME do C-R auth for v2 devices */
 471         }
 472
 473         if (tmp & 0x80) {
 474                 fp_err("could not power up device");
 475                 return -EIO;
 476         }
 477
 478         r = get_irq_with_type(dev, IRQDATA_SCANPWR_ON, 300);
 479         if (r == GET_IRQ_OVERFLOW) {
 480                 goto retry;
 481         } else if (r == -ETIMEDOUT) {
 482                 timeouts++;
 483                 if (timeouts <= 3) {
 484                         fp_dbg("scan power up timeout, retrying...");
 485                         goto retry;
 486                 } else {
 487                         fp_err("could not power up scanner after 3 attempts");
 488                 }
 489         }
 490         return r;
 491 }
 492
 493 static int dev_init(struct fp_img_dev *dev, unsigned long driver_data)
 494 {
 495         struct usb_config_descriptor *config;
 496         struct usb_interface *iface = NULL;
 497         struct usb_interface_descriptor *iface_desc;
 498         struct usb_endpoint_descriptor *ep;
 499         struct uru4k_dev *urudev;
 500         int i;
 501         int r;
 502
 503         /* Find fingerprint interface */
 504         config = usb_device(dev->udev)->config;
 505         for (i = 0; i < config->bNumInterfaces; i++) {
 506                 struct usb_interface *cur_iface = &config->interface[i];
 507
 508                 if (cur_iface->num_altsetting < 1)
 509                         continue;
 510
 511                 iface_desc = &cur_iface->altsetting[0];
 512                 if (iface_desc->bInterfaceClass == 255
 513                                 && iface_desc->bInterfaceSubClass == 255
 514                                 && iface_desc->bInterfaceProtocol == 255) {
 515                         iface = cur_iface;
 516                         break;
 517                 }
 518         }
 519
 520         if (iface == NULL) {
 521                 fp_err("could not find interface");
 522                 return -ENODEV;
 523         }
 524
 525         /* Find/check endpoints */
 526
 527         if (iface_desc->bNumEndpoints != 2) {
 528                 fp_err("found %d endpoints!?", iface_desc->bNumEndpoints);
 529                 return -ENODEV;
 530         }
 531
 532         ep = &iface_desc->endpoint[0];
 533         if (ep->bEndpointAddress != EP_INTR
 534                         || (ep->bmAttributes & USB_ENDPOINT_TYPE_MASK) !=
 535                                 USB_ENDPOINT_TYPE_INTERRUPT) {
 536                 fp_err("unrecognised interrupt endpoint");
 537                 return -ENODEV;
 538         }
 539
 540         ep = &iface_desc->endpoint[1];
 541         if (ep->bEndpointAddress != EP_DATA
 542                         || (ep->bmAttributes & USB_ENDPOINT_TYPE_MASK) !=
 543                                 USB_ENDPOINT_TYPE_BULK) {
 544                 fp_err("unrecognised bulk endpoint");
 545                 return -ENODEV;
 546         }
 547
 548         /* Device looks like a supported reader */
 549
 550         r = usb_claim_interface(dev->udev, iface_desc->bInterfaceNumber);
 551         if (r < 0) {
 552                 fp_err("interface claim failed");
 553                 return r;
 554         }
 555
 556         urudev = g_malloc0(sizeof(*urudev));
 557         urudev->profile = &uru4k_dev_info[driver_data];
 558         urudev->interface = iface_desc->bInterfaceNumber;
 559         dev->priv = urudev;
 560
 561         r = do_init(dev);
 562         if (r < 0)
 563                 goto err;
 564
 565         return 0;
 566 err:
 567         usb_release_interface(dev->udev, iface_desc->bInterfaceNumber);
 568         g_free(urudev);
 569         return r;
 570 }
 571
 572 static void dev_exit(struct fp_img_dev *dev)
 573 {
 574         struct uru4k_dev *urudev = dev->priv;
 575
 576         set_mode(dev, MODE_INIT);
 577         set_hwstat(dev, 0x80);
 578         usb_release_interface(dev->udev, urudev->interface);
 579         g_free(urudev);
 580 }
 581
 582 static const struct usb_id id_table[] = {
 583         /* ms kbd with fp rdr */
 584         { .vendor = 0x045e, .product = 0x00bb, .driver_data = MS_KBD },
 585
 586         /* ms intellimouse with fp rdr */
 587         { .vendor = 0x045e, .product = 0x00bc, .driver_data = MS_INTELLIMOUSE },
 588
 589         /* ms fp rdr (standalone) */
 590         { .vendor = 0x045e, .product = 0x00bd, .driver_data = MS_STANDALONE },
 591
 592         /* dp uru4000 (standalone) */
 593         { .vendor = 0x05ba, .product = 0x0007, .driver_data = DP_URU4000 },
 594
 595         /* dp uru4000b (standalone) */
 596         { .vendor = 0x05ba, .product = 0x000a, .driver_data = DP_URU4000B },
 597
 598         /* terminating entry */
 599         { 0, 0, 0, },
 600 };
 601
 602 struct fp_img_driver uru4000_driver = {
 603         .driver = {
 604                 .id = 2,
 605                 .name = FP_COMPONENT,
 606                 .full_name = "Digital Persona U.are.U 4000/4000B",
 607                 .id_table = id_table,
 608         },
 609         .flags = FP_IMGDRV_SUPPORTS_UNCONDITIONAL_CAPTURE,
 610         .img_height = 289,
 611         .img_width = 384,
 612
 613         .init = dev_init,
 614         .exit = dev_exit,
 615         .await_finger_on = await_finger_on,
 616         .await_finger_off = await_finger_off,
 617         .capture = capture,
 618 };
 619