Added missing gsc(4) (Genius scanner related man page).

2 files changed, 298 insertions, 2 deletions

diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile
index 54a862d..bc3e84e 100644
--- a/share/man/man4/Makefile
+++ b/share/man/man4/Makefile
@@ -1,7 +1,7 @@
 #	@(#)Makefile	8.1 (Berkeley) 6/18/93
 
-MAN4=	bpf.4 cd.4 ch.4 clnp.4 cltp.4 ddb.4 drum.4 esis.4 fd.4 fpa.4 icmp.4 \
-	idp.4 inet.4 intro.4 ip.4 ipfirewall.4 iso.4 \
+MAN4=	bpf.4 cd.4 ch.4 clnp.4 cltp.4 ddb.4 drum.4 esis.4 fd.4 fpa.4 gsc.4 \
+	icmp.4 idp.4 inet.4 intro.4 ip.4 ipfirewall.4 iso.4 \
 	lkm.4 lo.4 netintro.4 ns.4 \
 	nsip.4 null.4 pt.4 pty.4 route.4 \
 	scsi.4 sd.4 snp.4 spp.4 st.4 su.4 tcp.4 \
diff --git a/share/man/man4/gsc.4 b/share/man/man4/gsc.4
new file mode 100644
index 0000000..d1f93e4
--- /dev/null
+++ b/share/man/man4/gsc.4
@@ -0,0 +1,296 @@
+.\" gsc.4 - manual page for the scanner device driver `gsc'
+.\"
+.\"
+.\" Copyright (c) 1995 Gunther Schadow.  All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"	This product includes software developed by Gunther Schadow.
+.\" 4. The name of the author may not be used to endorse or promote products
+.\"    derived from this software without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+.Dd January 9, 1995
+.Os FreeBSD
+.Dt GSC 4
+.Sh NAME
+.Nm gsc
+.Nd a device driver for a handy scanner
+.Sh SYNOPSIS
+.Fd #include <machine/gsc.h>
+.sp
+.Cd Minor number bits: Ar uu d g p ...
+.Bl -tag -width "uu " -compact -offset indent
+.It Ar uu
+unit gsc0 .. gsc3
+.It Ar d
+selects logging of
+.Em debug
+messages
+.It Ar g
+selects
+.Em bitmap
+vs.
+.Em graymap
+output
+.It Ar p
+selects
+.Em raw
+vs. portable
+.Em pnm
+output
+.El
+.sp
+.Sh DESCRIPTION
+The
+.Nm gsc
+character device driver currently handles only the
+Genius GS-4500 handy scanner. It operates in pure dma modus, although
+the hardware could be set up to work with irq. I had neither enough
+documentation nor experience in writing interrupt driven device
+drivers.
+.Pp
+The device can operate at four different 
+.Em resolutions :
+100, 200,
+300 and 400dpi. It produces a simple bitmap with the most significant
+bit at the left side. The driver can optionally output the famous and
+likely simple portable bitmap file format
+.Xr pbm 5
+by Jef Poskanzer.
+Thus the scans can easily processed by any graphic package around
+(
+.Xr xpaint 1 ,
+.Xr xv 1 ,
+.Xr xli 1
+only to name some of them ...).  In 
+.Em raw
+mode a
+bit which is set means a black pixel because the scanner detects black
+points on white paper. On the other hand, because pnm format describes
+intensities of electron beams in video screens a set bit in 
+.Em pbm
+mode means a white pixel.
+.Pp
+The 
+.Em width
+of the output bitmap is fixed as given by the
+resolution value. However, the 
+.Em height
+of the bitmap must be
+supplied in 
+.Em pnm
+mode since the driver must know at what time the
+'end-of-file' shall be reached. With this feature you are able to
+directly copy the scanner output into a pbm file whith
+.Xr cat .
+Of course you can obtain a similar effect by using
+.Xr dd 1
+with the driver in 
+.Em raw
+mode.
+.Pp
+The 
+.Em graymap
+output mode is not yet implemented into the driver.
+It is even questionable if external programs would not do this job
+better thereby not counting to the size of the kernel. Even though, I
+do not know of tools which produce a graymap from a halftone bitmap.
+.Pp
+The ioctl requests that are served by
+.Nm gsc
+are listed below.
+There is a utility, called sgsc(1), that provides access to these
+requests from within shell.
+.Bl -tag -width Ds
+.It GSC_SRES int
+Set the
+.Em resolution
+value. If this call is made after the first
+read access to the device there will be no effect unless the device is
+closed and opened again.
+.It GSC_GRES int
+Get current resolution in dots per inch (dpi).
+.It GSC_SRESSSW void
+Set resolution value from selector switch. The driver must be in an
+open though untouched state otherwise the request will fail and
+.Xr errno 2
+is set to EBUSY.
+.It GSC_SWIDTH int
+Set the 
+.Em width
+of the bitmap. Actually, this is an alternative
+way of setting the resolution, since any allowed resolution matches
+exactly one width. Allowed are listed in the table below.
+.Bl -tag -width resolution -compact -offset indent
+.It resolution
+width
+.It 100 dpi
+424 pixels
+.It 200 dpi
+840 pixels
+.It 300 dpi
+1264 pixels
+.It 400 dpi
+1648 pixels
+.It ?
+1696 pixels
+.It ?
+2544 pixels
+.It ?
+3648 pixels
+.El
+.Pp
+Values which are not reported in the above table will cause the ioctl
+call to fail with 
+.Xr errno 2
+set to EINVAL.
+.sp
+As you can see, there are width values > 1696. This does, however, not
+mean that you can obtain scanned lines longer than the width of your
+scanner or by higher resolutions. Actually, the resolution is selected
+by only by the hardware switch. Any line that is longer than what is
+defined for the actual resolution will be undefined (usually white) on
+the right part that is exceeding the standard line.
+.It GSC_GWIDTH int
+Get current width of the bitmap in pixels.
+.It GSC_SHEIGHT int
+Set the 
+.Em height
+of the bitmap in 
+.Em pnm
+mode. This is actually
+a limit on the amount of lines scannable after the first read
+operation. When the limit is reached read will return 0. However, the
+device is turned off only when a close is performed (either
+explicitely or implicitely on exit of the calling process).
+.It GSC_GHEIGHT int
+Get the current height of the bitmap.
+.It GSC_SBLEN int
+Set the length of the buffer used internally to do the DMA transfer.
+The buffer length is supplied in lines of the bitmap. Since the buffer
+size limit is (currently) 0x3000 bytes the maximum number of lines
+allowed will vary with the width of each line. This upper limit is
+checked before it overwrites the current value and pases an ENOMEM in
+the
+.Xr errno 2 
+variable. However, since the bitmap width can change
+after a buffer length was selected a read request may fail with ENOMEM
+if the buffer length turns out too high. It is generally wise to
+choose long buffers rather than go save in order to obtain better
+output.
+.It GSC_GBLEN int
+Get the current buffer length in lines.
+.It GSC_SBTIME int
+Set the timeout for the completion of reading one buffer. Since a
+handy scanner is a human/computer interface timeout values are usually
+higher than those of a flat scanner. Default is 15 seconds. After
+timeout is reached the read operation will fail with EBUSY. Note that
+the timeout timer starts anew for each buffer to be read and thus does
+not cause you to scan faster for longer images. BLEN/BTIME is similar
+as MIN/TIME in termios(4).
+.It GSC_GBTIME int
+Get the current buffer timeout.
+.El
+.Pp
+All ioctl requests that modify a parameter except GSC_SBTIME do not
+have an effect on an ongoing scan process, i.e. after the first read
+request that follows open. You must close the device and open it again
+for the new selections to take effect. Consequently, the selections
+are not reset when you close or open the device.
+.Pp
+Similarily, requests that read a value do not report the value that is
+used for the ongoing scan process. The values needed during the scan
+process are saved when it starts and thus are not accessed by ioctl
+requests.
+.Pp
+The BTIME value does, however, have an immediate effect on the ongoing
+scan. Thus the timeout can for example be set to long until the user
+starts scanning.  It can then be set to a short amount to react
+(nearly) immediately when the user stops. Note that the user should be
+left time to at least fill one buffer without having to haste.
+.Pp
+Note that the 
+.Em pbm
+versus 
+.Em raw
+mode selection is done by the
+minor number not by ioctl requests. In 
+.Em raw
+mode the selected
+height of the bitmap will have no effect.
+.Sh FILES
+.Bl -tag -width /dev/gsc0pd
+.It Pa /dev/gsc0
+device node for 
+.Em raw
+output, has minor number 0.
+.It Pa /dev/gsc0d
+device node for 
+.Em raw
+output emiting 
+.Em debug
+messages if the
+GSCDEBUG option was given at compile time, has minor number 32.
+.It Pa /dev/gsc0p
+device node for output in 
+.Em pbm
+file format, has minor number 8.
+.It Pa /dev/gsc0pd
+device node for 
+.Em pbm
+and 
+.Em debug
+mode, has minor number 40.
+.PB
+.Sh EXAMPLES
+.Bd -literal -offset indent
+dd if=/dev/gsc0 of=rawfile bs=(width/8) count=(height)
+
+cat /dev/gsc0p > pbmfile
+.Ed
+.Sh DIAGNOSTICS
+.Bl -tag
+.It GSCDEBUG
+When you define this name as an `option' in the kernel configuration
+you can get debug output if you access the driver with a minor number
+whose debug bit (i.e. bit 5 out of 7) is set.
+.El
+.Sh SEE ALSO
+.Xr sgsc 1 ,
+.Xr open 2 ,
+.Xr ioctl 2 ,
+.Xr intro 2 ,
+.Xr read 2 ,
+.Xr close 2 ,
+.Xr cat 1 ,
+.Xr dd 1 ,
+.Xr pbm 5 ,
+.Xr pnm 1 ,
+.Xr pbmtopgm 1 ,
+.Xr termios 4
+.Sh AUTHORS
+Gunther Schadow <gusw@fub46.zedat.fu-berlin.de>
+.Sh BUGS
+Even though the scanner device has a little switch by which you should
+be able to select one of the four resolution modes, I could not yet
+determine how to read it's status. Unless this is not fixed the driver
+depends on the value passed by means of ioctl(2) which need not match
+what is selected by the hardware.