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 Dv GSC_SRES Vt 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 Dv GSC_GRES Vt int
 144 Get current resolution in dots per inch (dpi).
 145 .It Dv GSC_SRESSW Vt 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 Dv GSC_SWIDTH Vt 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 Dv GSC_GWIDTH Vt int
 195 Get current width of the bitmap in pixels.
 196 .It Dv GSC_SHEIGHT Vt 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 Dv GSC_GHEIGHT Vt int
 209 Get the current height of the bitmap.
 210 .It Dv GSC_SBLEN Vt 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 Dv GSC_GBLEN Vt int
 230 Get the current buffer length in lines.
 231 .It Dv GSC_SBTIME Vt 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 Dv GSC_GBTIME Vt int
 247 Get the current buffer timeout.
 248 .El
 249 .Pp
 250 All ioctl requests that modify a parameter except
 251 .Dv GSC_SBTIME
 252 do not
 253 have an effect on an ongoing scan process, i.e. after the first read
 254 request that follows open.
 255 You must close the device and open it again
 256 for the new selections to take effect.
 257 Consequently, the selections
 258 are not reset when you close or open the device.
 259 .Pp
 260 Similarly, requests that read a value do not report the value that is
 261 used for the ongoing scan process.
 262 The values needed during the scan
 263 process are saved when it starts and thus are not accessed by ioctl
 264 requests.
 265 .Pp
 266 The BTIME value does, however, have an immediate effect on the ongoing
 267 scan.
 268 Thus the timeout can for example be set to long until the user
 269 starts scanning.  It can then be set to a short amount to react
 270 (nearly) immediately when the user stops.
 271 Note that the user should be
 272 left time to at least fill one buffer without having to haste.
 273 .Pp
 274 Note that the
 275 .Em pbm
 276 versus
 277 .Em raw
 278 mode selection is done by the
 279 minor number not by ioctl requests.
 280 In
 281 .Em raw
 282 mode the selected
 283 height of the bitmap will have no effect.
 284 .Sh FILES
 285 .Bl -tag -width /dev/gsc0pd
 286 .It Pa /dev/gsc0
 287 device node for
 288 .Em raw
 289 output, has minor number 0.
 290 .It Pa /dev/gsc0d
 291 device node for
 292 .Em raw
 293 output emitting
 294 .Em debug
 295 messages if the
 296 GSCDEBUG option was given at compile time, has minor number 32.
 297 .It Pa /dev/gsc0p
 298 device node for output in
 299 .Em pbm
 300 file format, has minor number 8.
 301 .It Pa /dev/gsc0pd
 302 device node for
 303 .Em pbm
 304 and
 305 .Em debug
 306 mode, has minor number 40.
 307 .El
 308 .Sh EXAMPLES
 309 .Bd -literal -offset indent
 310 dd if=/dev/gsc0 of=rawfile bs=(width/8) count=(height)
 311
 312 cat /dev/gsc0p > pbmfile
 313 .Ed
 314 .Sh DIAGNOSTICS
 315 .Bl -tag -width Cd
 316 .It GSCDEBUG
 317 When you define this name as an `option' in the kernel configuration
 318 you can get debug output if you access the driver with a minor number
 319 whose debug bit (i.e. bit 5 out of 7) is set.
 320 .El
 321 .Sh SEE ALSO
 322 .Xr cat 1 ,
 323 .Xr dd 1 ,
 324 .Xr pbmtopgm 1 Pq Pa pkgsrc/graphics/netpbm ,
 325 .Xr sgsc 1 ,
 326 .Xr close 2 ,
 327 .Xr intro 2 ,
 328 .Xr ioctl 2 ,
 329 .Xr open 2 ,
 330 .Xr read 2 ,
 331 .Xr termios 4 ,
 332 .Xr pbm 5 Pq Pa pkgsrc/graphics/netpbm ,
 333 .Xr pnm 5 Pq Pa pkgsrc/graphics/netpbm
 334 .Sh AUTHORS
 335 .An Gunther Schadow Aq gusw@fub46.zedat.fu-berlin.de
 336 .Sh BUGS
 337 Even though the scanner device has a little switch by which you should
 338 be able to select one of the four resolution modes, I could not yet
 339 determine how to read its status.
 340 Unless this is not fixed the driver
 341 depends on the value passed by means of
 342 .Xr ioctl 2
 343 which need not match
 344 what is selected by the hardware.