💾 Archived View for retroforth.org › nga › docs › DEVICES.txt captured on 2023-03-20 at 17:37:24.
⬅️ 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