|
| 1 | +//! An implementation of the [`pir-8` ISA](https://github.com/thecoshman/pir-8/blob/master/ISA.md). |
| 2 | +//! |
| 3 | +//! # The library |
| 4 | +//! |
| 5 | +//! [`pir-8-emu`](https://github.com/LoungeCPP/pir-8-emu) can be thought of as consisting of layers: |
| 6 | +//! |
| 7 | +//! The first layer is the [`isa`](isa/) module, |
| 8 | +//! which contains a pure implementation of the [`pir-8` ISA](https://github.com/thecoshman/pir-8/blob/master/ISA.md), |
| 9 | +//! and can be used on its own to parse/generate binaries at the instruction level. |
| 10 | +//! |
| 11 | +//! The second layer is the [`vm`](vm/) module, |
| 12 | +//! which contains parts of VM memory and port handling. |
| 13 | +//! |
| 14 | +//! The third layer is the [`micro`](micro/) module, |
| 15 | +//! which contains a full stack-based microcode implementation, |
| 16 | +//! and can be used to fully emulate a `pir-8` machine (see example inside). |
| 17 | +//! |
| 18 | +//! The fourth layer is the various [`binutils`](binutils/), |
| 19 | +//! which contain useful parts of the executables, |
| 20 | +//! like [`AssemblerDirective`](binutils/pir_8_as/enum.AssemblerDirective.html) and |
| 21 | +//! [`OutputWithQueue`](binutils/pir_8_as/struct.OutputWithQueue.html), |
| 22 | +//! or [`NativePortHandler`](binutils/pir_8_emu/struct.NativePortHandler.html). |
| 23 | +//! |
| 24 | +//! These utilities can be used to quickly and correctly build off existing solutions, |
| 25 | +//! but may have some quirks or be less absolutely generic |
| 26 | +//! (e.g. [`Vm`](binutils/pir_8_emu/struct.Vm.html) will allow you to integrate |
| 27 | +//! a fully (as-emulator) controllable and functional `pir-8` virtual machine in about 5 lines, |
| 28 | +//! but it needs to have the `INS` SP register be observed after each μOp (see example inside)). |
| 29 | +//! |
| 30 | +//! # The binaries |
| 31 | +//! |
| 32 | +//! The headers link to manpages with more detailed usage instructions: |
| 33 | +//! |
| 34 | +//! ## [`pir-8-as`](https://rawcdn.githack.com/LoungeCPP/pir-8-emu/man/pir-8-as.1.html) |
| 35 | +//! |
| 36 | +//! An assembler with an… idiosyncratic syntax: |
| 37 | +//! |
| 38 | +//! ```p8a |
| 39 | +//! JUMP |
| 40 | +//! :label load text |
| 41 | +//! |
| 42 | +//! :literal "*pounces on u* OwO what's whis?" |
| 43 | +//! 0x00 |
| 44 | +//! |
| 45 | +//! :label save text |
| 46 | +//! LOAD IMM Y |
| 47 | +//! 1 |
| 48 | +//! |
| 49 | +//! LOAD IMM A |
| 50 | +//! 0x00 |
| 51 | +//! |
| 52 | +//! LOAD IMM X |
| 53 | +//! 0x03 |
| 54 | +//! |
| 55 | +//! :label save loop-head |
| 56 | +//! SAVE X |
| 57 | +//! :label load-offset load-byte 2 |
| 58 | +//! |
| 59 | +//! JUMP |
| 60 | +//! :label load load-byte |
| 61 | +//! |
| 62 | +//! :label save post-load |
| 63 | +//! PORT OUT S |
| 64 | +//! COMP S |
| 65 | +//! JMPZ |
| 66 | +//! :label load end |
| 67 | +//! |
| 68 | +//! ALU ADD |
| 69 | +//! MOVE S X |
| 70 | +//! JUMP |
| 71 | +//! :label load loop-head |
| 72 | +//! |
| 73 | +//! :label save end |
| 74 | +//! HALT |
| 75 | +//! |
| 76 | +//! :label save load-byte |
| 77 | +//! LOAD IND S |
| 78 | +//! 0x0000 |
| 79 | +//! JUMP |
| 80 | +//! :label load post-load |
| 81 | +//! ``` |
| 82 | +//! |
| 83 | +//! If you'd rather use a more normal syntax, [CatPlusPlus](https://github.com/TheCatPlusPlus) has also made |
| 84 | +//! a [`fasm`-based assembler](https://github.com/TheCatPlusPlus/pir8/tree/master/Assembler): |
| 85 | +//! |
| 86 | +//! ```asm |
| 87 | +//! include 'pir8.finc' |
| 88 | +//! |
| 89 | +//! origin 0x0002 |
| 90 | +//! |
| 91 | +//! load a, [0x0000] |
| 92 | +//! load b, [0x0001] |
| 93 | +//! |
| 94 | +//! top: |
| 95 | +//! move x, a |
| 96 | +//! move y, b |
| 97 | +//! sub |
| 98 | +//! |
| 99 | +//! jmpz exit |
| 100 | +//! |
| 101 | +//! move s, a |
| 102 | +//! comp b |
| 103 | +//! |
| 104 | +//! jmpl lt |
| 105 | +//! |
| 106 | +//! sub |
| 107 | +//! move a, s |
| 108 | +//! jump top |
| 109 | +//! |
| 110 | +//! lt: |
| 111 | +//! move y, a |
| 112 | +//! move x, b |
| 113 | +//! sub |
| 114 | +//! move b, s |
| 115 | +//! jump top |
| 116 | +//! |
| 117 | +//! exit: |
| 118 | +//! move d, a |
| 119 | +//! halt |
| 120 | +//! ``` |
| 121 | +//! |
| 122 | +//! ## [`pir-8-disasm`](https://rawcdn.githack.com/LoungeCPP/pir-8-emu/man/pir-8-disasm.1.html) |
| 123 | +//! |
| 124 | +//! A dissassembler with a [`ndisasm`](https://www.nasm.us)-based frontend: |
| 125 | +//! |
| 126 | +//! ```plaintext |
| 127 | +//! $ pir-8-disasm -k 1,7 test-data/xor-swap-with-loads.p8b |
| 128 | +//! 00000000 24 LOAD IND A |
| 129 | +//! 00000002 0110 D 0x0110 |
| 130 | +//! 00000003 1D LOAD IMM B |
| 131 | +//! 00000004 69 D 0x69 |
| 132 | +//! 00000005 62 MOVE A X |
| 133 | +//! 00000006 6B MOVE B Y |
| 134 | +//! 00000007 35 ALU XOR |
| 135 | +//! 00000008 S skipping 0x07 bytes |
| 136 | +//! 00000010 4C MOVE S A |
| 137 | +//! 00000011 FF HALT |
| 138 | +//! ``` |
| 139 | +//! |
| 140 | +//! ## [`pir-8-emu`](https://rawcdn.githack.com/LoungeCPP/pir-8-emu/man/pir-8-emu.1.html) |
| 141 | +//! |
| 142 | +//! The emulator in-of itself: |
| 143 | +//! |
| 144 | +//!  |
| 145 | +//! |
| 146 | +//! # Example programs |
| 147 | +//! |
| 148 | +//! Apart from the two forthlaid above, |
| 149 | +//! take a look at the [`test-data/`](https://github.com/LoungeCPP/pir-8-emu/tree/master/test-data) directory in the git repo, |
| 150 | +//! which contains a mix of assembler programs (`.p8a`), program binaries (`.p8b`), and derivations/hand-assemblies (`.diz`). |
| 151 | +//! |
| 152 | +//! # Native handlers |
| 153 | +//! |
| 154 | +//! For more information, |
| 155 | +//! consult the documentation on [`RawNativePortHandler`](binutils/pir_8_emu/struct.RawNativePortHandler.html). |
| 156 | +//! |
| 157 | +//! For examples, take a look at the [`handler-examples/`](https://github.com/LoungeCPP/pir-8-emu/tree/master/handler-examples) |
| 158 | +//! directory in the git repo. |
| 159 | +//! Running `make` at the root thereof *should* build them without much hassle, |
| 160 | +//! if it doesn't, please [open an issue](https://github.com/LoungeCPP/pir-8-emu/issues). |
| 161 | +//! |
| 162 | +//! The |
| 163 | +//! [`include/pir-8-emu/port_handler.h`](https://github.com/LoungeCPP/pir-8-emu/tree/master/include/pir-8-emu/port_handler.h) |
| 164 | +//! file contains C declarations. |
| 165 | +//! |
| 166 | +//! # Special thanks |
| 167 | +//! |
| 168 | +//! To all who support further development on [Patreon](https://patreon.com/nabijaczleweli), in particular: |
| 169 | +//! |
| 170 | +//! * ThePhD |
| 171 | +
|
1 | 172 | extern crate bear_lib_terminal; |
2 | 173 | #[macro_use] |
3 | 174 | extern crate downcast_rs; |
|
0 commit comments