[dragonfly.git] / share / man / man4 / man4.i386 / asc.4

.\" 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.
.\"
.\" $FreeBSD: src/share/man/man4/man4.i386/asc.4,v 1.14.2.2 2001/08/17 13:08:45 ru Exp $
.\" $DragonFly: src/share/man/man4/man4.i386/asc.4,v 1.5 2008/01/26 15:14:41 swildner Exp $
.Dd January 19, 1995
.Dt ASC 4 i386
.Os
.Sh NAME
.Nm asc
.Nd device driver for a GI1904-based hand scanner
.Sh SYNOPSIS
.Cd "device asc0 at isa? port IO_ASC1 drq 3 irq 10"
.Sh DESCRIPTION
The
.Nm
character device driver currently handles the
.Tn GI1904 Ns -based
hand scanner (e.g. Trust Amiscan Grey).
It uses DMA and interrupts.
Up to 50 lines of scanned input data are buffered in the driver.
.Pp
The device can operate at four different resolutions: 100, 200, 300
and 400 dots per inch.
It produces a simple bitmap with the most
significant bit at the left side.  The driver can optionally output
the simple portable bitmap file format
.Xr pbm 5 ;
thus the scans can easily processed by most graphics packages.
.Pp
The width of the output bitmap is fixed as given by the
resolution value.  However, the height of the bitmap must be
supplied when in
.Xr pbm 5
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., height equals width.
With this feature one is able to
directly copy the scanner output into a
.Xr pbm 5
file using
.Xr cat 1 .
One can obtain a similar effect by using
.Xr dd 1
with the driver
in raw mode.
.Sh IOCTLS
The
.Xr ioctl 2
commands applicable to
.Nm
are listed below.
The
.Xr sasc 1
provides user-level access to these commands.
.Bl -tag -width ".Dv ASC_GHEIGHT"
.It Dv ASC_GRES
.Pq Li int
Get current resolution in dots per inch (dpi).
.It Dv ASC_GWIDTH
.Pq Li int
Get current width of the bitmap in pixels.
.It Dv ASC_SHEIGHT
.Pq Li int
Set the height of the bitmap in
.Xr pbm 5
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 the last open file descriptor is closed.
.It Dv ASC_GHEIGHT
.Pq Li int
Get the current height of the bitmap.
.It Dv ASC_SBLEN
.Pq Li 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.  An
.Er ENOMEM
error is returned if the requested length would exceed this limit.
.It Dv ASC_GBLEN
.Pq Li int
Get the current buffer length in lines.
.It Dv ASC_SBTIME
.Pq Li 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; the default is 15 seconds.  After
timeout is reached the read operation will fail with
.Er EBUSY .
Note that
the timeout timer starts anew for each buffer to be read and thus
reducing it does not result in faster scans for longer images.
.It Dv ASC_GBTIME
.Pq Li int
Get the current buffer timeout.
.El
.Pp
All
.Fn ioctl
requests that modify a parameter except
.Dv ASC_SBTIME
do not have an effect on an ongoing scan process.  The user must close
the device and open it again for the new selections to take effect.
Consequently, the selections are
.Em not
reset when the device is opened or closed.
.Pp
Similarly, 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
.Fn ioctl
requests.
.Pp
The
.Dv ASC_SBTIME
value does, however, have an immediate effect on the ongoing scan.
Thus the timeout can, for example, be set to a large value until the
user starts scanning, and then set to a small value to react
(nearly) immediately when the user stops.
.Pp
Note that the
.Xr pbm 5
versus raw mode selection is done by the
minor number, not by
.Fn ioctl
requests.  In raw mode, the selected
height of the bitmap will have no effect.
.Sh FILES
.Bl -tag -width /dev/asc0pd -compact
.It Pa /dev/asc0
device node for raw output
.It Pa /dev/asc0d
device node for raw output, emitting debug messages if the
.Dv ASCDEBUG
option was given in the kernel configuration file
.It Pa /dev/asc0p
device node for output in
.Xr pbm 5
file format
.It Pa /dev/asc0pd
device node for
.Xr pbm 5
and debug mode
.El
.\"
.\" .Sh DIAGNOSTICS
.\"
.Sh SEE ALSO
.Xr sasc 1 ,
.Xr pbm 5 Pq Pa pkgsrc/graphics/netpbm
.Sh HISTORY
The
.Nm
driver first appeared in
.Fx 2.1 .
.Sh AUTHORS
The
.Nm
driver was written by
.An Luigi Rizzo .
.Sh BUGS
Ioctl support is not working yet.
Commit	Line	Data
984263bc MD	1	.\" asc(4) - manual page for the scanner device driver `asc'
	2	.\"
	3	.\"
	4	.\" Copyright (c) 1995 Gunther Schadow, Luigi Rizzo. 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 acknowledgements:
	16	.\" This product includes software developed by Gunther Schadow.
	17	.\" This product includes software developed by Luigi Rizzo.
	18	.\" 4. The name of the author may not be used to endorse or promote products
	19	.\" derived from this software without specific prior written permission.
	20	.\"
	21	.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
	22	.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
	23	.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
	24	.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
	25	.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
	26	.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
	27	.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
	28	.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
	29	.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
	30	.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
	31	.\"
	32	.\" $FreeBSD: src/share/man/man4/man4.i386/asc.4,v 1.14.2.2 2001/08/17 13:08:45 ru Exp $
7cd7d057	33	.\" $DragonFly: src/share/man/man4/man4.i386/asc.4,v 1.5 2008/01/26 15:14:41 swildner Exp $
984263bc MD	34	.Dd January 19, 1995
	35	.Dt ASC 4 i386
	36	.Os
	37	.Sh NAME
	38	.Nm asc
	39	.Nd device driver for a GI1904-based hand scanner
	40	.Sh SYNOPSIS
	41	.Cd "device asc0 at isa? port IO_ASC1 drq 3 irq 10"
	42	.Sh DESCRIPTION
	43	The
	44	.Nm
	45	character device driver currently handles the
	46	.Tn GI1904 Ns -based
	47	hand scanner (e.g. Trust Amiscan Grey).
	48	It uses DMA and interrupts.
	49	Up to 50 lines of scanned input data are buffered in the driver.
	50	.Pp
	51	The device can operate at four different resolutions: 100, 200, 300
	52	and 400 dots per inch.
	53	It produces a simple bitmap with the most
	54	significant bit at the left side. The driver can optionally output
	55	the simple portable bitmap file format
	56	.Xr pbm 5 ;
	57	thus the scans can easily processed by most graphics packages.
	58	.Pp
	59	The width of the output bitmap is fixed as given by the
	60	resolution value. However, the height of the bitmap must be
	61	supplied when in
	62	.Xr pbm 5
	63	mode, since the driver must know at what time the
	64	`end-of-file' shall be reached. The default is to produce a
	65	square image; i.e., height equals width.
	66	With this feature one is able to
	67	directly copy the scanner output into a
	68	.Xr pbm 5
	69	file using
	70	.Xr cat 1 .
	71	One can obtain a similar effect by using
	72	.Xr dd 1
	73	with the driver
	74	in raw mode.
	75	.Sh IOCTLS
	76	The
	77	.Xr ioctl 2
	78	commands applicable to
	79	.Nm
	80	are listed below.
	81	The
	82	.Xr sasc 1
	83	provides user-level access to these commands.
291ffd2f	84	.Bl -tag -width ".Dv ASC_GHEIGHT"
984263bc MD	85	.It Dv ASC_GRES
	86	.Pq Li int
	87	Get current resolution in dots per inch (dpi).
	88	.It Dv ASC_GWIDTH
	89	.Pq Li int
	90	Get current width of the bitmap in pixels.
	91	.It Dv ASC_SHEIGHT
	92	.Pq Li int
	93	Set the height of the bitmap in
	94	.Xr pbm 5
	95	mode. This is actually
	96	a limit on the amount of lines scannable after the first read
	97	operation. When the limit is reached, read will return 0. However, the
	98	device is turned off only when the last open file descriptor is closed.
	99	.It Dv ASC_GHEIGHT
	100	.Pq Li int
	101	Get the current height of the bitmap.
	102	.It Dv ASC_SBLEN
	103	.Pq Li int
	104	Set the length of the buffer used internally to do the DMA transfer.
	105	The buffer length is supplied in lines of the bitmap.
	106	Since the buffer
	107	size limit is (currently) 0x3000 bytes, the maximum number of lines
	108	allowed will vary with the width of each line. An
	109	.Er ENOMEM
	110	error is returned if the requested length would exceed this limit.
	111	.It Dv ASC_GBLEN
	112	.Pq Li int
	113	Get the current buffer length in lines.
	114	.It Dv ASC_SBTIME
	115	.Pq Li int
	116	Set the timeout for the completion of reading one buffer.
	117	Since a
	118	handy scanner is a human/computer interface timeout values are usually
	119	higher than those of a flat scanner; the default is 15 seconds. After
	120	timeout is reached the read operation will fail with
	121	.Er EBUSY .
	122	Note that
	123	the timeout timer starts anew for each buffer to be read and thus
	124	reducing it does not result in faster scans for longer images.
	125	.It Dv ASC_GBTIME
	126	.Pq Li int
	127	Get the current buffer timeout.
	128	.El
	129	.Pp
	130	All
	131	.Fn ioctl
	132	requests that modify a parameter except
	133	.Dv ASC_SBTIME
	134	do not have an effect on an ongoing scan process. The user must close
	135	the device and open it again for the new selections to take effect.
	136	Consequently, the selections are
	137	.Em not
	138	reset when the device is opened or closed.
	139	.Pp
	140	Similarly, requests that read a value do not report the value that is
	141	used for the ongoing scan process. The values needed during the scan
	142	process are saved when it starts and thus are not accessed by
	143	.Fn ioctl
	144	requests.
	145	.Pp
	146	The
	147	.Dv ASC_SBTIME
	148	value does, however, have an immediate effect on the ongoing scan.
149	Thus the timeout can, for example, be set to a large value until the
150	user starts scanning, and then set to a small value to react
151	(nearly) immediately when the user stops.
152	.Pp
153	Note that the
154	.Xr pbm 5
155	versus raw mode selection is done by the
156	minor number, not by
157	.Fn ioctl
158	requests. In raw mode, the selected
159	height of the bitmap will have no effect.
160	.Sh FILES
161	.Bl -tag -width /dev/asc0pd -compact
162	.It Pa /dev/asc0
163	device node for raw output
164	.It Pa /dev/asc0d
165	device node for raw output, emitting debug messages if the
166	.Dv ASCDEBUG
167	option was given in the kernel configuration file
168	.It Pa /dev/asc0p
169	device node for output in
170	.Xr pbm 5
171	file format
172	.It Pa /dev/asc0pd
173	device node for
174	.Xr pbm 5
175	and debug mode
176	.El
177	.\"
178	.\" .Sh DIAGNOSTICS
179	.\"
180	.Sh SEE ALSO
181	.Xr sasc 1 ,
7cd7d057	182	.Xr pbm 5 Pq Pa pkgsrc/graphics/netpbm
984263bc MD	183	.Sh HISTORY
	184	The
	185	.Nm
	186	driver first appeared in
	187	.Fx 2.1 .
ac561d34 SW	188	.Sh AUTHORS
	189	The
	190	.Nm
	191	driver was written by
	192	.An Luigi Rizzo .
	193	.Sh BUGS
	194	Ioctl support is not working yet.