Submitted by: -Luigi Rizzo (luigi@iet.unipi.it)

Obtained from:  Luigi Rizzo and Gunther Schadow
man page for the asc scanner driver

2 files changed, 183 insertions, 3 deletions

diff --git a/share/man/man4/man4.i386/Makefile b/share/man/man4/man4.i386/Makefile
index 6a82292..861c537 100644
--- a/share/man/man4/man4.i386/Makefile
+++ b/share/man/man4/man4.i386/Makefile
@@ -1,13 +1,14 @@
 #	@(#)Makefile	0.1 (RWGrimes) 3/25/93
 
-MAN4=   aha.4 ahb.4 ahc.4 apm.4 bt.4 cx.4 ed.4 fdc.4 fe.4 ie.4 is.4 joy.4 \
-	keyboard.4 lpt.4 matcd.4 mcd.4 mem.4 meteor.4 mse.4 npx.4 pcvt.4 \
-	screen.4 sio.4 spkr.4 tw.4 uha.4 wd.4
+MAN4=   aha.4 ahb.4 ahc.4 apm.4 asc.4 bt.4 cx.4 ed.4 fdc.4 fe.4 ie.4 \
+	is.4 joy.4 keyboard.4 lpt.4 matcd.4 mcd.4 mem.4 meteor.4 \
+	mse.4 npx.4 pcvt.4 screen.4 sio.4 spkr.4 tw.4 uha.4 wd.4
 
 MLINKS=		aha.4 ../aha.4
 MLINKS+=	ahb.4 ../ahb.4
 MLINKS+=	ahc.4 ../ahc.4
 MLINKS+=	apm.4 ../apm.4
+MLINKS+=	asc.4 ../asc.4
 MLINKS+=	bt.4 ../bt.4
 MLINKS+=	cx.4 ../cx.4
 MLINKS+=	ed.4 ../ed.4
diff --git a/share/man/man4/man4.i386/asc.4 b/share/man/man4/man4.i386/asc.4
new file mode 100644
index 0000000..fc187f3
--- /dev/null
+++ b/share/man/man4/man4.i386/asc.4
@@ -0,0 +1,179 @@
+.\" asc(4) - manual page for the scanner device driver `asc'
+.\"
+.\"
+.\" Copyright (c) 1995 Gunther Schadow, Luigi Rizzo. 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 acknowledgements:
+.\"	This product includes software developed by Gunther Schadow.
+.\"	This product includes software developed by Luigi Rizzo.
+.\" 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.
+.TH ASC 4 "January 6, 1995" FreeBSD "FreeBSD Programmer's Manual"
+.SH NAME
+\fBasc\fP - a device driver for a handy scanner
+.SH SYNOPSIS
+.TP
+\fB#include <machine/asc_ioctl.h>\fP
+.TP
+\fBMinor number bits:\fP \fIuu d g p ...\fP
+\fIuu\fP - unit asc0 .. asc3
+\fI d\fP - selects logging of \fIdebug\fP messages
+\fI g\fP - selects \fIbitmap\fP vs. \fIgraymap\fP output
+\fI p\fP - selects \fIraw\fP vs. portable \fIpnm\fP output
+.TP
+\fBdd if=/dev/asc0 of=rawfile bs=(width/8) count=(height)
+.TP
+\fBcat /dev/asc0p > pbmfile\fP
+.PB
+.SH DESCRIPTION
+The \fBasc\fP character device driver currently handles the
+GI1904-based hand scanner (e.g. Trust Amiscan Grey).
+It uses DMA and interrupts. Input data from the scanner are
+buffered, up to 50 scanlines are buffered in the driver.
+.PP
+The device can operate at four different \fIresolutions\fP: 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 pbm(5) by Jef
+Poskanzer. Thus the scans can easily processed by any graphic package
+around (xpaint, xv, xli only to name some of them ...).
+.PP
+The \fIwidth\fP of the output bitmap is fixed as given by the
+resolution value. However, the \fIheight\fP of the bitmap must be
+supplied in \fIpnm\fP mode since the driver must know at what time the
+'end-of-file' shall be reached. The default is to produce a
+square image, i.e. \fIheight=width\fP. With this feature you are able to
+directly copy the scanner output into a pbm file whith cat(1).  Of
+course you can obtain a similar effect by using dd(1) with the driver
+in \fIraw\fP mode.
+.PP
+The \fIgraymap\fP 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.
+.SH IOCTL REQUESTS
+The ioctl requests that are served by \fBasc\fP are listed below.
+There is a utility, called sasc(1), that provides access to these
+requests from within shell.
+.TP
+ASC_GRES int
+Get current resolution in dots per inch (dpi).
+.TP
+ASC_GWIDTH int
+Get current width of the bitmap in pixels.
+.TP
+ASC_SHEIGHT int
+Set the \fIheight\fP of the bitmap in \fIpnm\fP 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).
+.TP
+ASC_GHEIGHT int
+Get the current height of the bitmap.
+.TP
+ASC_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 \fBerrno\fP 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.
+.TP
+ASC_GBLEN int
+Get the current buffer length in lines.
+.TP
+ASC_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).
+.TP
+ASC_GBTIME int
+Get the current buffer timeout.
+.PP
+All ioctl requests that modify a parameter except ASC_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 \fIpbm\fP versus \fIraw\fP mode selection is done by the
+minor number not by ioctl requests. In \fIraw\fP mode the selected
+height of the bitmap will have no effect.
+.SH FILES
+.TP 15
+.BI /dev/asc0
+device node for \fIraw\fP output, has minor number 0.
+.TP
+.BI /dev/asc0d
+device node for \fIraw\fP output emiting \fIdebug\fP messages if the
+ASCDEBUG option was given at compile time, has minor number 32.
+.TP
+.BI /dev/asc0p
+device node for output in \fIpbm\fP file format, has minor number 8.
+.TP
+.BI /dev/asc0pd
+device node for \fIpbm\fP and \fIdebug\fP mode, has minor number 40.
+.PB
+.SH DIAGNOSTICS
+.TP
+\fBASCDEBUG\fP
+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.
+.SH SEE ALSO
+.nh
+open(2),
+ioctl(2),
+intro(2),
+read(2),
+close(2),
+cat(1),
+dd(1),
+pbm(5),
+pnm(1),
+termios(4).
+.hy
+.SH BUGS
+Ioctl support is not working yet.
+.SH AUTHOR
+Luigi Rizzo <luigi.rizzo@iet.unipi.it>