Copyright (c) Hyperion Entertainment and contributors.

Difference between revisions of "AmigaDOS Device Input and Output"

From AmigaOS Documentation Wiki
Jump to navigation Jump to search
 
Line 1: Line 1:
[[Category:DOS|Device]]{{WIP}}
+
[[Category:DOS|Device]]
  +
{{WIP}}
 
= Introduction =
 
= Introduction =
   
AmigaDOS uses handlers and filesystems to provide a standard method of
+
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.
interaction with physical I/O devices. Handlers and filesystems are
 
similar; handlers are a subset of a filesystem, supporting only a few I/O
 
operations, while filesystems include additional support for file
 
operations as well as directory-type operations. Handlers and filesystems
 
reside either in ROM or in the L: directory.
 
   
Handlers and filesystems are often referred to as "AmigaDOS devices" but
+
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.
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:
 
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 Port-handler (SER:, PAR:, and PRT:) which is built on top of the serial.device, parallel.device, and printer.device.
* The filesystem (DF0:, DF1:) which is built on top of the trackdisk.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.
 
* CON: (console handler) which is built on top of the console.device.
   
It is not required for a handler or filesystem to be built on top of an
+
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.
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 filesystem executing
+
Note that, unlike an Exec device, each handler and file system executing must have its own process.
must have its own process.
 
   
 
= AmigaDOS Devices =
 
= AmigaDOS Devices =
   
Here is a list of AmigaDOS devices implemented as handlers. Note that some
+
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.)
handlers have more than one name. (RAW: and CON: are the same handler with
 
different names. The port handlers SER:, PAR:, and PRT: are also
 
implemented as a single handler with more than one name.)
 
   
 
== AUX: ==
 
== AUX: ==
   
The AUX: handler provides unbuffered serial I/O. It is basically a
+
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.
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: ==
 
== CON: ==
Line 106: Line 89:
 
== RAW: ==
 
== 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
Provides unbuffered screen and keyboard I/O and allows
 
  +
application immediately. The keyboard I/O is unfiltered allowing processing of all key combinations. Keystrokes are not automatically echoed in the RAW: window.
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) ==
 
== NEWCON: (Obsolete) ==
Line 121: Line 98:
 
== SER: ==
 
== SER: ==
   
The SER: handler provides a stream-oriented interface to
+
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).
the serial port (a stream-oriented interface allows you to
 
treat the physical device as a file).
 
   
 
== PAR: ==
 
== PAR: ==
   
The PAR: handler provides a stream-oriented interface to
+
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).
the parallel port (a stream-oriented interface allows you
 
to treat the physical device as a file).
 
   
 
== PRT: ==
 
== PRT: ==
   
The PRT: handler provides a stream-oriented interface to
+
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.
the printer and also accepts standard printer codes,
 
translating them into the command sequence used for the
 
currently selected printer driver.
 
   
 
== NIL: ==
 
== 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.
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: ==
 
== 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.
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: ==
 
== 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).
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 =
 
= Communicating with AmigaDOS Devices =
   
The usual method of communicating with handlers and filesystems is through
+
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.
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
+
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.
(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
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|AmigaDOS Packets]].
 
function interface. For more information on packets, see [[AmigaDOS_Packets|AmigaDOS Packets]].
   
 
= Creating a New Device to Run Under AmigaDOS =
 
= Creating a New Device to Run Under AmigaDOS =
   
This section provides information about adding devices that are NOT part
+
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.
of the DOS filing system like the console and port handlers. The next
 
section provides information about adding filesystem-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
+
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.
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
+
There are two steps involved here. First, you must create a suitable device, a process that is not addressed here.
device, a process that is not addressed here.
 
   
Second, you must make this new device available as an AmigaDOS device.
+
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
This process involves writing a suitable device handler and installing it
 
  +
DEVS: directory, the handler in the L: directory, and add an entry for the device in DEVS:mountlist.
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.
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 =
 
= Making New Disk Devices =
   
To create a new disk device, you must construct a new device node as
+
To create a new disk device, you must construct a new device node as described in [[AmigaDOS Data Structures#Info_Substructure|Info Substructure]] in [[AmigaDOS_Data_Structures|AmigaDOS Data Structures]]. You must also write a device driver for the new disk device.
described in [[AmigaDOS Data Structures#Info_Substructure|Info Substructure]] in [[AmigaDOS_Data_Structures|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
+
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.
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.
 

Latest revision as of 19:47, 2 October 2015


WIP.png 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.