ASC(4)

NAME
asc - a device driver for a handy scanner

SYNOPSIS

#include <machine/asc_ioctl.h>

Minor number bits: uu d g p ...
    uu - unit asc0 .. asc3 d - selects logging of debug messages g - selects bitmap vs. graymap output p - selects raw vs. portable pnm output

dd if=/dev/asc0 of=rawfile bs=(width/8) count=(height)

cat /dev/asc0p > pbmfile

DESCRIPTION
The asc 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.

The device can operate at four different 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 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 ...).

The width of the output bitmap is fixed as given by the resolution value. However, the height of the bitmap must be supplied in pnm mode since the driver must know at what time the square image, i.e. height=width. 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 raw mode.

The 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.

IOCTL REQUESTS
The ioctl requests that are served by asc are listed below. There is a utility, called sasc(1), that provides access to these requests from within shell.

ASC_GRES int
    Get current resolution in dots per inch (dpi).

ASC_GWIDTH int
    Get current width of the bitmap in pixels.

ASC_SHEIGHT int
    Set the height of the bitmap in 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).

ASC_GHEIGHT int
    Get the current height of the bitmap.

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 errno 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.

ASC_GBLEN int
    Get the current buffer length in lines.

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).

ASC_GBTIME int
    Get the current buffer timeout.

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.

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.

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.

Note that the pbm versus raw mode selection is done by the minor number not by ioctl requests. In raw mode the selected height of the bitmap will have no effect.

FILES

/dev/asc0
    device node for raw output, has minor number 0.

/dev/asc0d
    device node for raw output emiting debug messages if the ASCDEBUG option was given at compile time, has minor number 32.

/dev/asc0p
    device node for output in pbm file format, has minor number 8.

/dev/asc0pd
    device node for pbm and debug mode, has minor number 40.

DIAGNOSTICS

ASCDEBUG
    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.

SEE ALSO
open(2), ioctl(2), intro(2), read(2), close(2), cat(1), dd(1), pbm(5), pnm(1), termios(4).

BUGS
Ioctl support is not working yet.

AUTHOR
Luigi Rizzo <luigi.rizzo@iet.unipi.it>