1 /* sane - Scanner Access Now Easy. 2 Copyright (C) 2001, 2002 Henning Meier-Geinitz 3 Copyright (C) 2003, 2005 Rene Rebe (sanei_read_int,sanei_set_timeout) 4 Copyright (C) 2008 m. allan noah (sanei_usb_clear_halt) 5 Copyright (C) 2011 Reinhold Kainhofer (sanei_usb_set_endpoint) 6 This file is part of the SANE package. 7 8 SANE is free software; you can redistribute it and/or modify it 9 under the terms of the GNU General Public License as published by 10 the Free Software Foundation; either version 2 of the License, or 11 (at your option) any later version. 12 13 SANE is distributed in the hope that it will be useful, but WITHOUT 14 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY 15 or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public 16 License for more details. 17 18 You should have received a copy of the GNU General Public License 19 along with sane; see the file COPYING. 20 If not, see <https://www.gnu.org/licenses/>. 21 22 As a special exception, the authors of SANE give permission for 23 additional uses of the libraries contained in this release of SANE. 24 25 The exception is that, if you link a SANE library with other files 26 to produce an executable, this does not by itself cause the 27 resulting executable to be covered by the GNU General Public 28 License. Your use of that executable is in no way restricted on 29 account of linking the SANE library code into it. 30 31 This exception does not, however, invalidate any other reasons why 32 the executable file might be covered by the GNU General Public 33 License. 34 35 If you submit changes to SANE to the maintainers to be included in 36 a subsequent release, you agree by submitting the changes that 37 those changes may be distributed with this exception intact. 38 39 If you write modifications of your own for SANE, it is your choice 40 whether to permit this exception to apply to your modifications. 41 If you do not wish that, delete this exception notice. 42 */ 43 44 /** @file sanei_usb.h 45 * This file provides a generic USB interface. 46 * 47 * Currently, two access methods to USB devices are provided: 48 * - Access to device 49 * files as used by the Linux kernel USB scanner driver is supported. FreeBSD 50 * and OpenBSD with their uscanner drivers also work this way. However, 51 * detection and control messages aren't supported on these platforms. 52 * - Access using libusb (where available). 53 * 54 * A general remark: Do not mix sanei_usb functions with "normal" file-related 55 * libc functions like open() or close. The device numbers used in sanei_usb 56 * are not file descriptors. 57 * 58 * @sa sanei_lm983x.h, sanei_pa4s2.h, sanei_pio.h, sanei_scsi.h, and <a 59 * href="http://www.sane-project.org/man/sane-usb.5.html">man sane-usb(5)</a> 60 * for user-oriented documentation 61 */ 62 63 #ifndef sanei_usb_h 64 #define sanei_usb_h 65 66 #include "../include/sane/config.h" 67 #include "../include/sane/sane.h" 68 69 #include <stdlib.h> /* for size_t */ 70 71 #ifdef __cplusplus 72 extern "C" { 73 #endif 74 75 /* USB spec defines */ 76 #ifndef USB_CLASS_PER_INTERFACE 77 /* Also defined in libusb */ 78 /** @name Device and/or interface class codes */ 79 /* @{ */ 80 #define USB_CLASS_PER_INTERFACE 0x00 81 #define USB_CLASS_AUDIO 0x01 82 #define USB_CLASS_COMM 0x02 83 #define USB_CLASS_HID 0x03 84 #define USB_CLASS_PRINTER 0x07 85 #define USB_CLASS_MASS_STORAGE 0x08 86 #define USB_CLASS_HUB 0x09 87 #define USB_CLASS_DATA 0x0a 88 #define USB_CLASS_VENDOR_SPEC 0xff 89 /* @} */ 90 91 /** @name USB descriptor types */ 92 /* @{ */ 93 #define USB_DT_DEVICE 0x01 94 #define USB_DT_CONFIG 0x02 95 #define USB_DT_STRING 0x03 96 #define USB_DT_INTERFACE 0x04 97 #define USB_DT_ENDPOINT 0x05 98 #define USB_DT_HID 0x21 99 #define USB_DT_REPORT 0x22 100 #define USB_DT_PHYSICAL 0x23 101 #define USB_DT_HUB 0x29 102 /* @} */ 103 104 /** @name Descriptor sizes per descriptor type */ 105 /* @{ */ 106 #define USB_DT_DEVICE_SIZE 18 107 #define USB_DT_CONFIG_SIZE 9 108 #define USB_DT_INTERFACE_SIZE 9 109 #define USB_DT_ENDPOINT_SIZE 7 110 #define USB_DT_ENDPOINT_AUDIO_SIZE 9 111 #define USB_DT_HUB_NONVAR_SIZE 7 112 /* @} */ 113 114 /** @name Endpoint descriptors */ 115 /* @{ */ 116 #define USB_ENDPOINT_ADDRESS_MASK 0x0f 117 #define USB_ENDPOINT_DIR_MASK 0x80 118 #define USB_ENDPOINT_TYPE_MASK 0x03 119 #define USB_ENDPOINT_TYPE_CONTROL 0 120 #define USB_ENDPOINT_TYPE_ISOCHRONOUS 1 121 #define USB_ENDPOINT_TYPE_BULK 2 122 #define USB_ENDPOINT_TYPE_INTERRUPT 3 123 /* @} */ 124 125 /** @name Standard requests */ 126 /* @{ */ 127 #define USB_REQ_GET_STATUS 0x00 128 #define USB_REQ_CLEAR_FEATURE 0x01 129 #define USB_REQ_SET_FEATURE 0x03 130 #define USB_REQ_SET_ADDRESS 0x05 131 #define USB_REQ_GET_DESCRIPTOR 0x06 132 #define USB_REQ_SET_DESCRIPTOR 0x07 133 #define USB_REQ_GET_CONFIGURATION 0x08 134 #define USB_REQ_SET_CONFIGURATION 0x09 135 #define USB_REQ_GET_INTERFACE 0x0A 136 #define USB_REQ_SET_INTERFACE 0x0B 137 #define USB_REQ_SYNCH_FRAME 0x0C 138 /* @} */ 139 140 /** @name USB types */ 141 /* @{ */ 142 #define USB_TYPE_STANDARD (0x00 << 5) 143 #define USB_TYPE_CLASS (0x01 << 5) 144 #define USB_TYPE_VENDOR (0x02 << 5) 145 #define USB_TYPE_RESERVED (0x03 << 5) 146 /* @} */ 147 148 /** @name USB recipients */ 149 /* @{ */ 150 #define USB_RECIP_DEVICE 0x00 151 #define USB_RECIP_INTERFACE 0x01 152 #define USB_RECIP_ENDPOINT 0x02 153 #define USB_RECIP_OTHER 0x03 154 /* @} */ 155 156 #endif /* not USB_CLASS_PER_INTERFACE */ 157 158 /* Not defined in libsub */ 159 /** @name USB Masks */ 160 /* @{ */ 161 #define USB_TYPE_MASK (0x03 << 5) 162 #define USB_RECIP_MASK 0x1f 163 /* @} */ 164 165 /** @name USB directions */ 166 /* @{ */ 167 #define USB_DIR_OUT 0x00 168 #define USB_DIR_IN 0x80 169 /* @} */ 170 171 /** */ 172 struct sanei_usb_dev_descriptor 173 { 174 SANE_Byte desc_type; 175 unsigned int bcd_usb; 176 unsigned int bcd_dev; 177 SANE_Byte dev_class; 178 SANE_Byte dev_sub_class; 179 SANE_Byte dev_protocol; 180 SANE_Byte max_packet_size; 181 }; 182 183 /** Initialize sanei_usb for replay testing. 184 185 Initializes sanei_usb for testing by mocking whole USB stack. This function 186 must be called before sanei_usb_init(). 187 188 The sanei_usb subsystem also implements a "development mode". It modifies 189 the XML data file with the actual commands of the test run and attempts to 190 proceed testing until a mismatching input command is found for which 191 input data is required. 192 193 A <known_commands_end/> node in the data XML file will cause sanei_usb not 194 to continue to the subsequent command in the XML file and instead it will 195 prepend all output commands before that node before an output command is 196 encountered. 197 198 @param path Path to the XML data file. 199 @param development_mode Enables development mode. 200 */ 201 extern SANE_Status sanei_usb_testing_enable_replay(SANE_String_Const path, 202 int development_mode); 203 204 /** Initialize sanei_usb for recording. 205 * 206 * Initializes sanei_usb for recording communication with the scanner. This 207 * function must be called before sanei_usb_init(). 208 * 209 * @param path Path to the XML data file. 210 * @param be_name The name of the backend to enable recording for. 211 */ 212 extern SANE_Status sanei_usb_testing_enable_record(SANE_String_Const path, 213 SANE_String_Const be_name); 214 215 /** Returns backend name for testing. 216 * 217 * Returns backend name for the file registered in sanei_usb_testing_enable. 218 * The caller is responsible for freeing it. 219 */ 220 extern SANE_String sanei_usb_testing_get_backend(); 221 222 /** Returns SANE_TRUE if replay testing mode is enabled, i.e. whether we are working with fake 223 * scan data. 224 */ 225 extern SANE_Bool sanei_usb_is_replay_mode_enabled(); 226 227 /** Clears currently recorded data. 228 229 This is useful on certain backends to clear the currently recorded data if it relates to 230 other devices than the one that the scan will be performed on. On these backends all 231 devices that the backend supports are opened multiple times. Recording this interaction 232 to XML file makes it impossible to replay it, as the existence of these devices is not mocked 233 currently. 234 235 This function may only be called when no USB devices are open, otherwise the behavior is 236 unpredictable. 237 */ 238 extern void sanei_usb_testing_record_clear(); 239 240 /** Records a debug message in the captured USB data if testing mode is enabled. If testing mode 241 * is not enabled, this function does nothing. 242 * 243 * @param msg Message to record 244 */ 245 extern void sanei_usb_testing_record_message(SANE_String_Const message); 246 247 /** Initialize sanei_usb. 248 * 249 * Call this before any other sanei_usb function. 250 */ 251 extern void sanei_usb_init (void); 252 253 /** End sanei_usb use, freeing resources when needed. 254 * 255 * When the use count of sanei_usb reach 0, free resources and end 256 * sanei_usb use. 257 */ 258 extern void sanei_usb_exit (void); 259 260 /** Search for USB devices. 261 * 262 * Search USB buses for scanner devices. 263 */ 264 extern void sanei_usb_scan_devices (void); 265 266 /** Get the vendor and product ids by device name. 267 * 268 * @param devname 269 * @param vendor vendor id 270 * @param product product id 271 * 272 * @return 273 * - SANE_STATUS_GOOD - if the ids could be determined 274 * - SANE_STATUS_INVAL - if the device is not found 275 * - SANE_STATUS_UNSUPPORTED - if this method is not supported with the current 276 * access method 277 */ 278 SANE_Status 279 sanei_usb_get_vendor_product_byname (SANE_String_Const devname, 280 SANE_Word * vendor, SANE_Word * product); 281 282 /** Get the vendor and product ids. 283 * 284 * Currently, only libusb devices and scanners supported by the Linux USB 285 * scanner module can be found. For the latter method, the Linux version 286 * must be 2.4.8 or higher. 287 * 288 * @param dn device number of an already sanei_usb_opened device 289 * @param vendor vendor id 290 * @param product product id 291 * 292 * @return 293 * - SANE_STATUS_GOOD - if the ids could be determined 294 * - SANE_STATUS_UNSUPPORTED - if the OS doesn't support detection of ids 295 */ 296 extern SANE_Status 297 sanei_usb_get_vendor_product (SANE_Int dn, SANE_Word * vendor, 298 SANE_Word * product); 299 300 /** Find devices that match given vendor and product ids. 301 * 302 * For limitations, see function sanei_usb_get_vendor_product(). 303 * The function attach is called for every device which has been found. 304 * 305 * @param vendor vendor id 306 * @param product product id 307 * @param attach attach function 308 * 309 * @return SANE_STATUS_GOOD - on success (even if no scanner was found) 310 */ 311 extern SANE_Status 312 sanei_usb_find_devices (SANE_Int vendor, SANE_Int product, 313 SANE_Status (*attach) (SANE_String_Const devname)); 314 315 /** Open a USB device. 316 * 317 * The device is opened by its name devname and the device number is 318 * returned in dn on success. 319 * 320 * Device names can be either device file names for direct access over 321 * kernel drivers (like /dev/usb/scanner) or libusb names. The libusb format 322 * looks like this: "libusb:bus-id:device-id". Bus-id and device-id are 323 * platform-dependent. An example could look like this: "libusb:001:002" 324 * (Linux). 325 * 326 * @param devname name of the device to open 327 * @param dn device number 328 * 329 * @return 330 * - SANE_STATUS_GOOD - on success 331 * - SANE_STATUS_ACCESS_DENIED - if the file couldn't be accessed due to 332 * permissions 333 * - SANE_STATUS_INVAL - on every other error 334 */ 335 extern SANE_Status sanei_usb_open (SANE_String_Const devname, SANE_Int * dn); 336 337 /** Set the endpoint for the USB communication 338 * 339 * Allows to switch to a different endpoint for the USB communication than 340 * the default (auto-detected) endpoint. This function can only be called 341 * after sanei_usb_open. 342 * 343 * @param dn device number 344 * @param ep_type type of endpoint to set (bitwise or of USB_DIR_IN/OUT and 345 * USB_ENDPOINT_TYPE_BULK/CONTROL/INTERRUPT/ISOCHRONOUS 346 * @param ep endpoint to use for the given type 347 * 348 */ 349 extern void sanei_usb_set_endpoint (SANE_Int dn, SANE_Int ep_type, SANE_Int ep); 350 351 /** Retrieve the endpoint used for the USB communication 352 * 353 * Returns the endpoint used for the USB communication of the given type. 354 * This function can only be called after sanei_usb_open. 355 * 356 * @param dn device number 357 * @param ep_type type of endpoint to retrieve (bitwise or of USB_DIR_IN/OUT 358 * and USB_ENDPOINT_TYPE_BULK/CONTROL/INTERRUPT/ISOCHRONOUS 359 * @return endpoint used for the given type 360 * 361 */ 362 extern SANE_Int sanei_usb_get_endpoint (SANE_Int dn, SANE_Int ep_type); 363 364 /** Close a USB device. 365 * 366 * @param dn device number 367 */ 368 extern void sanei_usb_close (SANE_Int dn); 369 370 /** Set the libusb timeout for bulk and interrupt reads. 371 * 372 * @param timeout the new timeout in ms 373 */ 374 extern void sanei_usb_set_timeout (SANE_Int timeout); 375 376 /** Check if sanei_usb_set_timeout() is available. 377 */ 378 #define HAVE_SANEI_USB_SET_TIMEOUT 379 380 /** Clear halt condition on bulk endpoints 381 * 382 * @param dn device number 383 */ 384 extern SANE_Status sanei_usb_clear_halt (SANE_Int dn); 385 386 /** Check if sanei_usb_clear_halt() is available. 387 */ 388 #define HAVE_SANEI_USB_CLEAR_HALT 389 390 /** Reset device 391 * 392 * @param dn device number 393 */ 394 extern SANE_Status sanei_usb_reset (SANE_Int dn); 395 396 /** Initiate a bulk transfer read. 397 * 398 * Read up to size bytes from the device to buffer. After the read, size 399 * contains the number of bytes actually read. 400 * 401 * @param dn device number 402 * @param buffer buffer to store read data in 403 * @param size size of the data 404 * 405 * @return 406 * - SANE_STATUS_GOOD - on success 407 * - SANE_STATUS_EOF - if zero bytes have been read 408 * - SANE_STATUS_IO_ERROR - if an error occurred during the read 409 * - SANE_STATUS_INVAL - on every other error 410 * 411 */ 412 extern SANE_Status 413 sanei_usb_read_bulk (SANE_Int dn, SANE_Byte * buffer, size_t * size); 414 415 /** Initiate a bulk transfer write. 416 * 417 * Write up to size bytes from buffer to the device. After the write size 418 * contains the number of bytes actually written. 419 * 420 * @param dn device number 421 * @param buffer buffer to write to device 422 * @param size size of the data 423 * 424 * @return 425 * - SANE_STATUS_GOOD - on success 426 * - SANE_STATUS_IO_ERROR - if an error occurred during the write 427 * - SANE_STATUS_INVAL - on every other error 428 */ 429 extern SANE_Status 430 sanei_usb_write_bulk (SANE_Int dn, const SANE_Byte * buffer, size_t * size); 431 432 /** Send/receive a control message to/from a USB device. 433 * 434 * This function is only supported for libusb devices and kernel access with 435 * Linux 2.4.13 and newer. 436 * For a detailed explanation of the parameters, have a look at the USB 437 * specification at the <a href="http://www.usb.org/developers/docs/"> 438 * www.usb.org developers information page</a>. 439 * 440 * @param dn device number 441 * @param rtype specifies the characteristics of the request (e.g. data 442 * direction) 443 * @param req actual request 444 * @param value parameter specific to the request 445 * @param index parameter specific to the request (often used to select 446 * endpoint) 447 * @param len length of data to send/receive 448 * @param data buffer to send/receive data 449 * 450 * @return 451 * - SANE_STATUS_GOOD - on success 452 * - SANE_STATUS_IO_ERROR - on error 453 * - SANE_STATUS_UNSUPPORTED - if the feature is not supported by the OS or 454 * SANE. 455 */ 456 extern SANE_Status 457 sanei_usb_control_msg (SANE_Int dn, SANE_Int rtype, SANE_Int req, 458 SANE_Int value, SANE_Int index, SANE_Int len, 459 SANE_Byte * data); 460 461 /** Initiate a interrupt transfer read. 462 * 463 * Read up to size bytes from the interrupt endpoint from the device to 464 * buffer. After the read, size contains the number of bytes actually read. 465 * 466 * @param dn device number 467 * @param buffer buffer to store read data in 468 * @param size size of the data 469 * 470 * @return 471 * - SANE_STATUS_GOOD - on success 472 * - SANE_STATUS_EOF - if zero bytes have been read 473 * - SANE_STATUS_IO_ERROR - if an error occurred during the read 474 * - SANE_STATUS_INVAL - on every other error 475 * 476 */ 477 478 extern SANE_Status 479 sanei_usb_read_int (SANE_Int dn, SANE_Byte * buffer, size_t * size); 480 481 /** Expand device name patterns into a list of devices. 482 * 483 * Apart from a normal device name (such as /dev/usb/scanner0 or 484 * libusb:002:003), this function currently supports USB device 485 * specifications of the form: 486 * 487 * usb VENDOR PRODUCT 488 * 489 * VENDOR and PRODUCT are non-negative integer numbers in decimal or 490 * hexadecimal format. A similar function for SCSI devices can be found 491 * in include/sane/config.h. 492 * 493 * @param name device name pattern 494 * @param attach attach function 495 * 496 */ 497 extern void 498 sanei_usb_attach_matching_devices (const char *name, 499 SANE_Status (*attach) (const char *dev)); 500 501 /** Initiate set configuration. 502 * 503 * Change set configuration 504 * 505 * @param dn device number 506 * @param configuration, configuration nummber 507 * 508 * @return 509 * - SANE_STATUS_GOOD - on success 510 * - SANE_STATUS_EOF - if zero bytes have been read 511 * - SANE_STATUS_IO_ERROR - if an error occurred during the read 512 * - SANE_STATUS_INVAL - on every other error 513 * 514 */ 515 516 extern SANE_Status 517 sanei_usb_set_configuration (SANE_Int dn, SANE_Int configuration); 518 519 /** Initiate claim interface. 520 * 521 * Change claim interface 522 * 523 * @param dn device number 524 * @param interface_number interface number 525 * 526 * @return 527 * - SANE_STATUS_GOOD - on success 528 * - SANE_STATUS_EOF - if zero bytes have been read 529 * - SANE_STATUS_IO_ERROR - if an error occurred during the read 530 * - SANE_STATUS_INVAL - on every other error 531 * 532 */ 533 534 extern SANE_Status 535 sanei_usb_claim_interface (SANE_Int dn, SANE_Int interface_number); 536 537 /** Initiate release interface. 538 * 539 * Change release interface 540 * 541 * @param dn device number 542 * @param interface_number interface number 543 * 544 * @return 545 * - SANE_STATUS_GOOD - on success 546 * - SANE_STATUS_EOF - if zero bytes have been read 547 * - SANE_STATUS_IO_ERROR - if an error occurred during the read 548 * - SANE_STATUS_INVAL - on every other error 549 * 550 */ 551 552 extern SANE_Status 553 sanei_usb_release_interface (SANE_Int dn, SANE_Int interface_number); 554 555 /** Initiate a set altinterface. 556 * 557 * Change set alternate 558 * 559 * @param dn device number 560 * @param alternate, alternate nummber 561 * 562 * @return 563 * - SANE_STATUS_GOOD - on success 564 * - SANE_STATUS_EOF - if zero bytes have been read 565 * - SANE_STATUS_IO_ERROR - if an error occurred during the read 566 * - SANE_STATUS_INVAL - on every other error 567 * 568 */ 569 570 extern SANE_Status 571 sanei_usb_set_altinterface (SANE_Int dn, SANE_Int alternate); 572 573 /** Get some information from the device descriptor 574 * 575 * Sometimes it's useful to know something about revisions and 576 * other stuff reported by the USB system 577 * 578 * @param dn device number 579 * @param desc where to put the information to 580 * 581 * @return 582 * - SANE_STATUS_GOOD - on success 583 * - SANE_STATUS_UNSUPPORTED - if the feature is not supported by the OS or 584 * SANE. 585 * - SANE_STATUS_INVAL - on every other error 586 * 587 */ 588 589 extern SANE_Status 590 sanei_usb_get_descriptor( SANE_Int dn, struct sanei_usb_dev_descriptor *desc ); 591 592 #ifdef __cplusplus 593 } // extern "C" 594 #endif 595 596 /*------------------------------------------------------*/ 597 #endif /* sanei_usb_h */ 598