1 /* sane - Scanner Access Now Easy. 2 3 Copyright (C) 2002 Sergey Vlasov <vsu@altlinux.ru> 4 Copyright (C) 2002 - 2007 Henning Geinitz <sane@geinitz.org> 5 6 This file is part of the SANE package. 7 8 This program is free software; you can redistribute it and/or 9 modify it under the terms of the GNU General Public License as 10 published by the Free Software Foundation; either version 2 of the 11 License, or (at your option) any later version. 12 13 This program is distributed in the hope that it will be useful, but 14 WITHOUT ANY WARRANTY; without even the implied warranty of 15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 16 General Public License for more details. 17 18 You should have received a copy of the GNU General Public License 19 along with this program. If not, see <https://www.gnu.org/licenses/>. 20 21 As a special exception, the authors of SANE give permission for 22 additional uses of the libraries contained in this release of SANE. 23 24 The exception is that, if you link a SANE library with other files 25 to produce an executable, this does not by itself cause the 26 resulting executable to be covered by the GNU General Public 27 License. Your use of that executable is in no way restricted on 28 account of linking the SANE library code into it. 29 30 This exception does not, however, invalidate any other reasons why 31 the executable file might be covered by the GNU General Public 32 License. 33 34 If you submit changes to SANE to the maintainers to be included in 35 a subsequent release, you agree by submitting the changes that 36 those changes may be distributed with this exception intact. 37 38 If you write modifications of your own for SANE, it is your choice 39 whether to permit this exception to apply to your modifications. 40 If you do not wish that, delete this exception notice. 41 */ 42 43 #ifndef GT68XX_LOW_H 44 #define GT68XX_LOW_H 45 46 /** @file 47 * @brief Low-level scanner interface functions. 48 */ 49 50 #include "../include/sane/sane.h" 51 52 #include <stddef.h> 53 54 #ifdef USE_FORK 55 #include <sys/types.h> 56 #include "gt68xx_shm_channel.h" 57 #endif 58 59 #ifdef NDEBUG 60 #undef MAX_DEBUG 61 #endif 62 63 /* calculate the minimum/maximum values */ 64 #define MIN(a, b) (((a) < (b)) ? (a) : (b)) 65 #define MAX(a, b) (((a) > (b)) ? (a) : (b)) 66 67 /* return the lower/upper 8 bits of a 16 bit word */ 68 #define HIBYTE(w) ((SANE_Byte)(((SANE_Word)(w) >> 8) & 0xFF)) 69 #define LOBYTE(w) ((SANE_Byte)(w)) 70 71 72 /* return if an error occurred while the function was called */ 73 #ifdef MAX_DEBUG 74 75 # define RIE(function) \ 76 do \ 77 { \ 78 status = function; \ 79 if (status != SANE_STATUS_GOOD) \ 80 { \ 81 DBG (7, "%s: %s: %s\n", __func__, STRINGIFY(function), \ 82 sane_strstatus (status)); \ 83 return status; \ 84 } \ 85 } \ 86 while (SANE_FALSE) 87 88 #else 89 90 # define RIE(function) \ 91 do { status = function; \ 92 if (status != SANE_STATUS_GOOD) return status; \ 93 } while (SANE_FALSE) 94 95 #endif 96 97 /* Flags */ 98 #define GT68XX_FLAG_MIRROR_X (1 << 0) /* CIS unit mounted the other way round? */ 99 #define GT68XX_FLAG_MOTOR_HOME (1 << 1) /* Use motor_home command (0x34) */ 100 #define GT68XX_FLAG_OFFSET_INV (1 << 2) /* Offset control is inverted */ 101 #define GT68XX_FLAG_UNTESTED (1 << 3) /* Print a warning for these scanners */ 102 #define GT68XX_FLAG_SE_2400 (1 << 4) /* Special quirks for SE 2400USB */ 103 #define GT68XX_FLAG_NO_STOP (1 << 5) /* Don't call stop_scan before the scan */ 104 #define GT68XX_FLAG_CIS_LAMP (1 << 6) /* CIS sensor with lamp */ 105 #define GT68XX_FLAG_NO_POWER_STATUS (1 << 7) /* get_power_status_doesn't work */ 106 #define GT68XX_FLAG_NO_LINEMODE (1 << 8) /* Linemode does not work with this scanner */ 107 #define GT68XX_FLAG_SCAN_FROM_HOME (1 << 9) /* Move home after calibration */ 108 #define GT68XX_FLAG_USE_OPTICAL_X (1 << 10) /* Use optical xdpi for 50 dpi and below */ 109 #define GT68XX_FLAG_ALWAYS_LINEMODE (1 << 11) /* Linemode must be used for any resolution */ 110 #define GT68XX_FLAG_SHEET_FED (1 << 12) /* we have a sheet fed scanner */ 111 #define GT68XX_FLAG_HAS_CALIBRATE (1 << 13) /* for sheet fed scanners that be calibrated with 112 an calibration sheet */ 113 #define GT68XX_FLAG_NO_CALIBRATE (1 << 14) /* don't calibrate, because calibration is broken */ 114 115 116 117 /* Forward typedefs */ 118 typedef struct GT68xx_USB_Device_Entry GT68xx_USB_Device_Entry; 119 typedef struct GT68xx_Command_Set GT68xx_Command_Set; 120 typedef struct GT68xx_Model GT68xx_Model; 121 typedef struct GT68xx_Device GT68xx_Device; 122 typedef struct GT68xx_Scan_Request GT68xx_Scan_Request; 123 typedef struct GT68xx_Scan_Parameters GT68xx_Scan_Parameters; 124 typedef struct GT68xx_AFE_Parameters GT68xx_AFE_Parameters; 125 typedef struct GT68xx_Exposure_Parameters GT68xx_Exposure_Parameters; 126 127 typedef enum GT68xx_Color_Order 128 { 129 COLOR_ORDER_RGB, 130 COLOR_ORDER_BGR 131 } 132 GT68xx_Color_Order; 133 134 #define GT68XX_COLOR_RED SANE_I18N ("Red") 135 #define GT68XX_COLOR_GREEN SANE_I18N ("Green") 136 #define GT68XX_COLOR_BLUE SANE_I18N ("Blue") 137 138 /** Scan action code (purpose of the scan). 139 * 140 * The scan action code affects various scanning mode fields in the setup 141 * command. 142 */ 143 typedef enum GT68xx_Scan_Action 144 { 145 SA_CALIBRATE, /**< Calibration scan, no offsets, no LD 146 correction */ 147 SA_CALIBRATE_ONE_LINE, /**< Same, but only one line for auto AFE */ 148 SA_SCAN /**< Normal scan */ 149 } 150 GT68xx_Scan_Action; 151 152 /** USB device list entry. */ 153 struct GT68xx_USB_Device_Entry 154 { 155 SANE_Word vendor; /**< USB vendor identifier */ 156 SANE_Word product; /**< USB product identifier */ 157 GT68xx_Model *model; /**< Scanner model information */ 158 }; 159 160 #define MAX_SCANNERS 50 161 /* Looks like gcc doesn't like declarations without specificating the number 162 of array elements at least when --enable-warnings is active */ 163 164 /** List of all supported devices. 165 * 166 * This is an array of GT68xx_USB_Device_Entry structures which describe 167 * USB devices supported by this backend. The array is terminated by an 168 * entry with model = NULL. 169 * 170 */ 171 static GT68xx_USB_Device_Entry gt68xx_usb_device_list[MAX_SCANNERS]; 172 173 /** GT68xx analog front-end (AFE) parameters. 174 */ 175 struct GT68xx_AFE_Parameters 176 { 177 SANE_Byte r_offset; /**< Red channel offset */ 178 SANE_Byte r_pga; /**< Red channel PGA gain */ 179 SANE_Byte g_offset; /**< Green channel offset (also used for mono) */ 180 SANE_Byte g_pga; /**< Green channel PGA gain (also used for mono) */ 181 SANE_Byte b_offset; /**< Blue channel offset */ 182 SANE_Byte b_pga; /**< Blue channel PGA gain */ 183 }; 184 185 /** GT68xx exposure time parameters. 186 */ 187 struct GT68xx_Exposure_Parameters 188 { 189 SANE_Int r_time; /**< Red exposure time */ 190 SANE_Int g_time; /**< Red exposure time */ 191 SANE_Int b_time; /**< Red exposure time */ 192 }; 193 194 195 /** 196 * Scanner command set description. 197 * 198 * This description contains parts which are common to all scanners with the 199 * same command set, but may have different optical resolution and other 200 * parameters. 201 */ 202 struct GT68xx_Command_Set 203 { 204 /** @name Identification */ 205 /*@{ */ 206 207 /** Name of this command set */ 208 SANE_String_Const name; 209 210 /*@} */ 211 212 /** @name USB request parameters 213 * 214 * These values are used in the USB control transfer parameters (wValue and 215 * wIndex fields, as in the USB specification). 216 */ 217 /*@{ */ 218 219 SANE_Byte request_type; /**< Request type (should be 0x40, vendor spec) */ 220 SANE_Byte request; /**< Vendor spec request (0x01 or 0x04) */ 221 SANE_Word memory_read_value; /**< Memory read - wValue */ 222 SANE_Word memory_write_value; /**< Memory write - wValue */ 223 SANE_Word send_cmd_value; /**< Send normal command - wValue */ 224 SANE_Word send_cmd_index; /**< Send normal command - wIndex */ 225 SANE_Word recv_res_value; /**< Receive normal result - wValue */ 226 SANE_Word recv_res_index; /**< Receive normal result - wIndex */ 227 SANE_Word send_small_cmd_value; /**< Send small command - wValue */ 228 SANE_Word send_small_cmd_index; /**< Send small command - wIndex */ 229 SANE_Word recv_small_res_value; /**< Receive small result - wValue */ 230 SANE_Word recv_small_res_index; /**< Receive small result - wIndex */ 231 232 /*@} */ 233 234 /** @name Activation/deactivation hooks 235 * 236 * These hooks can be used to perform additional actions when the device is 237 * activated and deactivated. 238 */ 239 /*@{ */ 240 241 /** Activate the device. 242 * 243 * This function may allocate a command-set-specific data structure and place 244 * the pointer to it into the GT68xx_Device::command_set_private field. 245 */ 246 SANE_Status (*activate) (GT68xx_Device * dev); 247 248 /** Deactivate the device. 249 * 250 * If the activate function has allocated a command-set-specific data 251 * structure, this function must free all corresponding resources and set the 252 * GT68xx_Device::command_set_private pointer to #NULL. 253 */ 254 SANE_Status (*deactivate) (GT68xx_Device * dev); 255 256 /*@} */ 257 258 /** @name Low-level command implementation functions 259 * 260 * These functions should implement the corresponding commands for the 261 * particular command set. If a function cannot be implemented because there 262 * is no corresponding command in the command set, the function pointer 263 * should be set to #NULL; the wrapper will return #SANE_STATUS_UNSUPPORTED 264 * in this case. 265 */ 266 /*@{ */ 267 268 /** Check whether the firmware is already downloaded. 269 * 270 * @param dev Device object. 271 * @param loaded Returned firmware status: 272 * - #SANE_TRUE - the firmware is already loaded. 273 * - #SANE_FALSE - the firmware is not loaded. 274 */ 275 SANE_Status (*check_firmware) (GT68xx_Device * dev, SANE_Bool * loaded); 276 277 /** Download the firmware */ 278 SANE_Status (*download_firmware) (GT68xx_Device * dev, 279 SANE_Byte * data, SANE_Word size); 280 281 /** Check whether the external power supply is connected. 282 * 283 * @param dev Device object. 284 * @param power_ok Returned power status: 285 * - #SANE_TRUE - the external power supply is connected, or the scanner does 286 * not need external power. 287 * - #SANE_FALSE - the external power supply is not connected, so the scanner 288 * will not work. 289 */ 290 SANE_Status (*get_power_status) (GT68xx_Device * dev, 291 SANE_Bool * power_ok); 292 293 /** Check whether a transparency adapter is attached to the scanner. 294 * 295 * @param dev Device object. 296 * @param ta_attached Returned transparency adapter status: 297 * - #SANE_TRUE - the transparency adapter is connected. 298 * - #SANE_FALSE - the transparency adapter is not connected. 299 * 300 * @return 301 * - #SANE_STATUS_GOOD - transparency adapter status was checked 302 * successfully; check @a *ta_attached for the result. 303 * - #SANE_STATUS_UNSUPPORTED - this scanner model does not support the 304 * transparency adapter. 305 * */ 306 SANE_Status (*get_ta_status) (GT68xx_Device * dev, 307 SANE_Bool * ta_attached); 308 309 /** Turn the lamps in the scanner and/or the transparency adapter on or off. 310 * 311 * @param dev Device object. 312 * @param fb_lamp #SANE_TRUE turns on the flatbed lamp. 313 * @param ta_lamp #SANE_TRUE turns on the transparency adapter lamp. 314 * 315 * @return 316 * - #SANE_STATUS_GOOD - the command completed successfully. 317 * - #SANE_STATUS_UNSUPPORTED - unsupported request was made (like attempt to 318 * turn on the TA lamp on a scanner which does not support TA). 319 */ 320 SANE_Status (*lamp_control) (GT68xx_Device * dev, SANE_Bool fb_lamp, 321 SANE_Bool ta_lamp); 322 323 /** Check whether the scanner carriage is still moving. 324 * 325 * @param dev Device object. 326 * @param moving Returned state of the scanner: 327 * - #SANE_TRUE - the scanner carriage is still moving. 328 * - #SANE_FALSE - the scanner carriage has stopped. 329 * 330 * @return 331 * - #SANE_STATUS_GOOD - the command completed successfully, the status in @a 332 * *moving is valid. 333 */ 334 SANE_Status (*is_moving) (GT68xx_Device * dev, SANE_Bool * moving); 335 336 337 /** Move the scanner carriage by the specified number of steps. 338 * 339 * @param dev Device object. 340 * @param distance Number of steps to move (positive to move forward, 341 * negative to move backward). The measurement unit is model-dependent; 342 * number of steps per inch is found in the GT68xx_Model::base_ydpi field. 343 * 344 * @return 345 * - #SANE_STATUS_GOOD - the command completed successfully; the movement is 346 * started. Call gt68xx_device_is_moving() periodically to determine when 347 * the movement is complete. 348 */ 349 SANE_Status (*move_relative) (GT68xx_Device * dev, SANE_Int distance); 350 351 /** Move the scanner carriage to the home position. 352 * 353 * @param dev Device object. 354 */ 355 SANE_Status (*carriage_home) (GT68xx_Device * dev); 356 357 /** Eject the paper at the end of the scan. 358 * 359 * @param dev Device object. 360 */ 361 SANE_Status (*paperfeed) (GT68xx_Device * dev); 362 363 /** Start scanning the image. 364 * 365 * @param dev Device object. 366 */ 367 SANE_Status (*start_scan) (GT68xx_Device * dev); 368 369 /** Start reading the scanned image data from the scanner. 370 * 371 * @param dev Device object. 372 * */ 373 SANE_Status (*read_scanned_data) (GT68xx_Device * dev, SANE_Bool * ready); 374 375 /** Stop scanning the image and reading the data. */ 376 SANE_Status (*stop_scan) (GT68xx_Device * dev); 377 378 /** Set parameters for the next scan. */ 379 SANE_Status (*setup_scan) (GT68xx_Device * dev, 380 GT68xx_Scan_Request * request, 381 GT68xx_Scan_Action action, 382 GT68xx_Scan_Parameters * params); 383 384 SANE_Status (*set_afe) (GT68xx_Device * dev, 385 GT68xx_AFE_Parameters * params); 386 387 SANE_Status (*set_exposure_time) (GT68xx_Device * dev, 388 GT68xx_Exposure_Parameters * params); 389 390 /** Get the vendor, product and some more ids from the scanner */ 391 SANE_Status (*get_id) (GT68xx_Device * dev); 392 393 /** Move the paper by the amount of y offset needed to reach scan area 394 * 395 * @param dev Device object. 396 * @param request scan request used to compute move to reach scan area 397 */ 398 SANE_Status (*move_paper) (GT68xx_Device * dev, 399 GT68xx_Scan_Request * request); 400 401 /** Detect if a document is inserted in the feeder 402 * 403 * @param dev Device object. 404 * @param present 405 */ 406 SANE_Status (*document_present) (GT68xx_Device * dev, 407 SANE_Bool *present); 408 /*@} */ 409 }; 410 411 #define MAX_RESOLUTIONS 12 412 #define MAX_DPI 4 413 414 /** Model-specific scanner data. 415 */ 416 struct GT68xx_Model 417 { 418 /** @name Identification */ 419 /*@{ */ 420 421 /** A single lowercase word to be used in the configuration file. */ 422 SANE_String_Const name; 423 424 /** Device vendor string. */ 425 SANE_String_Const vendor; 426 427 /** Device model name. */ 428 SANE_String_Const model; 429 430 /** Name of the firmware file. */ 431 SANE_String_Const firmware_name; 432 433 /** Dynamic allocation flag. 434 * 435 * This flag must be set to SANE_TRUE if the structure is dynamically 436 * allocated; in this case the structure will be freed when the GT68xx_Device 437 * is freed. 438 */ 439 SANE_Bool allocated; 440 /*@} */ 441 442 /** @name Scanner model parameters */ 443 /*@{ */ 444 445 GT68xx_Command_Set *command_set; 446 447 SANE_Int optical_xdpi; /* maximum resolution in x-direction */ 448 SANE_Int optical_ydpi; /* maximum resolution in y-direction */ 449 SANE_Int base_xdpi; /* x-resolution used to calculate geometry */ 450 SANE_Int base_ydpi; /* y-resolution used to calculate geometry */ 451 SANE_Int ydpi_no_backtrack; /* if ydpi is equal or higher, disable backtracking */ 452 SANE_Bool constant_ydpi; /* Use base_ydpi for all resolutions */ 453 454 SANE_Int xdpi_values[MAX_RESOLUTIONS]; /* possible x resolutions */ 455 SANE_Int ydpi_values[MAX_RESOLUTIONS]; /* possible y resolutions */ 456 SANE_Int bpp_gray_values[MAX_DPI]; /* possible depths in gray mode */ 457 SANE_Int bpp_color_values[MAX_DPI]; /* possible depths in color mode */ 458 459 SANE_Fixed x_offset; /* Start of scan area in mm */ 460 SANE_Fixed y_offset; /* Start of scan area in mm */ 461 SANE_Fixed x_size; /* Size of scan area in mm */ 462 SANE_Fixed y_size; /* Size of scan area in mm */ 463 464 SANE_Fixed y_offset_calib; /* Start of white strip in mm */ 465 SANE_Fixed x_offset_mark; /* Start of black mark in mm */ 466 467 SANE_Fixed x_offset_ta; /* Start of scan area in TA mode in mm */ 468 SANE_Fixed y_offset_ta; /* Start of scan area in TA mode in mm */ 469 SANE_Fixed x_size_ta; /* Size of scan area in TA mode in mm */ 470 SANE_Fixed y_size_ta; /* Size of scan area in TA mode in mm */ 471 472 SANE_Fixed y_offset_calib_ta; /* Start of white strip in TA mode in mm */ 473 474 /* Line-distance correction (in pixel at optical_ydpi) for CCD scanners */ 475 SANE_Int ld_shift_r; /* red */ 476 SANE_Int ld_shift_g; /* green */ 477 SANE_Int ld_shift_b; /* blue */ 478 SANE_Int ld_shift_double; /* distance between two CCD lines of one color 479 (only applicable for CCD with 6 lines) */ 480 481 GT68xx_Color_Order line_mode_color_order; /* Order of the CCD/CIS colors */ 482 483 GT68xx_AFE_Parameters afe_params; /* Default offset/gain */ 484 GT68xx_Exposure_Parameters exposure; /* Default exposure parameters */ 485 SANE_Fixed default_gamma_value; /* Default gamma value */ 486 487 SANE_Bool is_cis; /* Is this a CIS or CCD scanner? */ 488 489 SANE_Word flags; /* Which hacks are needed for this scanner? */ 490 /*@} */ 491 }; 492 493 /** GT68xx device instance. 494 * 495 */ 496 struct GT68xx_Device 497 { 498 /** Device file descriptor. */ 499 int fd; 500 501 /** Device activation flag. */ 502 SANE_Bool active; 503 504 /** Device missing to flag devices that are unplugged 505 * after sane_init and before sane_exit */ 506 SANE_Bool missing; 507 508 /** Scanner model data. */ 509 GT68xx_Model *model; 510 511 /** Pointer to command-set-specific data. */ 512 void *command_set_private; 513 514 GT68xx_AFE_Parameters *afe; 515 GT68xx_Exposure_Parameters *exposure; 516 SANE_Fixed gamma_value; 517 518 SANE_Bool read_active; 519 SANE_Bool final_scan; 520 SANE_Byte *read_buffer; 521 size_t requested_buffer_size; 522 size_t read_buffer_size; 523 size_t read_pos; 524 size_t read_bytes_in_buffer; 525 size_t read_bytes_left; 526 SANE_Byte gray_mode_color; 527 SANE_Bool manual_selection; 528 SANE_Bool scan_started; 529 530 #ifdef USE_FORK 531 Shm_Channel *shm_channel; 532 pid_t reader_pid; 533 #endif /* USE_FORK */ 534 535 /** Pointer to next device */ 536 struct GT68xx_Device *next; 537 538 /** Device file name */ 539 SANE_String file_name; 540 }; 541 542 /** Parameters for the high-level scan request. 543 * 544 * These parameters describe the scan request sent by the SANE frontend. 545 */ 546 struct GT68xx_Scan_Request 547 { 548 SANE_Fixed x0; /**< Left boundary */ 549 SANE_Fixed y0; /**< Top boundary */ 550 SANE_Fixed xs; /**< Width */ 551 SANE_Fixed ys; /**< Height */ 552 SANE_Int xdpi; /**< Horizontal resolution */ 553 SANE_Int ydpi; /**< Vertical resolution */ 554 SANE_Int depth; /**< Number of bits per channel */ 555 SANE_Bool color; /**< Color mode flag */ 556 SANE_Bool mbs; /**< Move before scan */ 557 SANE_Bool mds; /**< Move during scan */ 558 SANE_Bool mas; /**< Move after scan */ 559 SANE_Bool lamp; /**< Lamp on/off */ 560 SANE_Bool calculate; /**< Don't scan, only calculate parameters */ 561 SANE_Bool use_ta; /**< Use the tansparency adapter */ 562 SANE_Bool backtrack; /**< Enable backtracking */ 563 SANE_Bool backtrack_lines; /**< How many lines to backtrack */ 564 }; 565 566 /** Scan parameters for gt68xx_device_setup_scan(). 567 * 568 * These parameters describe a low-level scan request; many such requests are 569 * executed during calibration, and they need to have parameters separate from 570 * the main request (GT68xx_Scan_Request). 571 */ 572 struct GT68xx_Scan_Parameters 573 { 574 SANE_Int xdpi; /**< Horizontal resolution */ 575 SANE_Int ydpi; /**< Vertical resolution */ 576 SANE_Int depth; /**< Number of bits per channel */ 577 SANE_Bool color; /**< Color mode flag */ 578 579 SANE_Int pixel_xs; /**< Logical width in pixels */ 580 SANE_Int pixel_ys; /**< Logical height in pixels */ 581 SANE_Int scan_xs; /**< Physical width in pixels */ 582 SANE_Int scan_ys; /**< Physical height in pixels */ 583 SANE_Int scan_bpl; /**< Number of bytes per scan line */ 584 SANE_Bool line_mode; /**< Use line mode instead of pixel mode */ 585 SANE_Int overscan_lines; /**< Number of extra scan lines */ 586 SANE_Int ld_shift_r; 587 SANE_Int ld_shift_g; 588 SANE_Int ld_shift_b; 589 SANE_Int ld_shift_double; 590 SANE_Int double_column; 591 SANE_Int pixel_x0; /**< x start position */ 592 }; 593 594 595 #define GT68XX_PACKET_SIZE 64 596 597 typedef SANE_Byte GT68xx_Packet[GT68XX_PACKET_SIZE]; 598 599 /** Create a new GT68xx_Device object. 600 * 601 * The newly created device object is in the closed state. 602 * 603 * @param dev_return Returned pointer to the created device object. 604 * 605 * @return 606 * - #SANE_STATUS_GOOD - the device object was created. 607 * - #SANE_STATUS_NO_MEM - not enough system resources to create the object. 608 */ 609 static SANE_Status gt68xx_device_new (GT68xx_Device ** dev_return); 610 611 /** Destroy the device object and release all associated resources. 612 * 613 * If the device was active, it will be deactivated; if the device was open, it 614 * will be closed. 615 * 616 * @param dev Device object. 617 * 618 * @return 619 * - #SANE_STATUS_GOOD - success. 620 */ 621 static SANE_Status gt68xx_device_free (GT68xx_Device * dev); 622 623 /** Open the scanner device. 624 * 625 * This function opens the device special file @a dev_name and tries to detect 626 * the device model by its USB ID. 627 * 628 * If the device is detected successfully (its USB ID is found in the supported 629 * device list), this function sets the appropriate model parameters. 630 * 631 * If the USB ID is not recognized, the device remains unconfigured; an attempt 632 * to activate it will fail unless gt68xx_device_set_model() is used to force 633 * the parameter set. Note that the open is considered to be successful in 634 * this case. 635 * 636 * @param dev Device object. 637 * @param dev_name Scanner device name. 638 * 639 * @return 640 * - #SANE_STATUS_GOOD - the device was opened successfully (it still may be 641 * unconfigured). 642 */ 643 static SANE_Status 644 gt68xx_device_open (GT68xx_Device * dev, const char *dev_name); 645 646 /** Close the scanner device. 647 * 648 * @param dev Device object. 649 */ 650 static SANE_Status gt68xx_device_close (GT68xx_Device * dev); 651 652 /** Check if the device is configured. 653 * 654 * A device is considered configured when it has a model parameters structure 655 * (GT68xx_Model) and a command set (GT68xx_Command_Set). Normally these 656 * parameters are assigned automatically by gt68xx_device_open(), if the device 657 * is known. If the USB ID of the device is not found in the list, or the OS 658 * does not support identification of USB devices, the device will be 659 * unconfigured after opening. 660 * 661 * @param dev Device object. 662 * 663 * @return 664 * - #SANE_TRUE - device is configured and can be activated. 665 * - #SANE_FALSE - device is not configured; attempt to activate it will fail. 666 */ 667 static SANE_Bool gt68xx_device_is_configured (GT68xx_Device * dev); 668 669 /** Change the device model structure. 670 * 671 * This function can be used to change all model-dependent parameters at once 672 * by supplying a whole model data structure. The model may be changed only 673 * when the device is not active. 674 * 675 * If the device already had a model structure which was dynamically allocated, 676 * the old structure is freed. 677 * 678 * If the new model structure @a model is dynamically allocated, the device @a 679 * dev takes ownership of it: @a model will be freed when @a dev is destroyed 680 * or gt68xx_device_set_model() is called again. 681 * 682 * @param dev Device object. 683 * @param model Device model data. 684 * 685 * @return 686 * - #SANE_STATUS_GOOD - model successfully changed. 687 * - #SANE_STATUS_INVAL - invalid request (attempt to change model when the 688 * device is already active, or not yet opened). 689 */ 690 static SANE_Status 691 gt68xx_device_set_model (GT68xx_Device * dev, GT68xx_Model * model); 692 693 /** Get model by name. 694 * 695 * This function can be used to find a model by its name. 696 * 697 * @param name Device model name. 698 * @param model Device model data. 699 * 700 * @return 701 * - #SANE_TRUE - model successfully found. 702 * - #SANE_FALSE - model not found. 703 */ 704 static SANE_Bool 705 gt68xx_device_get_model (SANE_String name, GT68xx_Model ** model); 706 707 #if 0 708 /** Create a new private copy of the model data for this device. 709 * 710 * Normally the model data structures can be shared between several devices. 711 * If the program needs to modify some model parameters for a device, it must 712 * call this function to make a private copy of parameters. This private copy 713 * will be automatically freed when the device is destroyed. 714 * 715 * @param dev Device object. 716 * 717 * @return 718 * - #SANE_STATUS_GOOD - a private copy was made successfully. 719 * - #SANE_STATUS_INVAL - invalid request (the device was already active, or 720 * not yet opened). 721 * - #SANE_STATUS_NO_MEM - not enough memory for copy of the model parameters. 722 */ 723 static SANE_Status gt68xx_device_unshare_model (GT68xx_Device * dev); 724 #endif 725 726 /** Activate the device. 727 * 728 * The device must be activated before performing any I/O operations with it. 729 * All device model parameters must be configured before activation; it is 730 * impossible to change them after the device is active. 731 * 732 * This function might need to acquire resources (it calls 733 * GT68xx_Command_Set::activate). These resources will be released when 734 * gt68xx_device_deactivate() is called. 735 * 736 * @param dev Device object. 737 * 738 * @return 739 * - #SANE_STATUS_GOOD - device activated successfully. 740 * - #SANE_STATUS_INVAL - invalid request (attempt to activate a closed or 741 * unconfigured device). 742 */ 743 static SANE_Status gt68xx_device_activate (GT68xx_Device * dev); 744 745 /** Deactivate the device. 746 * 747 * This function reverses the action of gt68xx_device_activate(). 748 * 749 * @param dev Device object. 750 * 751 * @return 752 * - #SANE_STATUS_GOOD - device deactivated successfully. 753 * - #SANE_STATUS_INVAL - invalid request (the device was not activated). 754 */ 755 static SANE_Status gt68xx_device_deactivate (GT68xx_Device * dev); 756 757 /** Write a data block to the GT68xx memory. 758 * 759 * @param dev Device object. 760 * @param addr Start address in the GT68xx memory. 761 * @param size Size of the data block in bytes. 762 * @param data Data block to write. 763 * 764 * @return 765 * - #SANE_STATUS_GOOD - success. 766 * - #SANE_STATUS_IO_ERROR - a communication error occurred. 767 * 768 * @warning 769 * @a size must be a multiple of 64 (at least with GT6816), otherwise the 770 * scanner (and possibly the entire USB bus) will lock up. 771 */ 772 static SANE_Status 773 gt68xx_device_memory_write (GT68xx_Device * dev, SANE_Word addr, 774 SANE_Word size, SANE_Byte * data); 775 776 /** Read a data block from the GT68xx memory. 777 * 778 * @param dev Device object. 779 * @param addr Start address in the GT68xx memory. 780 * @param size Size of the data block in bytes. 781 * @param data Buffer for the read data. 782 * 783 * @return 784 * - #SANE_STATUS_GOOD - success. 785 * - #SANE_STATUS_IO_ERROR - a communication error occurred. 786 * 787 * @warning 788 * @a size must be a multiple of 64 (at least with GT6816), otherwise the 789 * scanner (and possibly the entire USB bus) will lock up. 790 */ 791 static SANE_Status 792 gt68xx_device_memory_read (GT68xx_Device * dev, SANE_Word addr, 793 SANE_Word size, SANE_Byte * data); 794 795 /** Execute a control command. 796 * 797 * @param dev Device object. 798 * @param cmd Command packet. 799 * @param res Result packet (may point to the same buffer as @a cmd). 800 * 801 * @return 802 * - #SANE_STATUS_GOOD - success. 803 * - #SANE_STATUS_IO_ERROR - a communication error occurred. 804 */ 805 static SANE_Status 806 gt68xx_device_req (GT68xx_Device * dev, GT68xx_Packet cmd, GT68xx_Packet res); 807 808 /** Execute a "small" control command. 809 * 810 * @param dev Device object. 811 * @param cmd Command packet; only first 8 bytes are used. 812 * @param res Result packet (may point to the same buffer as @a cmd). 813 * 814 * @return 815 * - #SANE_STATUS_GOOD - success. 816 * - #SANE_STATUS_IO_ERROR - a communication error occurred. 817 */ 818 static SANE_Status 819 gt68xx_device_small_req (GT68xx_Device * dev, GT68xx_Packet cmd, 820 GT68xx_Packet res); 821 822 #if 0 823 /** Check whether the firmware is downloaded into the scanner. 824 * 825 * @param dev Device object. 826 * @param loaded Returned firmware status: 827 * - #SANE_TRUE - the firmware is already loaded. 828 * - #SANE_FALSE - the firmware is not loaded. 829 * 830 * @return 831 * - #SANE_STATUS_GOOD - success. 832 * - #SANE_STATUS_IO_ERROR - a communication error occurred. 833 */ 834 static SANE_Status 835 gt68xx_device_check_firmware (GT68xx_Device * dev, SANE_Bool * loaded); 836 #endif 837 838 static SANE_Status 839 gt68xx_device_download_firmware (GT68xx_Device * dev, 840 SANE_Byte * data, SANE_Word size); 841 842 /** Check whether the external power supply is connected. 843 * 844 * @param dev Device object. 845 * @param power_ok Returned power status: 846 * - #SANE_TRUE - the external power supply is connected, or the scanner does 847 * not need external power. 848 * - #SANE_FALSE - the external power supply is not connected, so the scanner 849 * will not work. 850 * 851 * @return 852 * - #SANE_STATUS_GOOD - success. 853 * - #SANE_STATUS_IO_ERROR - a communication error occurred. 854 */ 855 static SANE_Status 856 gt68xx_device_get_power_status (GT68xx_Device * dev, SANE_Bool * power_ok); 857 858 /** Check whether the transparency adapter is connected. 859 * 860 * @param dev Device object. 861 * @param ta_attached Returned TA status: 862 * - #SANE_TRUE - the TA is connected. 863 * - #SANE_FALSE - the TA is not connected. 864 * 865 * @return 866 * - #SANE_STATUS_GOOD - success. 867 * - #SANE_STATUS_UNSUPPORTED - the scanner does not support TA connection. 868 * - #SANE_STATUS_IO_ERROR - a communication error occurred. 869 */ 870 static SANE_Status 871 gt68xx_device_get_ta_status (GT68xx_Device * dev, SANE_Bool * ta_attached); 872 873 /** Turn the lamps in the scanner and/or the transparency adapter on or off. 874 * 875 * @param dev Device object. 876 * @param fb_lamp #SANE_TRUE turns on the flatbed lamp. 877 * @param ta_lamp #SANE_TRUE turns on the transparency adapter lamp. 878 * 879 * @return 880 * - #SANE_STATUS_GOOD - success. 881 * - #SANE_STATUS_IO_ERROR - a communication error occurred. 882 * - #SANE_STATUS_UNSUPPORTED - unsupported request was made (like attempt to 883 * turn on the TA lamp on a scanner which does not support TA). 884 */ 885 static SANE_Status 886 gt68xx_device_lamp_control (GT68xx_Device * dev, SANE_Bool fb_lamp, 887 SANE_Bool ta_lamp); 888 889 /** Check whether the scanner carriage is still moving. 890 * 891 * @param dev Device object. 892 * @param moving Returned state of the scanner: 893 * - #SANE_TRUE - the scanner carriage is still moving. 894 * - #SANE_FALSE - the scanner carriage has stopped. 895 * 896 * @return 897 * - #SANE_STATUS_GOOD - success; the status in @a *moving is valid. 898 * - #SANE_STATUS_IO_ERROR - a communication error occurred. 899 */ 900 static SANE_Status 901 gt68xx_device_is_moving (GT68xx_Device * dev, SANE_Bool * moving); 902 903 #if 0 904 /** Move the scanner carriage by the specified number of steps. 905 * 906 * @param dev Device object. 907 * @param distance Number of steps to move (positive to move forward, negative 908 * to move backward). The measurement unit is model-dependent; number of steps 909 * per inch is found in the GT68xx_Model::base_ydpi field. 910 * 911 * @return 912 * - #SANE_STATUS_GOOD - success; the movement is started. Call 913 * gt68xx_device_is_moving() periodically to determine when the movement is 914 * complete. 915 * - #SANE_STATUS_IO_ERROR - a communication error occurred. 916 */ 917 static SANE_Status 918 gt68xx_device_move_relative (GT68xx_Device * dev, SANE_Int distance); 919 #endif 920 921 /** Move the scanner carriage to the home position. 922 * 923 * This function starts moving the scanner carriage to the home position, but 924 * deos not wait for finishing the movement. To determine when the carriage 925 * returned to the home position, the program should periodically call 926 * gt68xx_device_is_moving(). 927 * 928 * @param dev Device object. 929 * 930 * @return 931 * - #SANE_STATUS_GOOD - success; the movement is started. 932 * - #SANE_STATUS_IO_ERROR - a communication error occurred. 933 */ 934 static SANE_Status gt68xx_device_carriage_home (GT68xx_Device * dev); 935 936 /** Eject the paper after the end of scanning. 937 * 938 * 939 * @param dev Device object. 940 * 941 * @return 942 * - #SANE_STATUS_GOOD - success; the movement is started. 943 * - #SANE_STATUS_IO_ERROR - a communication error occurred. 944 */ 945 static SANE_Status gt68xx_device_paperfeed (GT68xx_Device * dev); 946 947 /** Start scanning the image. 948 * 949 * This function initiates scanning with parameters set by 950 * gt68xx_device_setup_scan() (which should be called before). In particular, 951 * it starts the carriage movement to the start of the scanning window. 952 * 953 * After calling this function, gt68xx_device_read_scanned_data() should be 954 * called repeatedly until the scanner signals that it is ready to deliver the 955 * data. 956 * 957 * @param dev Device object. 958 * 959 * @return 960 * - #SANE_STATUS_GOOD - success. 961 * - #SANE_STATUS_IO_ERROR - a communication error occurred. 962 */ 963 static SANE_Status gt68xx_device_start_scan (GT68xx_Device * dev); 964 965 /** Start reading the scanned image data. 966 * 967 * This function should be used only after gt68xx_device_start_scan(). It 968 * should be called repeatedly until @a *ready flag becomes true, at which 969 * point reading the image data should be started using 970 * gt68xx_device_read_prepare(). 971 * 972 * @param dev Device object. 973 * @param ready Returned status of the scanner: 974 * - #SANE_TRUE - the scanner is ready to send data. 975 * - #SANE_FALSE - the scanner is not ready (e.g., the carriage has not reached 976 * the start of the scanning window). 977 * 978 * @return 979 * - #SANE_STATUS_GOOD - success; the value in @a *ready is valid. 980 * - #SANE_STATUS_IO_ERROR - a communication error occurred. 981 */ 982 static SANE_Status 983 gt68xx_device_read_scanned_data (GT68xx_Device * dev, SANE_Bool * ready); 984 985 /** Stop scanning the image. 986 * 987 * This function should be used after reading all image data from the scanner, 988 * or in the middle of scan to abort the scanning process. 989 * 990 * @param dev Device object. 991 * 992 * @return 993 * - #SANE_STATUS_GOOD - success. 994 * - #SANE_STATUS_IO_ERROR - a communication error occurred. 995 */ 996 static SANE_Status gt68xx_device_stop_scan (GT68xx_Device * dev); 997 998 /** Set parameters for the next scan. 999 * 1000 * This function calculates the hardware-dependent scanning parameters and, 1001 * unless @a calculate_only is set, sends the command to prepare for scanning 1002 * with the specified window and parameters. 1003 * 1004 * @param dev Device object. 1005 * @param request High-level scanning request. 1006 * @param action Action code describing the phase of calibration or scanning 1007 * process. 1008 * @param params Returned structure with hardware-dependent scanning 1009 * parameters. 1010 * 1011 * @return 1012 * - #SANE_STATUS_GOOD - success. 1013 * - #SANE_STATUS_UNSUPPORTED - the requested scanning parameters in @a request 1014 * are not supported by hardware. 1015 * - #SANE_STATUS_INVAL - some of the parameters in @a request, or the @a 1016 * action code, are completely invalid. 1017 * - #SANE_STATUS_IO_ERROR - a communication error occurred. 1018 */ 1019 static SANE_Status 1020 gt68xx_device_setup_scan (GT68xx_Device * dev, 1021 GT68xx_Scan_Request * request, 1022 GT68xx_Scan_Action action, 1023 GT68xx_Scan_Parameters * params); 1024 1025 /** Configure the analog front-end (AFE) of the GT68xx. 1026 * 1027 * @param dev Device object. 1028 * @param params AFE parameters. 1029 * 1030 * @return 1031 * - #SANE_STATUS_GOOD - success. 1032 * - #SANE_STATUS_IO_ERROR - a communication error occurred. 1033 */ 1034 static SANE_Status 1035 gt68xx_device_set_afe (GT68xx_Device * dev, GT68xx_AFE_Parameters * params); 1036 1037 static SANE_Status 1038 gt68xx_device_set_exposure_time (GT68xx_Device * dev, 1039 GT68xx_Exposure_Parameters * params); 1040 1041 /** Read raw data from the bulk-in scanner pipe. 1042 * 1043 * @param dev Device object. 1044 * @param buffer Buffer for the read data. 1045 * @param size Pointer to the variable which must be set to the requested data 1046 * size before call. After completion this variable will hold the number of 1047 * bytes actually read. 1048 * 1049 * @return 1050 * - #SANE_STATUS_GOOD - success. 1051 * - #SANE_STATUS_IO_ERROR - a communication error occurred. 1052 */ 1053 static SANE_Status 1054 gt68xx_device_read_raw (GT68xx_Device * dev, SANE_Byte * buffer, 1055 size_t * size); 1056 1057 static SANE_Status 1058 gt68xx_device_set_read_buffer_size (GT68xx_Device * dev, size_t buffer_size); 1059 1060 static SANE_Status 1061 gt68xx_device_read_prepare (GT68xx_Device * dev, size_t expected_count, 1062 SANE_Bool final_scan); 1063 1064 static SANE_Status 1065 gt68xx_device_read (GT68xx_Device * dev, SANE_Byte * buffer, size_t * size); 1066 1067 static SANE_Status gt68xx_device_read_finish (GT68xx_Device * dev); 1068 1069 /** Make sure that the result of a command is ok. 1070 * 1071 * @param res Result packet from the last command 1072 * @param command Command 1073 * 1074 * @return 1075 * - #SANE_STATUS_GOOD - success. 1076 * - #SANE_STATUS_IO_ERROR - the command wasn't successful 1077 */ 1078 static SANE_Status 1079 gt68xx_device_check_result (GT68xx_Packet res, SANE_Byte command); 1080 1081 1082 static SANE_Status 1083 gt68xx_device_get_id (GT68xx_Device * dev); 1084 1085 /** Read the device descriptor of the scanner. 1086 * 1087 * This function should be called before closing the device to make sure 1088 * that the device descriptor is properly stored in the scanner's memory. 1089 * If that's not done, the next try to get the config descriptor will 1090 * result in a corrupted descriptor. 1091 * 1092 * @param dev device 1093 */ 1094 static void 1095 gt68xx_device_fix_descriptor (GT68xx_Device * dev); 1096 1097 #endif /* not GT68XX_LOW_H */ 1098 1099 /* vim: set sw=2 cino=>2se-1sn-1s{s^-1st0(0u0 smarttab expandtab: */ 1100