smart-tools
v1.1.2
Published
S.M.A.R.T. (Simplified Memory & Assembly Reference Tool) - A set of tools designed for educational purposes to provide a clear understanding of assembly language and virtual machine operations.
Downloads
1
Readme
SMART Tools
SMART (Simple Machine Assembly and Runtime Tools) is a comprehensive suite designed to introduce students to the world of assembly language and low-level computing. The primary goal of SMART Tools is to provide a simplified yet robust environment for students to grasp the foundational concepts of assembly programming without being overwhelmed by intricate details.
Web-based User Interface
You can try it out using the web-based user interface.
Why SMART Tools?
- Simplicity: SMART is designed to be straightforward, making it easier for beginners to understand the core concepts without getting lost in the complexities of real-world assembly languages.
- Comprehensive: While simple, SMART provides a complete experience, from writing code in the assembly language to running it on a virtual machine.
- Educational: The tools are tailored for educational purposes, ensuring that students not only learn how to write assembly but also understand the underlying principles.
Components
- Assembly Language: A simple yet powerful assembly language tailored for educational purposes. Dive deeper into its syntax, opcodes, and features in README.ASM.md.
- CLI Tools: A set of command-line utilities including an assembler, disassembler, and a virtual machine. Detailed usage and options can be found in README.CLI.md.
Quick Example
Here's a simple SMART assembly program that adds two numbers:
START: LOADA NUM1 ; Load the first number into register A
LOADB NUM2 ; Load the second number into register B
ADDB NUM1 ; Add the value in register A to register B
STOREA RESULT ; Store the result
END
NUM1: DATA 0x05 ; 5 in decimal
NUM2: DATA 0x03 ; 3 in decimal
RESULT: DATA 0x00
Running the Tools
To get started with SMART Tools, you'll first need to install them. Once installed, you can use the command-line interfaces to assemble, disassemble, and run your programs.
Tools Provided:
smart-assembler: This tool allows you to convert your assembly language programs into machine code. It takes an .asm file and produces an .obj file containing the binary representation of your program.
smart-disassemble: If you have a machine code program (in an .obj file) and you want to understand its assembly representation, this tool will help you convert it back into an .asm file.
smart-vm: This is a virtual machine that lets you run your machine code programs. It simulates the behavior of the SMART computer architecture, allowing you to execute and debug your programs in a controlled environment.
For a deeper understanding of what each tool does and the concepts behind them, please refer to the README.INFO.md.
Installation
Running container
podman run -it quay.io/yaacov/smart-tools
Installing using npm
npm install smart-tools
From source
Before you begin, ensure you have Node.js and npm (Node Package Manager) installed on your system. If not, you can download and install them from Node.js official website.
Once you have Node.js and npm set up:
- Clone the repository and navigate to the directory:
git clone <repository-url>
cd smart-tools
- Install the necessary dependencies:
npm install
- Run the code
# Run the tools from source
node src/smart-vm.mjs
# build the contaier image
podman build -t quay.io/yaacov/smart-tools .
# Run the container image
podman run -it quay.io/yaacov/smart-tools
Assembling a Program
To assemble a .asm file into a .obj binary:
smart-assembler path/to/yourfile.asm outputfile.obj
Disassembling a Program
To disassemble a .obj binary into a .asm file:
smart-disassemble path/to/yourfile.obj outputfile.asm
Or, to print the disassembled code to the console:
smart-disassemble path/to/yourfile.obj -
Running a Program
To run a .obj binary:
smart-vm path/to/yourfile.obj
For debugging and stepping through the program:
smart-vm path/to/yourfile.obj --debug
Remember, detailed information about the CLI tools, their options, and more examples can be found in README.CLI.md.
Similar Projects
While there are several projects aimed at teaching assembly language, SMART Tools stands out due to its simplicity and focus on foundational concepts. Some similar projects include:
- MIPS Assembly: A more complex assembly language used in MIPS processors. While powerful, it might be overwhelming for beginners.
- Little Man Computer (LMC): An instructional model of a computer. LMC is simple like SMART but lacks some of the features and opcodes provided by SMART.
The primary difference between SMART Tools and other projects is the balance between simplicity and comprehensiveness. While SMART is designed to be beginner-friendly, it doesn't compromise on providing a complete assembly programming experience.