125 lines
3.7 KiB
Text
125 lines
3.7 KiB
Text
|
# 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 | |
|
||
|
|
|
||
|
|
# 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). |
|