💾 Archived View for retroforth.org › nga › docs › DEVICES.txt captured on 2024-07-08 at 23:59:13.
⬅️ Previous capture (2023-01-29)
-=-=-=-=-=-=-
# 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