share/man/man4/man4.i386/gsc.4

   1 .\" gsc.4 - manual page for the scanner device driver `gsc'
   2 .\"
   3 .\"
   4 .\" Copyright (c) 1995 Gunther Schadow.  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 acknowledgement:
  16 .\"     This product includes software developed by Gunther Schadow.
  17 .\" 4. The name of the author may not be used to endorse or promote products
  18 .\"    derived from this software without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  21 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  22 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  23 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  24 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  25 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  26 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  27 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  28 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  29 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  30 .\"
  31 .\" $FreeBSD: src/share/man/man4/man4.i386/gsc.4,v 1.12.2.7 2001/12/17 11:30:13 ru Exp $
  32 .\" $DragonFly: src/share/man/man4/man4.i386/gsc.4,v 1.6 2008/04/16 08:29:21 swildner Exp $
  33 .\"
  34 .Dd January 9, 1995
  35 .Os
  36 .Dt GSC 4 i386
  37 .Sh NAME
  38 .Nm gsc
  39 .Nd a device driver for a handy scanner
  40 .Sh SYNOPSIS
  41 .In machine/gsc.h
  42 .Pp
  43 .Cd Minor number bits: Ar uu d g p ...
  44 .Bl -tag -width "uu " -compact -offset indent
  45 .It Ar uu
  46 unit gsc0 .. gsc3
  47 .It Ar d
  48 selects logging of
  49 .Em debug
  50 messages
  51 .It Ar g
  52 selects
  53 .Em bitmap
  54 vs.
  55 .Em graymap
  56 output
  57 .It Ar p
  58 selects
  59 .Em raw
  60 vs. portable
  61 .Em pnm
  62 output
  63 .El
  64 .Sh DESCRIPTION
  65 The
  66 .Nm
  67 character device driver currently handles only the
  68 Genius GS-4500 handy scanner.
  69 It operates in pure DMA modes, although
  70 the hardware could be set up to work with irq.
  71 I had neither enough
  72 documentation nor experience in writing interrupt driven device
  73 drivers.
  74 .Pp
  75 The device can operate at four different
  76 .Em resolutions :
  77 100, 200,
  78 300 and 400dpi.
  79 It produces a simple bitmap with the most significant
  80 bit at the left side.
  81 The driver can optionally output the famous and
  82 likely simple portable bitmap file format
  83 .Xr pbm 5
  84 by Jef Poskanzer.
  85 Thus the scans can easily processed by any graphic package around
  86 .Xr ( xpaint 1 ,
  87 .Xr xv 1 ,
  88 .Xr xli 1
  89 only to name some of them ...).  In
  90 .Em raw
  91 mode a
  92 bit which is set means a black pixel because the scanner detects black
  93 points on white paper.
  94 On the other hand, because pnm format describes
  95 intensities of electron beams in video screens a set bit in
  96 .Em pbm
  97 mode means a white pixel.
  98 .Pp
  99 The
 100 .Em width
 101 of the output bitmap is fixed as given by the
 102 resolution value.
 103 However, the
 104 .Em height
 105 of the bitmap must be
 106 supplied in
 107 .Em pnm
 108 mode since the driver must know at what time the
 109 .Sq end-of-file
 110 shall be reached.
 111 With this feature you are able to
 112 directly copy the scanner output into a pbm file with
 113 .Xr cat 1 .
 114 Of course you can obtain a similar effect by using
 115 .Xr dd 1
 116 with the driver in
 117 .Em raw
 118 mode.
 119 .Pp
 120 The
 121 .Em graymap
 122 output mode is not yet implemented into the driver.
 123 It is even questionable if external programs would not do this job
 124 better thereby not counting to the size of the kernel.
 125 Even though, I
 126 do not know of tools which produce a graymap from a halftone bitmap.
 127 .Pp
 128 The ioctl requests that are served by
 129 .Nm
 130 are listed below.
 131 There is a utility, called
 132 .Xr sgsc 1 ,
 133 that provides access to these
 134 requests from within shell.
 135 .Bl -tag -width Ds
 136 .It GSC_SRES int
 137 Set the
 138 .Em resolution
 139 value.
 140 If this call is made after the first
 141 read access to the device there will be no effect unless the device is
 142 closed and opened again.
 143 .It GSC_GRES int
 144 Get current resolution in dots per inch (dpi).
 145 .It GSC_SRESSSW void
 146 Set resolution value from selector switch.
 147 The driver must be in an
 148 open though untouched state otherwise the request will fail and
 149 .Xr errno 2
 150 is set to
 151 .Er EBUSY .
 152 .It GSC_SWIDTH int
 153 Set the
 154 .Em width
 155 of the bitmap.
 156 Actually, this is an alternative
 157 way of setting the resolution, since any allowed resolution matches
 158 exactly one width.
 159 Allowed are listed in the table below.
 160 .Bl -tag -width resolution -compact -offset indent
 161 .It resolution
 162 width
 163 .It 100 dpi
 164 424 pixels
 165 .It 200 dpi
 166 840 pixels
 167 .It 300 dpi
 168 1264 pixels
 169 .It 400 dpi
 170 1648 pixels
 171 .It ?
 172 1696 pixels
 173 .It ?
 174 2544 pixels
 175 .It ?
 176 3648 pixels
 177 .El
 178 .Pp
 179 Values which are not reported in the above table will cause the ioctl
 180 call to fail with
 181 .Xr errno 2
 182 set to
 183 .Er EINVAL .
 184 .Pp
 185 As you can see, there are width values > 1696.
 186 This does, however, not
 187 mean that you can obtain scanned lines longer than the width of your
 188 scanner or by higher resolutions.
 189 Actually, the resolution is selected
 190 by only by the hardware switch.
 191 Any line that is longer than what is
 192 defined for the actual resolution will be undefined (usually white) on
 193 the right part that is exceeding the standard line.
 194 .It GSC_GWIDTH int
 195 Get current width of the bitmap in pixels.
 196 .It GSC_SHEIGHT int
 197 Set the
 198 .Em height
 199 of the bitmap in
 200 .Em pnm
 201 mode.
 202 This is actually
 203 a limit on the amount of lines scannable after the first read
 204 operation.
 205 When the limit is reached read will return 0. However, the
 206 device is turned off only when a close is performed (either
 207 explicitly or implicitly on exit of the calling process).
 208 .It GSC_GHEIGHT int
 209 Get the current height of the bitmap.
 210 .It GSC_SBLEN int
 211 Set the length of the buffer used internally to do the DMA transfer.
 212 The buffer length is supplied in lines of the bitmap.
 213 Since the buffer
 214 size limit is (currently) 0x3000 bytes the maximum number of lines
 215 allowed will vary with the width of each line.
 216 This upper limit is
 217 checked before it overwrites the current value and passes an
 218 .Er ENOMEM
 219 in the
 220 .Xr errno 2
 221 variable.
 222 However, since the bitmap width can change
 223 after a buffer length was selected a read request may fail with
 224 .Er ENOMEM
 225 if the buffer length turns out too high.
 226 It is generally wise to
 227 choose long buffers rather than go save in order to obtain better
 228 output.
 229 .It GSC_GBLEN int
 230 Get the current buffer length in lines.
 231 .It GSC_SBTIME int
 232 Set the timeout for the completion of reading one buffer.
 233 Since a
 234 handy scanner is a human/computer interface timeout values are usually
 235 higher than those of a flat scanner.
 236 Default is 15 seconds.
 237 After
 238 timeout is reached the read operation will fail with
 239 .Er EBUSY .
 240 Note that
 241 the timeout timer starts anew for each buffer to be read and thus does
 242 not cause you to scan faster for longer images.
 243 BLEN/BTIME is similar
 244 as MIN/TIME in
 245 .Xr termios 4 .
 246 .It GSC_GBTIME int
 247 Get the current buffer timeout.
 248 .El
 249 .Pp
 250 All ioctl requests that modify a parameter except GSC_SBTIME do not
 251 have an effect on an ongoing scan process, i.e. after the first read
 252 request that follows open.
 253 You must close the device and open it again
 254 for the new selections to take effect.
 255 Consequently, the selections
 256 are not reset when you close or open the device.
 257 .Pp
 258 Similarly, requests that read a value do not report the value that is
 259 used for the ongoing scan process.
 260 The values needed during the scan
 261 process are saved when it starts and thus are not accessed by ioctl
 262 requests.
 263 .Pp
 264 The BTIME value does, however, have an immediate effect on the ongoing
 265 scan.
 266 Thus the timeout can for example be set to long until the user
 267 starts scanning.  It can then be set to a short amount to react
 268 (nearly) immediately when the user stops.
 269 Note that the user should be
 270 left time to at least fill one buffer without having to haste.
 271 .Pp
 272 Note that the
 273 .Em pbm
 274 versus
 275 .Em raw
 276 mode selection is done by the
 277 minor number not by ioctl requests.
 278 In
 279 .Em raw
 280 mode the selected
 281 height of the bitmap will have no effect.
 282 .Sh FILES
 283 .Bl -tag -width /dev/gsc0pd
 284 .It Pa /dev/gsc0
 285 device node for
 286 .Em raw
 287 output, has minor number 0.
 288 .It Pa /dev/gsc0d
 289 device node for
 290 .Em raw
 291 output emitting
 292 .Em debug
 293 messages if the
 294 GSCDEBUG option was given at compile time, has minor number 32.
 295 .It Pa /dev/gsc0p
 296 device node for output in
 297 .Em pbm
 298 file format, has minor number 8.
 299 .It Pa /dev/gsc0pd
 300 device node for
 301 .Em pbm
 302 and
 303 .Em debug
 304 mode, has minor number 40.
 305 .El
 306 .Sh EXAMPLES
 307 .Bd -literal -offset indent
 308 dd if=/dev/gsc0 of=rawfile bs=(width/8) count=(height)
 309
 310 cat /dev/gsc0p > pbmfile
 311 .Ed
 312 .Sh DIAGNOSTICS
 313 .Bl -tag -width Cd
 314 .It GSCDEBUG
 315 When you define this name as an `option' in the kernel configuration
 316 you can get debug output if you access the driver with a minor number
 317 whose debug bit (i.e. bit 5 out of 7) is set.
 318 .El
 319 .Sh SEE ALSO
 320 .Xr cat 1 ,
 321 .Xr dd 1 ,
 322 .Xr pbmtopgm 1 Pq Pa pkgsrc/graphics/netpbm ,
 323 .Xr sgsc 1 ,
 324 .Xr close 2 ,
 325 .Xr intro 2 ,
 326 .Xr ioctl 2 ,
 327 .Xr open 2 ,
 328 .Xr read 2 ,
 329 .Xr termios 4 ,
 330 .Xr pbm 5 Pq Pa pkgsrc/graphics/netpbm ,
 331 .Xr pnm 5 Pq Pa pkgsrc/graphics/netpbm
 332 .Sh AUTHORS
 333 .An Gunther Schadow Aq gusw@fub46.zedat.fu-berlin.de
 334 .Sh BUGS
 335 Even though the scanner device has a little switch by which you should
 336 be able to select one of the four resolution modes, I could not yet
 337 determine how to read its status.
 338 Unless this is not fixed the driver
 339 depends on the value passed by means of
 340 .Xr ioctl 2
 341 which need not match
 342 what is selected by the hardware.