Crate yaxpeax_nd812

Expand description

`yaxpeax-nd812`, a decoder for the ND812 instruction set

the ND812 instruction set is used in the Nuclear Data ND812 microcomputer, first introduced in 1970. the ND812 and associated additional hardware (such as the ND4410) were used for scientific applications and it seems relatively few programs for this equipment has survived to the present day.

interesting for yaxpeax reasons, the ND812 is a 12-bit machine. yaxpeax-nd812 decodes units of ND812Word, consulting only the low 12 bits of the contained u16. ND812Word then requires an impl Reader<u16, ND812Word> to decode from; there is a default impl to read ND812Word from a regular &[u8], but a more comprehensive ND812 simulator would need to also reproduce the wrap-at-4k-boundary behavior from the real hardware.

the actual packing of 12-bit words may also be of interest. i couldn’t find any ND812 programs online as binary, even as binary images to be loaded by simulators - i couldn’t really find any ND812 simulators available online either. so my best guess for a reasonable binary format is to do what people do with PDP-8 (also 12-bit) binary blobs, with 12-bit words in two-byte units of memory.

lastly, thank goodness for bitsavers.org. i found many of the manuals and documents for the ND812 in scattered places online, but bitsavers has them all in one place. the reference there helped me answer a few questions about missing documents, and led me to finding program ND41-1085 in the IM41-1085 manual for x-ray analysis. it turned out that the best test cases were reference programs from Nuclear Data themselves.

reference materials:

shasum -a 256 IM*
3a4ccbdd898ff071636d14af908e2386d6204b77d39a546f416f40ad7ad890fa
  IM41-0001_Software_Instruction_Manual_BASC-12_General_Assembler_Jan71.pdf
39dcb814862c385986aee6ff31b4f0a942e9ff8dcaac0046cbcba55f052d42e5
  IM41-0002-04_Software_Instruction_Manual_ND812_Symbolic_Text_Editor_Nov72.pdf
d5380bed1407566b491d00e654bc7967208fa71ef6daa7ec82e73805f671ff0a
  IM41-0059-00_NUTRAN_User_and_Programmers_Guide_Nov72.pdf
f508a4bb6a834352b1a391ac0dd851201dd6a6a5cfa6eec53aa4c6dbf86e088a
  IM41-1062-00_Software_Instruction_Manual_ND4410_Low_High_Speed_Paper_Tape_IO_Overlay_Program_Apr72.pdf
a1364c23ffadc4414c7b905cfce7cd4c0914a5b0d29b1726246a9d5d68d0aa7a
  IM41-8001-01_Software_Instruction_Manual_ND812_Diagnostics_Feb72.pdf
62013481aab174473ae1cbaed35d02eb7f22a05acd6c56ae36d166502925cb25
  IM41-8045-00_Software_Instruction_Manual_Hardware_Multipy_Divide_Test_Jun72.pdf
3cf00d268cab96eebda973b53b870fe761e83d2e61a733860094920b17d84b22
  IM88-0481-02_Hardware_Instruction_Manual_ND812_Teletype_Auto_Loader_Interface_Sep72.pdf

usage

the fastest way to decode an nd812 instruction is through InstDecoder::decode_slice():

use yaxpeax_nd812::InstDecoder;

let inst = InstDecoder::decode_u16(&[0o1122]).unwrap();

assert_eq!("adr j", inst.to_string());

opcodes and operands are available on the decoded instruction, as well as its length and operand count:

use yaxpeax_nd812::{InstDecoder, Operand, Opcode};

let inst = InstDecoder::decode_u16(&[0o1123]).unwrap();

assert_eq!("sbr j", inst.to_string());
assert_eq!(inst.operand_count(), 2);
assert_eq!(inst.len(), 1);
assert_eq!(inst.opcode(), Opcode::SubR);
assert_eq!(inst.operand(0), Operand::R);
assert_eq!(inst.operand(1), Operand::J);

additionally, yaxpeax-nd812 implements yaxpeax-arch traits for generic use, such as yaxpeax_arch::LengthedInstruction. yaxpeax_arch::Arch is implemented by the unit struct ND812. yaxpeax-nd812 does not decode from a U8Reader, like many other decodes, but does decode from an ND812Reader that can be trivially constructed from a U8Reader.