https://github.com/hlorenzi/customasm

💻 An assembler for custom, user-defined instruction sets! https://hlorenzi.github.io/customasm/web/
https://github.com/hlorenzi/customasm

asm assembler assembly assembly-language bytecode bytecode-compiler compiler custom customizable instruction-set instruction-set-architecture machine-code microprocessor processor-architecture rust rust-lang user-defined virtual-machine vm webassembly

Last synced: 3 days ago
JSON representation

💻 An assembler for custom, user-defined instruction sets! https://hlorenzi.github.io/customasm/web/

• Host: GitHub
• URL: https://github.com/hlorenzi/customasm
• Owner: hlorenzi
• License: apache-2.0
• Created: 2016-07-24T18:33:07.000Z (over 8 years ago)
• Default Branch: main
• Last Pushed: 2024-12-01T17:58:05.000Z (20 days ago)
• Last Synced: 2024-12-12T02:04:10.614Z (10 days ago)
• Topics: asm, assembler, assembly, assembly-language, bytecode, bytecode-compiler, compiler, custom, customizable, instruction-set, instruction-set-architecture, machine-code, microprocessor, processor-architecture, rust, rust-lang, user-defined, virtual-machine, vm, webassembly
• Language: Rust
• Homepage:
• Size: 5.17 MB
• Stars: 729
• Watchers: 17
• Forks: 57
• Open Issues: 32
• Metadata Files:
  • Readme: README.md
  • Funding: .github/FUNDING.yml
  • License: LICENSE.txt

Awesome Lists containing this project

• StarryDivineSky - hlorenzi/customasm

README

        
# customasm

`customasm` is an assembler that allows you to provide your own **custom

instruction sets** to assemble your source files! 

It can be useful, for example, if you're trying to test the bytecode of a new virtual machine,

or if you're eager to write programs for that new microprocessor architecture 

you just implemented in an FPGA chip!

[![crates.io][badge-cratesio-img]][badge-cratesio-url]

[![Latest Release][badge-latest-img]][badge-latest-url]

[![Releases][badge-downloads-img]][badge-downloads-url]

[![Discord][badge-discord-img]][badge-discord-url]

[![GitHub Sponsor][badge-github-sponsor-img]][badge-github-sponsor-url]

[badge-cratesio-img]: https://img.shields.io/crates/v/customasm

[badge-cratesio-url]: https://crates.io/crates/customasm

[badge-latest-img]: https://img.shields.io/github/v/release/hlorenzi/customasm

[badge-latest-url]: https://github.com/hlorenzi/customasm/releases

[badge-downloads-img]: https://img.shields.io/github/downloads/hlorenzi/customasm/total

[badge-downloads-url]: https://github.com/hlorenzi/customasm/releases

[badge-github-sponsor-img]: https://img.shields.io/github/sponsors/hlorenzi?label=GitHub%20Sponsors&logo=GitHub

[badge-github-sponsor-url]: https://github.com/sponsors/hlorenzi

[badge-discord-img]: https://img.shields.io/discord/394999035540275222?label=Join%20the%20Discord%20server!&logo=discord

[badge-discord-url]: https://discord.com/invite/pXeDXGD

[🖥️ Try it right now on your web browser!](https://hlorenzi.github.io/customasm/web/)

[🕹️ Check out an example project](/examples/nes_colors.asm) which targets the NES!

[⌨️ Install the VSCode syntax highlight extension!](https://marketplace.visualstudio.com/items?itemName=hlorenzi.customasm-vscode)

[❤️ Support the author!](https://accounts.hlorenzi.com/supporters)

## Documentation

[📚 Check out the wiki](https://github.com/hlorenzi/customasm/wiki)

for a changelog, documentation, and a how-to-start guide!

[💲 Check out the command-line help!](/src/usage_help.md) (Better formatted on the command-line itself)

## Installation

You can install directly from *crates.io* by running `cargo install customasm`.

Then the `customasm` application should automatically become available in your

command-line environment.

You can also download pre-built executables from the

[Releases section](https://github.com/hlorenzi/customasm/releases).

You can compile from source yourself by first cloning the repository and

then simply running `cargo build`.

There's also a battery of tests available at `cargo test`.

## Example

Given the following file:

```asm

#ruledef

{

    load r1, {value: i8} => 0x11 @ value

    load r2, {value: i8} => 0x12 @ value

    load r3, {value: i8} => 0x13 @ value

    add  r1, r2          => 0x21

    sub  r3, {value: i8} => 0x33 @ value

    jnz  {address: u16}  => 0x40 @ address

    ret                  => 0x50

}

multiply3x4:

    load r1, 0

    load r2, 3

    load r3, 4

    

    .loop:

        add r1, r2

        sub r3, 1

        jnz .loop

    

    ret

```

...the assembler will use the `#ruledef` directive to convert the

instructions into binary code:

```asm

 outp | addr | data (base 16)

  0:0 |    0 |          ; multiply3x4:

  0:0 |    0 | 11 00    ; load r1, 0

  2:0 |    2 | 12 03    ; load r2, 3

  4:0 |    4 | 13 04    ; load r3, 4

  6:0 |    6 |          ; .loop:

  6:0 |    6 | 21       ; add r1, r2

  7:0 |    7 | 33 01    ; sub r3, 1

  9:0 |    9 | 40 00 06 ; jnz .loop

  c:0 |    c | 50       ; ret

```