share/man/man4/man4.i386/asc.4

   1 .\" asc(4) - manual page for the scanner device driver `asc'
   2 .\"
   3 .\"
   4 .\" Copyright (c) 1995 Gunther Schadow, Luigi Rizzo. All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. All advertising materials mentioning features or use of this software
  15 .\"    must display the following acknowledgements:
  16 .\"     This product includes software developed by Gunther Schadow.
  17 .\"     This product includes software developed by Luigi Rizzo.
  18 .\" 4. The name of the author may not be used to endorse or promote products
  19 .\"    derived from this software without specific prior written permission.
  20 .\"
  21 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  22 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  23 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  24 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  25 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  26 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  27 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  28 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  29 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  30 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  31 .\"
  32 .\" $FreeBSD: src/share/man/man4/man4.i386/asc.4,v 1.14.2.2 2001/08/17 13:08:45 ru Exp $
  33 .\" $DragonFly: src/share/man/man4/man4.i386/asc.4,v 1.5 2008/01/26 15:14:41 swildner Exp $
  34 .Dd January 19, 1995
  35 .Dt ASC 4 i386
  36 .Os
  37 .Sh NAME
  38 .Nm asc
  39 .Nd device driver for a GI1904-based hand scanner
  40 .Sh SYNOPSIS
  41 .Cd "device asc0 at isa? port IO_ASC1 drq 3 irq 10"
  42 .Sh DESCRIPTION
  43 The
  44 .Nm
  45 character device driver currently handles the
  46 .Tn GI1904 Ns -based
  47 hand scanner (e.g. Trust Amiscan Grey).
  48 It uses DMA and interrupts.
  49 Up to 50 lines of scanned input data are buffered in the driver.
  50 .Pp
  51 The device can operate at four different resolutions: 100, 200, 300
  52 and 400 dots per inch.
  53 It produces a simple bitmap with the most
  54 significant bit at the left side.  The driver can optionally output
  55 the simple portable bitmap file format
  56 .Xr pbm 5 ;
  57 thus the scans can easily processed by most graphics packages.
  58 .Pp
  59 The width of the output bitmap is fixed as given by the
  60 resolution value.  However, the height of the bitmap must be
  61 supplied when in
  62 .Xr pbm 5
  63 mode, since the driver must know at what time the
  64 `end-of-file' shall be reached.  The default is to produce a
  65 square image; i.e., height equals width.
  66 With this feature one is able to
  67 directly copy the scanner output into a
  68 .Xr pbm 5
  69 file using
  70 .Xr cat 1 .
  71 One can obtain a similar effect by using
  72 .Xr dd 1
  73 with the driver
  74 in raw mode.
  75 .Sh IOCTLS
  76 The
  77 .Xr ioctl 2
  78 commands applicable to
  79 .Nm
  80 are listed below.
  81 The
  82 .Xr sasc 1
  83 provides user-level access to these commands.
  84 .Bl -tag -width ".Dv ASC_GHEIGHT"
  85 .It Dv ASC_GRES
  86 .Pq Li int
  87 Get current resolution in dots per inch (dpi).
  88 .It Dv ASC_GWIDTH
  89 .Pq Li int
  90 Get current width of the bitmap in pixels.
  91 .It Dv ASC_SHEIGHT
  92 .Pq Li int
  93 Set the height of the bitmap in
  94 .Xr pbm 5
  95 mode.  This is actually
  96 a limit on the amount of lines scannable after the first read
  97 operation.  When the limit is reached, read will return 0. However, the
  98 device is turned off only when the last open file descriptor is closed.
  99 .It Dv ASC_GHEIGHT
 100 .Pq Li int
 101 Get the current height of the bitmap.
 102 .It Dv ASC_SBLEN
 103 .Pq Li int
 104 Set the length of the buffer used internally to do the DMA transfer.
 105 The buffer length is supplied in lines of the bitmap.
 106 Since the buffer
 107 size limit is (currently) 0x3000 bytes, the maximum number of lines
 108 allowed will vary with the width of each line.  An
 109 .Er ENOMEM
 110 error is returned if the requested length would exceed this limit.
 111 .It Dv ASC_GBLEN
 112 .Pq Li int
 113 Get the current buffer length in lines.
 114 .It Dv ASC_SBTIME
 115 .Pq Li int
 116 Set the timeout for the completion of reading one buffer.
 117 Since a
 118 handy scanner is a human/computer interface timeout values are usually
 119 higher than those of a flat scanner; the default is 15 seconds.  After
 120 timeout is reached the read operation will fail with
 121 .Er EBUSY .
 122 Note that
 123 the timeout timer starts anew for each buffer to be read and thus
 124 reducing it does not result in faster scans for longer images.
 125 .It Dv ASC_GBTIME
 126 .Pq Li int
 127 Get the current buffer timeout.
 128 .El
 129 .Pp
 130 All
 131 .Fn ioctl
 132 requests that modify a parameter except
 133 .Dv ASC_SBTIME
 134 do not have an effect on an ongoing scan process.  The user must close
 135 the device and open it again for the new selections to take effect.
 136 Consequently, the selections are
 137 .Em not
 138 reset when the device is opened or closed.
 139 .Pp
 140 Similarly, requests that read a value do not report the value that is
 141 used for the ongoing scan process.  The values needed during the scan
 142 process are saved when it starts and thus are not accessed by
 143 .Fn ioctl
 144 requests.
 145 .Pp
 146 The
 147 .Dv ASC_SBTIME
 148 value does, however, have an immediate effect on the ongoing scan.
 149 Thus the timeout can, for example, be set to a large value until the
 150 user starts scanning, and then set to a small value to react
 151 (nearly) immediately when the user stops.
 152 .Pp
 153 Note that the
 154 .Xr pbm 5
 155 versus raw mode selection is done by the
 156 minor number, not by
 157 .Fn ioctl
 158 requests.  In raw mode, the selected
 159 height of the bitmap will have no effect.
 160 .Sh FILES
 161 .Bl -tag -width /dev/asc0pd -compact
 162 .It Pa /dev/asc0
 163 device node for raw output
 164 .It Pa /dev/asc0d
 165 device node for raw output, emitting debug messages if the
 166 .Dv ASCDEBUG
 167 option was given in the kernel configuration file
 168 .It Pa /dev/asc0p
 169 device node for output in
 170 .Xr pbm 5
 171 file format
 172 .It Pa /dev/asc0pd
 173 device node for
 174 .Xr pbm 5
 175 and debug mode
 176 .El
 177 .\"
 178 .\" .Sh DIAGNOSTICS
 179 .\"
 180 .Sh SEE ALSO
 181 .Xr sasc 1 ,
 182 .Xr pbm 5 Pq Pa pkgsrc/graphics/netpbm
 183 .Sh HISTORY
 184 The
 185 .Nm
 186 driver first appeared in
 187 .Fx 2.1 .
 188 .Sh AUTHORS
 189 The
 190 .Nm
 191 driver was written by
 192 .An Luigi Rizzo .
 193 .Sh BUGS
 194 Ioctl support is not working yet.