retroforth/doc/DEVICES.txt

# Overview

Nga provides three instructions for interacting with I/O devices.
These are:

    ie   i/o enumerate    returns the number of attached devices
    iq   i/o query        returns information about a device
    ii   i/o interact     invokes an interaction with a device

As an example, with an implementation providing an output source,
a block storage system, and keyboard:

    ie    will return `3` since there are three i/o devices
    0 iq  will return 0 0, since the first device is a screen (0)
          with a version of 0
    1 iq  will return 1 3, since the second device is a block
          storage (3), with a version of 1
    2 iq  will return 0 1, since the third device is a keyboard
          (1), with a version of 0

In this case, some interactions can be defined:

    : c:put
    i liiire..
    d 0
    
    : c:get
    i liiire..
    d 2

Setup the stack, push the device ID to the stack, and then use
`ii` to invoke the interaction.

A RETRO system requires one I/O device (a generic output for a
single character). This must be the first device, and must have
a device ID of 0.

All other devices are optional and can be specified in any order.

# Device Types

 ID  | Device Type      | Notes                      |
-----+------------------+----------------------------+
0000 | Generic Output   | Always present as device 0 |
0001 | Keyboard         |                            |
0002 | Floating Point   |                            |
0003 | Block Storage    | Raw, 1024 cell blocks      |
0004 | Filesystem       | Unix-style Files           |
0005 | Network: Gopher  | Make gopher requests       |
0006 | Network: HTTP    |                            |
0007 | Network: Sockets |                            |
0008 | Syscalls: Unix   |                            |
0009 | Scripting Hooks  |                            |
0010 | Random Number    |                            |

# Device Details

## 0000: Generic Output

Revision 0:

This device is used to write a single character to an system
specific output device.

Takes a single value representing a character, returns nothing.

No subcommands are defined.

## 0001: Keyboard

Revision 0:

Read and return a keypress.

Consumes no data, returns a single value representing the
character that was read.

No subcommands are defined.

## 0002: Floating Point

Revision 0:

TBD.

## 0003: Block Storage

Reserved for future use.

## 0004: Filesystem

Revision 0:

This implements a device providing traditional Unix-like files.

Takes a value indicating an operation, and each operation takes
additional values.

    | Operation | Stack | Action                           |
    | --------- | ----- | -------------------------------- |
    | 0         | sm-h  | Open a file                      |
    | 1         | h-    | Close a file                     |
    | 2         | h-c   | Read a byte from a file          |
    | 3         | ch-   | Write a byte to a file           |
    | 4         | h-n   | Return current pointer into file |
    | 5         | nh-   | Move pointer in a file           |
    | 6         | h-n   | Return the size of a file        |
    | 7         | s-    | Delete a file                    |
    | 8         | h-    | Flush pending writes             |

## 0005: Network: Gopher

Revision 0:

This device fetches resources using the Gopher protocol.

Takes a single value indicating the operation; the operation
requires additional values.

    | Operation | Stack | Action                           |
    | --------- | ----- | -------------------------------- |
    | 0         | asns- | Connect to server (s1), port (n) |
    |           |       | and request selector (s2). The   |
    |           |       | returned data is stored at the   |
    |           |       | destination address (a).         |

## 0010: Random Number Generator