yaacov / 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.

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?

1. 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.
2. Comprehensive: While simple, SMART provides a complete experience, from writing code in the assembly language to running it on a virtual machine.
3. 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

1. Assembly Language: A simple yet powerful assembly language tailored for educational purposes. Dive deeper into its syntax, opcodes, and features in README.ASM.md.
2. 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.

bitmap editor

smart-tools's Issues

throw error on wrong number of operands

throw error on wrong number of operands when compiling code

Sdd stck operations

modernize the ui look and feel

Expand & Enhance Example Documentation for Various Skill Levels

Hello Contributors! 🚀

Objective:

Enhance Smart Assembly's educational impact with improved and diversified example documentation.

Needs:

• Document Existing Examples: Ensure clarity and student-friendliness.
• Develop More Examples: Ranging from basic logic operators to advanced recursions, suitable for different learning stages.

Action Items:

• Enhance Current Examples: Add clear, educational comments explaining functionalities.
• Add New Examples: Implement clear, well-commented examples catering to varied skill levels, highlighting the expected understanding level.

Your Impact:

Your contributions will enrich the learning experiences for users of Smart Assembly, ensuring clear pathways for skill development.

🛠 Skills: Proficiency in Assembly language, ability to articulate technical processes clearly in comments.

add noop opcode

no op op code is an important op code

add option to set step time

when running in the user interface add option to set step time for each running step

add option to save and load

add option to save and load assembly code in the assembly editor

dinamically fetch opcodes and list of examples

dinamically fetch opcodes and list of examples from the compiler code instead of hard coding them in the ui