pir_8_emu/lib.rs
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 and assembly 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//! LOAD IMM WIDE C&D
40//! :label load-offset full message -1
41//!
42//! :label save loop
43//! MOVE D X
44//! LOAD IMM BYTE Y
45//! 1
46//! ALU ADD
47//! MOVE S D
48//! MOVE C X
49//! LOAD IMM BYTE Y
50//! 0
51//! ALU ADDC
52//! MOVE S C
53//! MADR WRITE C&D
54//!
55//! LOAD IMM BYTE A
56//! 0 ; port number
57//! LOAD IND B
58//! PORT OUT B
59//!
60//! MOVE B S
61//! COMP S
62//!
63//! LOAD IMM WIDE ADR
64//! :label load full end
65//! JMZG
66//! LOAD IMM WIDE ADR
67//! :label load full loop
68//! JUMP
69//!
70//! :label save end
71//! HALT
72//!
73//!
74//! :label save message
75//! :literal "*pounces on u* OwO what's whis?"
76//! ```
77//!
78//! If you'd rather use a more normal syntax, [CatPlusPlus](https://github.com/TheCatPlusPlus) has also made
79//! a [`fasm`-based assembler](https://github.com/TheCatPlusPlus/pir8/tree/master/Assembler):
80//!
81//! ```asm
82//! include 'pir8.finc'
83//!
84//! origin 0x0002
85//!
86//! load a, [0x0000]
87//! load b, [0x0001]
88//!
89//! top:
90//! move x, a
91//! move y, b
92//! sub
93//!
94//! jmpz exit
95//!
96//! move s, a
97//! comp b
98//!
99//! jmpl lt
100//!
101//! sub
102//! move a, s
103//! jump top
104//!
105//! lt:
106//! move y, a
107//! move x, b
108//! sub
109//! move b, s
110//! jump top
111//!
112//! exit:
113//! move d, a
114//! halt
115//! ```
116//!
117//! ## [`pir-8-disasm`](https://rawcdn.githack.com/LoungeCPP/pir-8-emu/man/pir-8-disasm.1.html)
118//!
119//! A dissassembler with a [`ndisasm`](https://www.nasm.us)-based frontend:
120//!
121//! ```plaintext
122//! $ pir-8-disasm -k 0x27,31 test-data/copy-any-length-literal-to-port.p8b
123//! 00000000 1E LOAD IMM C
124//! 00000001 00 D 0x00
125//! 00000002 1A LOAD IMM X
126//! 00000003 27 D 0x27
127//! 00000004 1B LOAD IMM Y
128//! 00000005 01 D 0x01
129//! 00000006 31 ALU SUB
130//! 00000007 4A MOVE S X
131//! 00000008 4F MOVE S D
132//! 00000009 7A MOVE D X
133//! 0000000A 1B LOAD IMM Y
134//! 0000000B 01 D 0x01
135//! 0000000C 30 ALU ADD
136//! 0000000D 4F MOVE S D
137//! 0000000E 72 MOVE C X
138//! 0000000F 1B LOAD IMM Y
139//! 00000010 00 D 0x00
140//! 00000011 32 ALU ADDC
141//! 00000012 4E MOVE S C
142//! 00000013 0D MADR WRITE C&D
143//! 00000014 1C LOAD IMM A
144//! 00000015 00 D 0x00
145//! 00000016 25 LOAD IND B
146//! 00000017 E5 PORT OUT B
147//! 00000018 69 MOVE B S
148//! 00000019 F1 COMP S
149//! 0000001A 1C LOAD IMM A
150//! 0000001B 00 D 0x00
151//! 0000001C 1D LOAD IMM B
152//! 0000001D 26 D 0x26
153//! 0000001E 0C MADR WRITE A&B
154//! 0000001F 14 JMZG
155//! 00000020 1C LOAD IMM A
156//! 00000021 00 D 0x00
157//! 00000022 1D LOAD IMM B
158//! 00000023 09 D 0x09
159//! 00000024 0C MADR WRITE A&B
160//! 00000025 17 JUMP
161//! 00000026 FF HALT
162//! 00000027 S skipping 0x1F bytes
163//! ```
164//!
165//! ## [`pir-8-emu`](https://rawcdn.githack.com/LoungeCPP/pir-8-emu/man/pir-8-emu.1.html)
166//!
167//! The emulator in-of itself:
168//!
169//! 
170//!
171//! # Example programs
172//!
173//! Apart from the two forthlaid above,
174//! take a look at the [`test-data/`](https://github.com/LoungeCPP/pir-8-emu/tree/master/test-data) directory in the git repo,
175//! which contains a mix of assembler programs (`.p8a`), program binaries (`.p8b`), and derivations/hand-assemblies (`.diz`).
176//!
177//! # Native handlers
178//!
179//! For more information,
180//! consult the documentation on [`RawNativePortHandler`](binutils/pir_8_emu/struct.RawNativePortHandler.html).
181//!
182//! For examples, take a look at the [`handler-examples/`](https://github.com/LoungeCPP/pir-8-emu/tree/master/handler-examples)
183//! directory in the git repo.
184//! Running `make` at the root thereof *should* build them without much hassle,
185//! if it doesn't, please [open an issue](https://github.com/LoungeCPP/pir-8-emu/issues).
186//!
187//! The
188//! [`include/pir-8-emu/port_handler.h`](https://github.com/LoungeCPP/pir-8-emu/tree/master/include/pir-8-emu/port_handler.h)
189//! file contains C declarations.
190//!
191//! # Special thanks
192//!
193//! To all who support further development on [Patreon](https://patreon.com/nabijaczleweli), in particular:
194//!
195//! * ThePhD
196
197extern crate bear_lib_terminal;
198#[macro_use]
199extern crate downcast_rs;
200#[macro_use]
201extern crate lazy_static;
202extern crate arraydeque;
203#[macro_use]
204extern crate const_cstr;
205extern crate num_traits;
206extern crate dlopen;
207extern crate serde;
208#[macro_use]
209extern crate clap;
210extern crate libc;
211extern crate dirs;
212extern crate toml;
213
214mod rw;
215
216pub mod vm;
217pub mod isa;
218pub mod util;
219pub mod micro;
220pub mod options;
221pub mod binutils;
222
223pub use self::rw::{ReadWriteMarker, ReadWritable};