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.4 2007/05/17 08:19:01 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 (
  87 .Xr xpaint 1 ,
  88 .Xr xv 1 ,
  89 .Xr xli 1
  90 only to name some of them ...).  In
  91 .Em raw
  92 mode a
  93 bit which is set means a black pixel because the scanner detects black
  94 points on white paper.
  95 On the other hand, because pnm format describes
  96 intensities of electron beams in video screens a set bit in
  97 .Em pbm
  98 mode means a white pixel.
  99 .Pp
 100 The
 101 .Em width
 102 of the output bitmap is fixed as given by the
 103 resolution value.
 104 However, the
 105 .Em height
 106 of the bitmap must be
 107 supplied in
 108 .Em pnm
 109 mode since the driver must know at what time the
 110 .Sq end-of-file
 111 shall be reached.
 112 With this feature you are able to
 113 directly copy the scanner output into a pbm file with
 114 .Xr cat 1 .
 115 Of course you can obtain a similar effect by using
 116 .Xr dd 1
 117 with the driver in
 118 .Em raw
 119 mode.
 120 .Pp
 121 The
 122 .Em graymap
 123 output mode is not yet implemented into the driver.
 124 It is even questionable if external programs would not do this job
 125 better thereby not counting to the size of the kernel.
 126 Even though, I
 127 do not know of tools which produce a graymap from a halftone bitmap.
 128 .Pp
 129 The ioctl requests that are served by
 130 .Nm
 131 are listed below.
 132 There is a utility, called
 133 .Xr sgsc 1 ,
 134 that provides access to these
 135 requests from within shell.
 136 .Bl -tag -width Ds
 137 .It GSC_SRES int
 138 Set the
 139 .Em resolution
 140 value.
 141 If this call is made after the first
 142 read access to the device there will be no effect unless the device is
 143 closed and opened again.
 144 .It GSC_GRES int
 145 Get current resolution in dots per inch (dpi).
 146 .It GSC_SRESSSW void
 147 Set resolution value from selector switch.
 148 The driver must be in an
 149 open though untouched state otherwise the request will fail and
 150 .Xr errno 2
 151 is set to
 152 .Er EBUSY .
 153 .It GSC_SWIDTH int
 154 Set the
 155 .Em width
 156 of the bitmap.
 157 Actually, this is an alternative
 158 way of setting the resolution, since any allowed resolution matches
 159 exactly one width.
 160 Allowed are listed in the table below.
 161 .Bl -tag -width resolution -compact -offset indent
 162 .It resolution
 163 width
 164 .It 100 dpi
 165 424 pixels
 166 .It 200 dpi
 167 840 pixels
 168 .It 300 dpi
 169 1264 pixels
 170 .It 400 dpi
 171 1648 pixels
 172 .It ?
 173 1696 pixels
 174 .It ?
 175 2544 pixels
 176 .It ?
 177 3648 pixels
 178 .El
 179 .Pp
 180 Values which are not reported in the above table will cause the ioctl
 181 call to fail with
 182 .Xr errno 2
 183 set to
 184 .Er EINVAL .
 185 .Pp
 186 As you can see, there are width values > 1696.
 187 This does, however, not
 188 mean that you can obtain scanned lines longer than the width of your
 189 scanner or by higher resolutions.
 190 Actually, the resolution is selected
 191 by only by the hardware switch.
 192 Any line that is longer than what is
 193 defined for the actual resolution will be undefined (usually white) on
 194 the right part that is exceeding the standard line.
 195 .It GSC_GWIDTH int
 196 Get current width of the bitmap in pixels.
 197 .It GSC_SHEIGHT int
 198 Set the
 199 .Em height
 200 of the bitmap in
 201 .Em pnm
 202 mode.
 203 This is actually
 204 a limit on the amount of lines scannable after the first read
 205 operation.
 206 When the limit is reached read will return 0. However, the
 207 device is turned off only when a close is performed (either
 208 explicitly or implicitly on exit of the calling process).
 209 .It GSC_GHEIGHT int
 210 Get the current height of the bitmap.
 211 .It GSC_SBLEN int
 212 Set the length of the buffer used internally to do the DMA transfer.
 213 The buffer length is supplied in lines of the bitmap.
 214 Since the buffer
 215 size limit is (currently) 0x3000 bytes the maximum number of lines
 216 allowed will vary with the width of each line.
 217 This upper limit is
 218 checked before it overwrites the current value and passes an
 219 .Er ENOMEM
 220 in the
 221 .Xr errno 2
 222 variable.
 223 However, since the bitmap width can change
 224 after a buffer length was selected a read request may fail with
 225 .Er ENOMEM
 226 if the buffer length turns out too high.
 227 It is generally wise to
 228 choose long buffers rather than go save in order to obtain better
 229 output.
 230 .It GSC_GBLEN int
 231 Get the current buffer length in lines.
 232 .It GSC_SBTIME int
 233 Set the timeout for the completion of reading one buffer.
 234 Since a
 235 handy scanner is a human/computer interface timeout values are usually
 236 higher than those of a flat scanner.
 237 Default is 15 seconds.
 238 After
 239 timeout is reached the read operation will fail with
 240 .Er EBUSY .
 241 Note that
 242 the timeout timer starts anew for each buffer to be read and thus does
 243 not cause you to scan faster for longer images.
 244 BLEN/BTIME is similar
 245 as MIN/TIME in
 246 .Xr termios 4 .
 247 .It GSC_GBTIME int
 248 Get the current buffer timeout.
 249 .El
 250 .Pp
 251 All ioctl requests that modify a parameter except GSC_SBTIME 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 ,
 324 .Xr pnm 1 ,
 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
 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.