AmigaDOS Device Input and Output

This page is currently being updated to AmigaOS 4.x. Some of the information contained here may not yet be applicable in part or totally.

Introduction

AmigaDOS uses handlers and file systems to provide a standard method of interaction with physical I/O devices. Handlers and file systems are similar; handlers are a subset of a file system, supporting only a few I/O operations, while file systems include additional support for file operations as well as directory-type operations. Handlers and file systems reside either in ROM or in the L: directory.

Handlers and file systems are often referred to as "AmigaDOS devices" but keep in mind that an AmigaDOS device is different from an Exec device. AmigaDOS devices appear as names within the DOS name space, for example, SER:, RAM: or DF0: (rather than Exec's serial.device or trackdisk.device). AmigaDOS devices are often built on top of Exec devices using the Exec device to perform the low-level functions.

Examples of this type include:

• The Port-handler (SER:, PAR:, and PRT:) which is built on top of the serial.device, parallel.device, and printer.device.
• The file system (DF0:, DF1:) which is built on top of the trackdisk.device.
• CON: (console handler) which is built on top of the console.device.

It is not required for a handler or file system to be built on top of an Exec device. In some cases the handler manages its own resources. For example, for the RAM-handler the resource being maintained is RAM. While the memory used by the RAM-handler is still allocated by Exec, there is really no underlying Exec device.

Note that, unlike an Exec device, each handler and file system executing must have its own process.

AmigaDOS Devices

Here is a list of AmigaDOS devices implemented as handlers. Note that some handlers have more than one name. (RAW: and CON: are the same handler with different names. The port handlers SER:, PAR:, and PRT: are alsoimplemented as a single handler with more than one name.)

AUX:

The AUX: handler provides unbuffered serial I/O. It is basically a console handler that uses the serial port rather than the Amiga screen or keyboard. For instance, the command NEWSHELL AUX: allows you to run a Shell over the serial port.

CON:

Provides buffered keyboard and screen I/O and allows definition of a new window for the output. With CON:, keystrokes are buffered and held back from the application until the user presses the RETURN key. The keyboard input is filtered: function keys and cursor keys are not transmitted. Other keys are automatically echoed in the CON: window.

The window is specified using x/y/width/height/title where x and y are the distance from the top and left edge of the screen the window should open. For instance, the command TYPE >CON:5/5/100/100/Output DEVS:mountlist shows the mountlist file in a new window named Output which is 100 x 100 pixels and is positioned 5 pixels down and to the right of the upper left corner of the screen.

Instead of using a new window for the output, you can send it to the currently selected window by using * instead of CON:x/y/width/height/title.

Additional keywords may be specified as follows:

AUTO	Don't open window until or unless I/O occurs
CLOSE	Put a close gadget on the window. If the user closes the window, a read from CON: will return -1L; a read from RAW: (or a CON: in raw mode) will retuirn the Raw Event escape string for a close gadget.
WAIT	Hold off close until user clicks the close gadget or types Control-\.
WINDOW 0xaddr	Use window pointed to by addr (may be [on] a custom screen).
SCREEN name	Opens on the public screen specified by name.

The additional CON: keywords BACKDROP, NODRAG, NOBORDER, NOSIZE, SIMPLE and SMART control the same window attributes as their similarly named Intuition window flags.

The command line can be edited with cursor keys, backspace, and delete. A 2K line history buffer allows a line previously typed to be recalled by pressing cursor up. Shift cursor up (or Control-R) searches back through the line history buffer for the last line entered that matches a partially typed string. Shift cursor down (or Control-B) brings you to the bottom of the history buffer. Additional edit operations are:

Control-K	Deletes everything from the cursor to the end of the line.
Control-U	Deletes everything from the cursor to the start of the line.
Control-X	Deletes the entire line.
Control-W	Moves the cursor to the next tab stop.
Control-A	Moves the cursor to the start of the line (shift cursor left also does this).
Control-Z	Moves the cursor to the end of the line (shift cursor right also does this).

In addition to the line editing features, text copy and paste features are available. The user can drag-select a text block in a console window with the mouse and then copy the selected text to an internal buffer with Right-Amiga-C. (Extended drag-select is also supported with the Shift keys.) The text may then be pasted into another console window with Right-Amiga-V. Pasted text is inserted into the read stream as if the text had been typed manually.

A special utility called ConClip (part of the standard Startup-sequence) provides clipboard support for copy and paste operations. When ConClip is running, console text copied with Right-Amiga-C is placed in the clipboard.device; console paste operations with Right-Amiga-V cause a special code (<CSI>0 v) to be inserted into the read stream instead of the text. The CON: handler reads from the clipboard when this code is received so applications that use CON: get clipboard support automatically. Applications that use the RAW: handler (see blow) must provide their own support for clipboard reads.

Note that with the CON: and RAW: handlers, if the SMART flag is used in the window specification then only text paste operations are supported. Text cut operations do not work with the SMART flag.

RAW:

Provides unbuffered screen and keyboard I/O and allows definition of a new window for the output just like CON:. (In fact, RAW: and CON: are implemented as a single handler with two names and corresponding modes of operation.) With RAW:, key presses are unbuffered and can be read by an application immediately. The keyboard I/O is unfiltered allowing processing of all key combinations. Keystrokes are not automatically echoed in the RAW: window.

NEWCON: (Obsolete)

(Obsolete) This handler was included only in V1.3 of the Amiga operating system as an alternative to the original CON: handler. The original CON: handler had no line editing functions but these have been incorporated into CON: in V2.0 and later versions of AmigaDOS.

SER:

The SER: handler provides a stream-oriented interface to the serial port (a stream-oriented interface allows you to treat the physical device as a file).

PAR:

The PAR: handler provides a stream-oriented interface to the parallel port (a stream-oriented interface allows you to treat the physical device as a file).

PRT:

The PRT: handler provides a stream-oriented interface to the printer and also accepts standard printer codes, translating them into the command sequence used for the currently selected printer driver.

NIL:

The NIL: handler provides a convenient place to send command output that you are not interested in. For instance, MOUNT >NIL: AUX: mount[s] the AUX: device without printing any diagnostic messages on the screen. Note that the NIL: handler is really a fake handler maintained within AmigaDOS. It is not a separate process.

PIPE:

The PIPE: handler is a mechanism meant to provide convenient buffered I/O communication between programs. When the PIPE: is written to, up to 4K of data are buffered before the writing process is blocked. After one process writes to PIPE: any other can read from it. This is useful, for instance, when you're using two application programs and want to transfer a large amount of data from one (write) to the other (read) without creating a temporary file in RAM: or on disk.

SPEAK:

The SPEAK: handler provides speech output for the Amiga. With SPEAK: you can have the Amiga literally read the contents of a file out load. For instance, COPY DEVS:mountlist SPEAK:OPT/f/s160 will say the contents of the mountlist in a female voice at a moderate speed. SPEAK: accepts all the options of the SAY command and also o0 and o1 (enables or disables processing of options in the input stream), a0 and a1 (toggled direct phoneme mode), and d0 and d1 (enables sentence pause on LF or CR).

Communicating with AmigaDOS Devices

The usual method of communicating with handlers and file systems is through the AmigaDOS file I/O functions such as Open(), Read() and Write(). A lower level method is through the DOS packet interface, the basic communication method between different processes. Built on top of the Exec message passing system, the packet interface provides a standard means of interprocess communication.

This communication may take place either synchronously or asynchronously (usually through a routine called DoPkt(), which does the work of finding the task address, sending the message via PutMsg(), and Wait()ing on the reserved DOS packet signal). The DOS library calls that talk to handlers - Read(), Write(), Open() - use the packet interface.

The dos.library translates these calls into packets, sends them to the appropriate handler process, and returns the results to the calling routine. There is very little extra overhead associated with using the library calls over using the packet interface directly. What is lost, though, is the ability to easily perform asynchronous I/O, so you may want to use the packet interface directly for this instead of using the function interface. For more information on packets, see AmigaDOS Packets.

Creating a New Device to Run Under AmigaDOS

This section provides information about adding devices that are NOT part of the DOS filing system like the console and port handlers. The next section provides information about adding file system-related devices (hard disks, floppy disks) - that is, devices that DOS can use to read and write files with their associated directories.

You would want to use this information to add a new device such as a new serial port or a new parallel port. In this case you may be creating a device named "SER2:" which is to act just like "SER:" as far as DOS is concerned.

There are two steps involved here. First, you must create a suitable device, a process that is not addressed here.

Second, you must make this new device available as an AmigaDOS device. This process involves writing a suitable device handler and installing it into the AmigaDOS structures. You install a new device and its handler under AmigaDOS with the MOUNT command. You need to put the device in the DEVS: directory, the handler in the L: directory, and add an entry for the device in DEVS:mountlist.

The device handler is the interface between your device and an application program. The AmigaDOS kernel will attempt to load the code of the handler and create a new process for it when it is first referenced. This is handled automatically when the kernel notices that the Task field in the DevInfo structure is zero. If the code is already loaded, the code segment pointer is placed in the SegList field. If this field is zero, the kernel loads the code from the filename given in the filename field and updates the SegList field.

Making New Disk Devices

To create a new disk device, you must construct a new device node as described in Info Substructure in AmigaDOS Data Structures. You must also write a device driver for the new disk device.

A device driver for a new disk device must mimic the calls that are performed by the trackdisk.device. It must include the ability to respond to commands such as Read(), Write(), Seek(), and return status information in the same way as described for the trackdisk driver.