tgtakaoka/libasm

C++ library of assembler / disassembler that can run on embedded system

libasm: cross assemble/disassemble library

The libasm allows assembling and disassembling supported retro CPUs on a small environment (less than 9kB-17kB Flash and 350B RAM on AVR Arduino).

Assembler library interface

Assembling MC68HC11 instruction in string to binary can be done in a minute. You can also add symbol table lookup via SymbolTable interface.

#include <asm_mc6800.h>
libasm::mc6800::AsmMc6800 asm6800;
asm6800.setCpu("68HC11");

const char *text = "SUBD $90";
libasm::Insn insn{0x1000};

asm6800.encode(text, insn);
assert(insn.getError() == OK);
assert(insn.address()  == 0x1000);
assert(insn.length()   == 2);    // direct addressing
assert(insn.bytes()[0] == 0x93); // SUBD
assert(insn.bytes()[1] == 0x90); // $90

Disassembler library interface

To disassemble MC68000 binaries, you need to wrap memory by ArrayMemory or implements your own DisMemory interface to feed binaries. You can also add symbol table lookup via SymbolTable interface.

#include <dis_mc68000.h>
libasm::mc68000::DisMc68000 dis68k;
dis68k.setOption("relative", "true");

const uint16_t words[] = {0047372, 0x1232};
const libasm::ArrayMemory memory{0x1000, words, sizeof(words)};
libasm::DisMemory dismem = memory.iterator();
libasm::Insn insn{dismem.address()};
char opr[80];

dis68k.decode(dismem, insn, opr, sizeof(opr));
assert(insn.getError() == OK);
assert(insn.address()  == 0x1000);
assert(std::string(insn.name()) == "jmp");
assert(std::string(opr) == "(*+$1234,pc)");

Arduino sketch examples

There are assembler and disassembler example sketches you can try to run on actual Arduino board at examples.

Assembler command line interface

On POSIX environment, assembler command line interface is provided. It can generate Intel HEX or Motorola S-Record output.

libasm assembler (version 1.6.47)
usage: asm [-o <output>] [-l <list>] <input>
  -C <CPU>    : target CPU
                MC6800 MB8861 MC6801 HD6301 MC68HC11 MC6805 MC146805
                MC68HC05 MC6809 HD6309 MOS6502 R65C02 G65SC02 W65C02S
                W65C816S i8039 i8048 i80C39 i80C48 MSM80C39 MSM80C48 i8051
                i8080 i8085 V30EMU Z80 Z8 Z86C Z88 TLCS90 INS8060 INS8070
                CDP1802 CDP1804 CDP1804A SCN2650 F3850 IM6100 HD6120
                TMS7000 TMS32010 TMS32015 i8086 i80186 V30 i8096 MC68000
                TMS9900 TMS9980 TMS9995 TMS99105 Z8001 Z8002 NS32032 MN1610
                MN1613 MN1613A
  -o <output> : output file
  -l <list>   : list file
  -S[<bytes>] : output Motorola S-Record format
  -H[<bytes>] : output Intel HEX format
              : optional <bytes> specifies data record length (max 32)
  -h          : use lowe case letter for hexadecimal
  -n          : output line number to list file
  -v          : print progress verbosely
  --<name>=<vale>
              : extra options (<type> [, <CPU>])
  list-radix      : set listing radix (8, 16)  (int)
  smart-branch    : optimize branch instruction  (bool)
  fpu             : floating point co-processor  (text)
  pc-bits         : program counter width in bit, default 13  (int, 6805)
  setdp           : set direct page register  (int, 6809)
  longa           : enable 16-bit accumulator  (bool, 6502)
  longi           : enable 16-bit index registers  (bool, 6502)
  reg-alias       : emit register alias regarding setrp value  (bool, Z8)
  setrp           : set register pointer  (int, Z8)
  setrp0          : set register pointer 0  (int, Z8)
  setrp1          : set register pointer 1  (int, Z8)
  optimize-index  : optimize zero index  (bool, Z8)
  use-register    : enable register name Rn  (bool, 1802)
  optimize-segment: enable optimizing segment override  (bool, 8086)
  short-direct    : enable optimizing direct addressing  (bool, Z8001)
  pmmu            : memory management unit  (text, 32032)

Disassembler command line interface

On POSIX environment, disassembler command line interface is provided. It can read Intel HEX or Motorola S-Record input.

libasm disassembler (version 1.6.47)
usage: dis -C <CPU> [-o <output>] [-l <list>] <input>
  -C <CPU>    : target CPU
                MC6800 MB8861 MC6801 HD6301 MC68HC11 MC6805 MC146805
                MC68HC05 MC6809 HD6309 MOS6502 R65C02 G65SC02 W65C02S
                W65C816S i8039 i8048 i80C39 i80C48 MSM80C39 MSM80C48 i8051
                i8080 i8085 V30EMU Z80 Z8 Z86C Z88 TLCS90 INS8060 INS8070
                CDP1802 CDP1804 CDP1804A SCN2650 F3850 IM6100 HD6120
                TMS7000 TMS32010 TMS32015 i8086 i80186 V30 i8096 MC68000
                TMS9900 TMS9980 TMS9995 TMS99105 Z8001 Z8002 NS32032 MN1610
                MN1613 MN1613A
  -o <output> : output file
  -l <list>   : list file
  <input>     : file can be Motorola S-Record or Intel HEX format
  -A start[,end]
              : disassemble start address and optional end address
  -r          : use program counter relative notation
  -h          : use lower case letter for hexadecimal
  -u          : use upper case letter for output
  -v          : print progress verbosely
  --<name>=<vale>
              : extra options (<type> [, <CPU>])
  list-radix      : set listing radix (8, 16)  (int)
  relative        : program counter relative branch target  (bool)
  c-style         : C language style number constant  (bool)
  intel-hex       : Intel style hexadecimal  (bool)
  origin-char     : letter for origin symbol  (char)
  pc-bits         : program counter width in bit (default 13)  (int, 6805)
  longa           : enable 16-bit accumulator  (bool, 6502)
  longi           : enable 16-bit index registers  (bool, 6502)
  indirect-long   : [] for indirect long operand  (bool, 6502)
  work-register   : prefer work register name than alias address  (bool, Z8)
  use-sharp       : use # (default =) for immediate  (bool, 8070)
  use-register    : use register name Rn  (bool, 1802)
  ignore-literal  : Ignore literal constant  (bool, 6100)
  segment-insn    : segment override as instruction  (bool, 8086)
  string-insn     : string instruction as repeat operand  (bool, 8086)
  use-absolute    : zero register indexing as absolute addressing  (bool, 8096)
  short-direct    : use |addr| for short direct notation  (bool, Z8001)
  segmented-addr  : use <<segment>> notation  (bool, Z8001)
  ioaddr-prefix   : I/O address prefix # (default none)  (bool, Z8001)
  pcrel-paren     : addr(pc) as program counter relative  (bool, 32032)
  external-paren  : disp2(disp(ext)) as external addressing  (bool, 32032)
  stropt-bracket  : string instruction operand in []  (bool, 32032)
  float-prefix    : float prefix 0F/0L (default none)  (bool, 32032)

Supported host environment

• Arduino (avr, megaavr, samd, teensy)

• PlatformIO (atmelavr, atmelmegaavr, atmelsam, teensy)

• Linux, macOS (C++14)

More information about this library can be found at GitHub

libasm's Issues

[ASM] Improve error message

Improve error reporting.

• More precise errorAt() reporting.
• Translate error number to text message.

[6309] can't assemble TFM D,X+ and OIM #$20,W,X

• "TFM D,X+" is tokenized as "D,X" and "+"
• "OIM #$20,W,X" is tokenized as "#$20" and ",W" and ",X"

Support Macro feature

Output ELF format support

It would be great if libasm generate ELF format file as an output binary with a relocation table.

Improve installation method

[Z8] Support SETRP pseudo

Currently only 0~15 of 8-bit register address specified as assembler operand are converted to work register Rn or @rn.
we must support SETDP or ASSUME RP:nn directive.

[Z8000] Add Z8000 CPU Assembler/Disassembler

[Doc] Add documentation

• More attractive README.md
• TUTORIAL.md
• ARDUINO.md

Add to Arduino Library Manager

[8086] Add i8086 Assembler/Disassembler

[TMS9900] Support TMS99900

Improve assembler output binary when error happens

See the change comment of d083fbe568.

[ASM] Accepts dot as prefix of directive

Coding for tmp96c141 processor tlcs900 family

Hi Professor
I have a tmp96c141 processor.
How can I write code for this processor with your library in the Arduino environment?
please guide me . I really need coding for tmp96c141 from the tlcs 900 family!
Thank.
mail: [email protected]

[NS32K] Add NS32000 CPU Assembler/Disassembler

Improve error message

Command line interface should display much descriptive error message than just a number.
And listing file should be generated even there is an error.

Assembler directives don't work

After release 1.6.29, libasm assembler command line interface asm doesn't properly handle assembler directives.
Such as FCB in 6502.

TMS320C10 support

Supporting early 16bit DSP seems interesting.

libasm as wasm backend

Using libasm as wasm backend to provide assembler and disassembler web interface.

Release 1.6.35 doesn't work on AVR

The release works fine on x86 and arm, but due to unknown bugs in libasm related to PROGMEM, it would not work on AVR architecture.

[TEST] Add regression test for command line interface

[ASM] Support warning message

Add PlatfomIO CI action

expresions in assembler numeric evaluation & c header output & stdout

Is it possible to do math in mediate constants?

For example take the low or high bytes from a label's address.
In 6502
lda # high byte of 'return'
sta some high byte vector location
lda# low byte of 'return'
sta some low byte vector location
etc

.return RTI

In the BBC Micro BASIC's build in 6502 assembler I would use
LDA # return DIV 256
LDA # return MOD 256

I would also find it useful if asm could generate c header file like this. Probably the prefix string 'at' could be a parameter.
const unsigned char atFFE0[] =
{
0xFF, 0xFE, 0xFD, 0xFC, 0xFB, 0xFA, 0xF9, 0xF8, 0xF7, 0xF6, 0xF5
};

Also '-' as a file name for 'use std out' would be handy to pipeline the processing of the hex file output for example.

Excellent work though, looking forward to using ins8060 and ins8070 modes.

[Arduino/ARM] compiler warning; dereferencing type-punned pointer will break strict-aliasing

Compiling Arduino example code targeting for ARM/Arduino spits a lot of compiler warning about dereferencing type-punned pointer.
pgm_read_byte, pgm_read_word, pgm_read_otr #define macro in config_host.h are the cause. And table_base.h should also be fixed.

[6800/Asm] Assembler wrongly accepts instruction without A or B accumulator

6800 Assembler correctly accepts

LDA A #$01
LDA A,#$02
LDAA  #$03
LDA B #$04
LDA B,#$05
LDAB  #$06

but also wrongly accepts

LDA   #$07

as ```LDAA``.
This should be an error.

Specify start address within input file and offset to add/subtract to address from input file in disassembler.

Thank you for your time and effort on this project.

I give you shout-out on my INS8073 blog page at [https://8073sbc.wordpress.com/2021/07/27/additional-tids-and-bits-to-add/]

I think the features suggested in the title would be a great enhancement to the dissassembler in CLI mode.

Peace and blessings,
JQ

Read ELF format as a disassembler input

The libasm disassembler should support ELF format as it's input, probably with a relocation table support.

[8051] Add 8051 CPU Assembler/Disassembler

[TEST] Improve auto test generator.

Currently test/gen command can generate fairly good auto-generated test assemble source for 8-bit CPU. Since 16-bit CPU's instruction usually has multiple bit-fields, scanning by simply incrementing instruction "value" doesn't work well. Need to find a good way to

• find bit-fields in instruction code
• iterate multiple bit-fields
• omit similar test cases which might appear not consecutively.

My target is the TMS70C02 processor. This is what seems to work:

Report from https://github.com/electrickery

My target is the TMS70C02 processor. This is what seems to work:

For constants, libasm seems to use C-type presentations

Directives:
ORG
INCLUDE "assemblyHeader.asm"
EQU
DATA

Constant presentations:
%>0B immediate hex number
%0x0B immediate hex number
%0b01010101 immediate binary number
%!123 immediate 'not 123'
%030 immediate decimal number

In EQU declarations the 'nnnh' presentation is supported, but not in constants
used in code mnemonics.
The '*' comment character is supported but only as the first,
non-space character on the line

Bytes in memory use the DATA PseudoOp, text requires single quotes:
MSG_USAGE DATA CR, LF, 'H - this help text', CR, LF, PRMPT, EOL

[Z8] Support Super8 (Z88xx)