freebsd-dev/share/man/man4/man4.i386/asc.4

180 lines
7.4 KiB
Groff
Raw Normal View History

.\" 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>