# 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 | Clock            |                               |
| 0006 |                  |                               |
| 0007 | Network: Sockets |                               |
| 0008 | Syscalls: Unix   |                               |
| 0009 | Scripting Hooks  |                               |
| 0010 | Random Number    |                               |
| 1000 | Image Writer     | Saving the image to disk      |
| 8000 | Multicore        | Extensions for multiple cores |
| 8100 | FFI              | Extensions for FFI            |
| 8101 | Unsigned         | Extensions for unsigned maths |
+------+------------------+-------------------------------+

# 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             |

## 0010: Random Number Generator