retroforth/doc/DEVICES.txt

125 lines
3.7 KiB
Text
Raw Normal View History

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