{"id":20214659,"url":"https://github.com/divergentclouds/riw-16","last_synced_at":"2026-06-20T08:31:36.608Z","repository":{"id":155459896,"uuid":"434979282","full_name":"DivergentClouds/riw-16","owner":"DivergentClouds","description":"A fantasy computer with 16 instructions.","archived":false,"fork":false,"pushed_at":"2023-05-15T00:05:58.000Z","size":48,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-11-30T16:52:09.692Z","etag":null,"topics":["assembly","fantasy-computer","fantasy-console","instruction-set-architecture","isa"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DivergentClouds.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-12-04T18:30:51.000Z","updated_at":"2024-10-12T16:02:50.000Z","dependencies_parsed_at":null,"dependency_job_id":"cad54076-eba6-4008-aa9c-a5ddbaaceab0","html_url":"https://github.com/DivergentClouds/riw-16","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/DivergentClouds/riw-16","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DivergentClouds%2Friw-16","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DivergentClouds%2Friw-16/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DivergentClouds%2Friw-16/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DivergentClouds%2Friw-16/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DivergentClouds","download_url":"https://codeload.github.com/DivergentClouds/riw-16/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DivergentClouds%2Friw-16/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34563535,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-20T02:00:06.407Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["assembly","fantasy-computer","fantasy-console","instruction-set-architecture","isa"],"created_at":"2024-11-14T06:17:28.418Z","updated_at":"2026-06-20T08:31:36.584Z","avatar_url":"https://github.com/DivergentClouds.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# RIW-16\n\n## Overview\nRIW-16 is a fantasy computer that is programmed in an assembly language with\n16 instructions.\n\n### Notes\n- RIW-16 stands for Reduced Instruction Word-16\n- Programmed in custom ASM\n- 16-bit registers\n- 16-bit instructions\n- 16-bit words instead of bytes\n- Fixed instruction width\n- Mixed Program/Data\n- 16 Registers\n- 2^24 words of memory\n  - Program is loaded in at address 0\n    - Program Counter starts at 0\n  - Only 2^16 words are addressable at a single time\n- Paged memory\n  - 256 pages\n  - Each Page is 256 Words\n- 2^32 words of addressable storage\n  - The emulator will use a custom storage data format to allow for sparse data\n- Text based I/O\n- Words are big-endian\n\n## I/O\n\n### Devices\n- System\n  - ID: `0x0`\n  - Operations:\n    - Syscall `0x0`\n      - Data: Writes to the internal `syscall-hold` register, then loads the\n      `syscall-handler` register into `$pc`\n    - Syscall-Hold-Get `0x1`\n      - Data: Reads from the internal `syscall-hold` register\n    - Syscall-Handler-Set `0x2`\n      - Data: Writes to the internal `syscall-handler` register\n    - Syscall-Handler-Get `0x3`\n      - Data: Reads from the internal `syscall-handler` register\n    - Fault `0x4`\n      - Data: Writes to the internal `fault-hold` register, then loads the\n      `fault-handler` register into `$pc`\n    - Fault-Hold-Get `0x5`\n      - Data: Reads from the internal `fault-hold` register\n    - Fault-Handler-Set `0x6`\n      - Data: Writes to the internal `fault-handler` register\n    - Fault-Handler-Get `0x7`\n      - Data: Reads from the internal `fault-handler` register\n    - Halt `0x8`\n      - Data: Ignored, Halts the system\n- Console\n  - ID: `0x1`\n  - Operations:\n    - Char-out `0x0`\n      - Data: The lower octet is sent to stdout of the host.\n    - Char-in `0x1`\n      - Data: If there is a byte from stdin on the host available, then the\n      upper octet is set to 0 and lower octet is set to the next byte of stdin,\n      otherwise the whole word is set to `0xFFFF`.\n- Storage\n  - ID: `0x2`\n  - Operations:\n    - MSW-Address-Set `0x0`\n      - Data: Writes to the most significant word of the storage device's\n      internal address.\n    - LSW-Address-Set `0x1`\n      - Data: Writes to the least significant word of the storage device's\n      internal address.\n    - MSW-Address-Get `0x2`\n      - Data: Reads the most significant word of the storage device's internal\n      address.\n    - LSW-Address-Get `0x3`\n      - Data: Reads the least significant word of the storage device's internal\n      address.\n    - Storage-Out `0x4`\n      - Data: Writes to the word at the storage device's current internal\n      address.\n    - Storage-In `0x5`\n      - Data: Reads the word at the storage device's current internal address.\n- MMU\n  - ID: `0x3`\n  - Operations:\n    - MSW-Frame-Set `0x0`\n      - Data: Writes the lower octet to the most significant word of the MMU's\n      internal `frame` register.\n    - LSW-Frame-Set `0x1`\n      - Data: Writes to the least significant word of the MMU's internal `frame`\n      register.\n    - MSW-Frame-Get `0x2`\n      - Data: Reads the lower octet of most significant word of the MMU's\n      internal `frame` register. The upper octet is set to 0.\n    - LSW-Frame-Get `0x3`\n      - Data: Reads the least significant word of the MMU's internal `frame`\n      register.\n    - Map-Set `0x4`\n      - Data: Sets the page specified by the data to be mapped to the frame\n      specified by the internal `frame` register.\n    - Map-Get `0x5`\n      - Data: Sets the internal `frame` register to the frame mapped to the\n      specified page.\n    - Lock-IO `0x6`\n      - Data: Redirect all I/O operations except `System/Syscall` on the\n      specified page to `System/Fault` with the data as `$pc`.\n    - Unlock-IO `0x7`\n      - Data: Stop redirecting I/O operations on the specified page.\n    - Lock-Read `0x8`\n      - Data: Redirect all `load` operations on the specified page to act as\n      `System/Fault` with the data as `$pc`\n    - Unlock-Read `0x9`\n      - Data: Stop redirecting `load` operations on the specified page.\n    - Lock-Write `0xA`\n      - Data: Redirect all `store` operations on the specified page to act as\n      `System/Fault` with the data as `$pc`\n    - Unlock-Write `0xB`\n      - Data: Stop redirecting `store` operations on the specified page.\n    - Lock-Execute `0xC`\n      - Data: Redirect all operations from the specified page to act as\n      `System/Fault` with the data as `$pc`.\n    - Unlock-Execute `0xD`\n      - Data: Stop redirecting all operations on the specified page.\n    - Promote `0xE`\n      - Data: Prevent all locks from affecting the specified page if `$pc` is\n      in the specified page. Any attempts to preform any operations to the\n      specified page or to set `$pc` to an address in the specified page from\n      a non-promoted page (except through `System/Syscall`) results in that\n      operation acting as `System/Fault` with the data as `$pc`.\n    - Demote `0xF`\n      - Data: Allow locks to affect the specified page and allow non-promoted\n      pages to access it if a lock does not prevent it.\n\n## Assembly Language\n\n### Notes\n\n- $ specifies a register\n- The lack of a `$` prefix specifies a immediate\n- Immediates may be prefixed with either `0b`, `0o`, `0d` or `0x` to specify\nwhat base the number is in\n  - `0b` is binary,`0o` is octal, `0d` is decimal and `0x` is hexadecimal\n  - If a number is not prefixed then it is assumed to be decimal\n- Underscores in immediates are ignored\n- A series of octet immediates may be represented by a series of characters\nsurrounded by single or double quotes\n- Identifiers are strings of the form `[a-zA-Z_][a-zA-Z0-9_]*`\n- Identifiers may be used in place of an immediate\n- An identifier may not be defined if it has been previously defined\n- Forward references to identifiers are valid\n- If an immediate is too large for an instruction, the assembler must emit an\nerror\n  - If the bit width of an immediate is specified\n- Some operators may optionally be suffixed with `w`, `o`, `n` or `b` to specify\nthe bit width of the result\n  - `w` is 16-bit, `o` is 8-bit, `n` is 4-bit, `b` is 1-bit\n  - If the operator is not suffixed, it is assumed to be 16-bit\n  - The affected operators are `+`, `+|`, `-`, `-|`, `|`, `\u0026`, `^` and `~`\n- Operators are left associative\n- Line comments are started with `;`\n\n### Instructions\n\n- `loct $A, B`\n  - `0000 AAAA BBBB BBBB`\n  - Loads the immediate value `B` into the lower octet of`$A`, other bits in\n  `$A` are not affected\n- `uoct $A, B`\n  - `0001 AAAA BBBB BBBB`\n  - Loads the immediate value `B` into the upper octet of`$A`, other bits in\n  `$A` are not affected\n- `addi $A, $B, C`\n  - `0010 AAAA BBBB CCCC`\n  - Adds `C` to `$B` and store the result in `$A`. `C` is treated as a 4-bit\n  signed integer\n- `load $A, $B, $C`\n  - `0011 AAAA BBBB CCCC`\n  - Loads the contents of the address that `($B + $C)` points to into `$A`.\n  `$C` is treated as signed\n- `store $A, $B, $C`\n  - `0100 AAAA BBBB CCCC`\n  - Stores `$C` into the address that `($A + $B)` points to. `$B` is treated\n  as signed\n- `add $A, $B, $C`\n  - `0101 AAAA BBBB CCCC`\n  - Adds `$B` to `$C` and stores the result in `$A`\n- `sub $A, $B, $C`\n  - `0110 AAAA BBBB CCCC`\n  - Subtracts `$C` from `$B` and stores the result in `$A`\n- `cmp $A, $B, $C`\n  - `0111 AAAA BBBB CCCC`\n  - Compare `$B` and `$C` with a subtraction of the form `$B - $C`,\n  store/clear flags of the comparison in `$A`, other bits in `$A` are not\n  affected\n- `branch $A, $B, C`\n  - `1000 AAAA BBBB CCCC`\n  - If the results of a bitwise AND with the immediate value `C` and `$B` match\n  `C`, copy `$A` into `$pc`\n- `shift $A, $B, $C`\n  - `1001 AAAA BBBB CCCC`\n  - Bitshifts `$B` by `$C` (negative for right, positive for left) and stores\n  the result in `$A`. Newly shifted in bits are 0\n- `and $A, $B, $C`\n  - `1010 AAAA BBBB CCCC`\n  - Performs a bitwise AND on `$B` and `$C`, and stores the result into `$A`\n- `or $A, $B, $C`\n  - `1011 AAAA BBBB CCCC`\n  - Performs a bitwise OR on `$B` and `$C`, and stores the result into `$A`\n- `xor $A, $B, $C`\n  - `1100 AAAA BBBB CCCC`\n  - Performs a bitwise XOR on `$B` and `$C`, and stores the result into `$A`\n- `nor $A, $B, $C`\n  - `1101 AAAA BBBB CCCC`\n  - Performs a bitwise NOR on `$B` and `$C`, and stores the result into `$A`\n- `swap $A, $B, $C`\n  - `1110 AAAA BBBB CCCC`\n  - Sets the most significant octet of `$A` to the least significant octet of\n  `$B` and the least significant octet of `$A` to the most significant octet\n  of `$C` \n- `io $A, $B, $C`\n  - `1111 AAAA BBBB CCCC`\n  - Performs a device-specific I/O operation `$B` using device `$A` and\n  and `$C` as the data.\n\n### Registers\n\n- `$0`-`$14`\n  - General Purpose Registers\n  - Alias: None\n  - Purpose: Anything\n- `$15`\n  - Program Counter\n  - Alias: `$pc`\n  - Purpose: Contains pointer to the current instruction, jumps if written to\n\n### Flags\n\nFlags are stored in the least significant nibble of the register that\n`cmp` is given. Other bits in the register are unaffected.\nThe flags are as follows:\n- Half\n  - x???\n  - Set if the result of the comparison was less than 256; cleared otherwise\n- Overflow\n  - ?x??\n  - Set if both operands were of the comparison were the same sign and the\n  result is of the opposite sign; cleared otherwise\n- Negative\n  - ??x?\n  - Set if result of the comparison had the most significant bit set;\n  cleared otherwise\n- Zero\n  - ???x\n  - Set if the result of the comparison was 0; cleared otherwise\n\n### Labels and Constants\n\n- `A:`\n  - Create a global label equal to the current address\n  - `A` is an identifier\n- `.A:`\n  - Create a local label equal to the current address\n  - Forward references to `A` are only allowed starting from the previous global\n  label\n    - If no global label precedes `A`, forward references are allowed starting\n    from the beginning of the file\n  - The identifier `A` is only considered defined until the next global label\n  - `A` is an identifier\n- `A = B`\n  - Create a global constant `A` equal to an immediate `B`\n  - `A` is an identifier\n- `.A = B`\n  - Create a local constant `A` equal to an immediate `B`\n  - Forward references to `A` are only allowed starting from the previous global\n  label\n    - If no global label precedes `A`, forward references are allowed starting\n    from the beginning of the file\n  - The identifier `A` is only considered defined until the next global label\n  - `A` is an identifier\n\n### Operators\n\n- `@`\n  - Treated as an immediate equal to the current address\n    - In the case of `word` the current address is the address at the start\n- `A[B, C]`\n  - Treated as an immediate equal to bits `B` through `C` from `A`\n  - Precedence: 1\n- `A + B`\n  - Treated as an immediate equal to `A` plus `B`, wraps\n  - Precedence: 0\n- `A +| B`\n  - Treated as an immediate equal to `A` plus `B`, staturates\n  - Precedence: 0\n- `A - B`\n  - Treated as an immediate equal to `A` minus `B`, wraps\n  - Precedence: 0\n- `A -| B`\n  - Treated as an immediate equal to `A` minus `B`, saturates\n  - Precedence: 0\n- `A | B`\n  - Treated as an immediate equal to `A` or `B`\n  - Precedence: 0\n- `A \u0026 B`\n  - Treated as an immediate equal to `A` and `B`\n  - Precedence: 0\n- `A ^ B`\n  - Treated as an immediate equal to `A` xor `B`\n  - Precedence: 0\n- `~ A`\n  - Precedence: 0\n- `( ... )`\n  - Group the contents as having the highest precedence\n  \n\n### Pseudo-Instructions\n\n- `word $A, B`\n  - Equivalent to `loct $A, B[0, 7]` followed by `uoct $A, B[8, 15]`\n- `jump $A`\n  - Equivalent to `OR $pc, $A $A`\n- `lit A, ...`\n  - Takes one or more 16-bit immediates and stores them starting at the current\n  address\n- `lito A, ...`\n  - Takes one or more 8-bit immediates and stores them starting at the current\n  address\n    - Up to two immediates are placed in each word, with the first immediate\n    going in the upper octet\n  \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdivergentclouds%2Friw-16","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdivergentclouds%2Friw-16","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdivergentclouds%2Friw-16/lists"}