117 lines
3.6 KiB
Text
117 lines
3.6 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 | 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
|