Practice x86 Assembly, One Instruction at a Time

asmlab is a powerful and interactive command-line tool that lets you test out assembly commands in a simulated environment.

This project is a reimagining of the excellent asmrepl, but ported to Rust with the following features :

• Simulated CPU: A virtual x86 environment where you can execute instructions and observe their effects on registers, flags, and memory.
• Multiple Modes: Seamlessly switch between modes to enhance your assembly experience:
  • Single-Instruction Mode: Execute and analyze one instruction at a time.
  • Multi-Instruction Mode: Write and run small assembly programs.
  • Calculator Mode: Perform arithmetic, bitwise, and trigonometric calculations, along with base conversions.
  • Script Mode: Define variables, use functions, and write scripts with an APL-inspired syntax.
• Syntax Highlighting: Code input is highlighted for improved readability.
• Comprehensive Instruction Set: Supports a wide range of x86 instructions, covering common operations and a few advanced instructions as well.
• Visual Register Representation: See the binary representation of registers for a deeper understanding of bit-level operations.

1. Clone the Repository:

   git clone git@github.com:StratusQuo/assemblyrepl.git

2. Build the Project:

   cd assemblyrepl
   cargo build

3. After building with Cargo:

Run the app with cargo run or copy the asmlab executable from the target/release directory to a directory in your PATH:

cp target/release/asmlab /usr/local/bin/

1. Run the REPL:

   cargo run

2. Explore! Use the following commands and features:

   • exit: Quit the REPL.
   • help: Display the help message (a list of available commands).
   • cpu: Show a compact view of the CPU state, including register values and flags.
   • state: Display a detailed view of the CPU state, with register values visualized in binary.

   Single-Instruction Mode (Default):

   
   • Enter a single assembly instruction (e.g., mov rax, 5) and press Enter to assemble and execute it.
   • Type a register name (e.g., rax) to see its value.
   • Use the memory command to inspect memory:
     • memory 0x100: Dumps 16 bytes in hexadecimal starting at address 0x100.
     • memory 0x100 -s 32: Dumps 32 bytes starting at address 0x100.
     • memory 0x100 -d: Dumps 16 bytes in decimal starting at 0x100.

   Multi-Instruction Mode:

   Type :multi to enter multi-line mode:

   
   • Enter your assembly instructions (one instruction per line)
   • An empty line indicates the end of your code block.
   • Type run to assemble and execute the code you've entered.

   Calculator Mode:

   Type :calc to enter calculator mode:

   

   In calc mode you can perform the following calculations and conversions using the below commands:

   • hex <value>: Convert a hexadecimal value to decimal and binary.
   • bin <value>: Convert a binary value to decimal and hexadecimal.
   • dec <value>: Convert a decimal value to hexadecimal and binary.
   • and <value1> <value2> ...: Perform a bitwise AND operation on the given values.
   • or <value1> <value2> ...: Perform a bitwise OR operation on the given values.
   • xor <value1> <value2> ...: Perform a bitwise XOR operation on the given values.
   • not <value>: Perform a bitwise NOT operation on the value.
   • sin <angle>: Calculate the sine of the angle (in degrees).
   • cos <angle>: Calculate the cosine of the angle (in degrees).
   • tan <angle>: Calculate the tangent of the angle (in degrees).
   • <value1> + <value2>: Add two values.
   • <value1> - <value2>: Subtract two values.
   • <value1> * <value2>: Multiply two values.
   • <value1> / <value2>: Divide two values.
   • shl <value> <amount>: Shift the bits of the value left by the specified amount.
   • shr <value> <amount>: Shift the bits of the value right by the specified amount.
   • rol <value> <amount>: Rotate the bits of the value left by the specified amount.
   • ror <value> <amount>: Rotate the bits of the value right by the specified amount.
   • twos <value>: Calculate the two's complement of a value.
   • float_to_ieee <value>: Convert a floating-point number to its IEEE 754 representation.

   Script Mode:

   Type :script to enter script mode:

   

   Note: There's still a lot of work to be done here -- there should be some fixes coming soon to make this mode more useful.

   • Define variables and write multi-line scripts that can use the following arithmetic & APL operators:
     • decimal <register>: Display the decimal value of a register.
     • <variable> → <value>: Assign a value to a variable.
     • <value1> + <value2>: Add two values.
     • <value1> - <value2>: Subtract two values.
     • <value1> × <value2>: Multiply two values.
     • <value1> ÷ <value2>: Divide two values.
     • <value1> ∧ <value2>: Bitwise AND.
     • <value1> ∨ <value2>: Bitwise OR.
     • <value1> ⊻ <value2>: Bitwise XOR.
     • ⌽ <value> <amount>: Rotate the bits of the value left by the specified amount.
     • ↑ <value> <amount>: Shift the bits of the value left by the specified amount.
     • ↓ <value> <amount>: Shift the bits of the value right by the specified amount.
     • ? <address>: Get the value at a memory address.
     • ι <end>: Create a range from 0 to <end>.
     • ι <start> <end>: Create a range from <start> to <end>.

Single Instruction Mode:

>> mov rax, 10
>> add rax, 5
>> rax
Rax: 0x000000000000000f

Multi-Instruction Mode:

>> :multi
.. mov rax, 1
.. mov rbx, 2
.. add rax, rbx
.. run
Executing: mov rax, 1
Assembled bytes: [48, c7, c0, 01, 00, 00, 00]
Instruction executed.
Executing: mov rbx, 2
Assembled bytes: [48, c7, c3, 02, 00, 00, 00]
Instruction executed.
Executing: add rax, rbx
Assembled bytes: [48, 01, d8]
Instruction executed.
All instructions executed successfully.
>> rax
Rax: 0x0000000000000003

Calculator Mode:

>> :calc
>> hex ff
Hex: 0xff
Decimal: 255
Binary: 0b11111111
>> 10 + 20
Result: 30
>> sin 45
Result: 0.7071067811865475 

Script Mode:

>> :script
.. count → 10
count ← 10
.. count + 5
Result: 15
.. decimal rax
RAX in decimal: 3

Contributions are welcome! If you find bugs, have feature suggestions, or want to contribute to the codebase, please open an issue or submit a pull request on GitHub.

This project is licensed under the MIT License.