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