diff --git a/doc/DEVICES.txt b/doc/DEVICES.txt new file mode 100644 index 0000000..7142254 --- /dev/null +++ b/doc/DEVICES.txt @@ -0,0 +1,124 @@ +# 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). | diff --git a/interfaces/native/Makefile b/interfaces/native/Makefile index f0fa886..c6e09aa 100644 --- a/interfaces/native/Makefile +++ b/interfaces/native/Makefile @@ -15,6 +15,11 @@ freebsd64: nasm -f elf64 fbsd64.s ld -nostdlib -m elf_x86_64_fbsd fbsd64.o retro.o -o bin/rf.bsd64 +openbsd: + cc -m64 -static -fno-pie -c retro.c + nasm -f elf64 obsd64.s + ld -fno-pie -e _start -static obsd64.o retro.o -o bin/rf.bsd64 + linux: cc -m32 -c retro.c nasm -f elf linux.s