#assembly #simulator #lc3 #object-file #parser #isa #cs

lc3-ensemble

LC-3 parser, assembler, and simulator intended for Georgia Tech's CS 2110 course

17 releases (8 breaking)

0.9.2 Dec 20, 2024
0.9.1 Oct 17, 2024
0.8.1 Oct 16, 2024
0.5.0 Jun 29, 2024

#68 in Simulation

Download history 130/week @ 2024-09-13 501/week @ 2024-09-20 274/week @ 2024-09-27 87/week @ 2024-10-04 490/week @ 2024-10-11 145/week @ 2024-10-18 2/week @ 2024-10-25 3/week @ 2024-11-01 3/week @ 2024-11-08 20/week @ 2024-12-06 6/week @ 2024-12-13 175/week @ 2024-12-20

201 downloads per month

MIT license

350KB
6K SLoC

Rust 5.5K SLoC // 0.1% comments Assembly 638 SLoC // 0.0% comments

Ensemble 🎷⚙️ (LC-3 parser, assembler, and simulator)

Ensemble is a parser, assembler, and simulator library for the LC-3 ISA, written in Rust.

This project, while mostly for general use, is mainly used for the lc3-ensemble-test and LC3Tools projects.

Refer to the documentation for additional support.


lib.rs:

A LC-3 parser, assembler, and simulator.

This is meant to be a general suite to use LC-3 assembly (meant as a backend for Georgia Tech's CS 2110 LC3Tools).

Usage

To convert LC-3 source code to an object file, it must be parsed and assembled:

use lc3_ensemble::parse::parse_ast;
use lc3_ensemble::asm::{assemble, assemble_debug, ObjectFile};

let code = "
    .orig x3000
    AND R0, R0, #0
    AND R0, R0, #7
    HALT
    .end
";
let ast = parse_ast(code).unwrap();

// Assemble AST into object file:
let obj_file: ObjectFile = assemble(ast).unwrap();
// OR:
let obj_file: ObjectFile = assemble_debug(ast, code).unwrap();

Once an object file has been created, it can be executed with the simulator:

use lc3_ensemble::sim::Simulator;

let mut simulator = Simulator::new(Default::default());
simulator.load_obj_file(&obj_file);
simulator.run().unwrap(); // <-- Result can be handled accordingly

If more granularity is needed for simulation, there are also step-in and step-out functions. See the [sim] module for more details.

Dependencies

~2.5MB
~22K SLoC