naken_asm / naken_util
mike@mikekohn.net
http://www.mikekohn.net/micro/naken_asm.php

-------------------------------------------------------------------------

SUPPORTED CPU'S

CPU                 Author
65xx                Joe Davisson
680x                Michael Kohn 
68HC08              Michael Kohn 
680x0               Michael Kohn 
8051/8052           Michael Kohn
ARM                 Michael Kohn
AVR8                Michael Kohn
dsPIC/PIC24         Michael Kohn
MIPS                Michael Kohn
MSP430/MSP430X      Michael Kohn
STM8                Michael Kohn
THUMB               Michael Kohn
TMS1000/TMS1100     Michael Kohn
TMS9900             Michael Kohn
Z80                 Michael Kohn

-------------------------------------------------------------------------

COMPILING

By default the configure script will include support for all CPU's.  If
only a subset of CPU's is desired, the --enable-<cpu arch> option can
be added to the configure script.  Type ./configure --help for all options.
It's recommended that libreadline dev files are installed.  If they are
installed naken_util in interactive mode will allow the up-arrow to
bring back previous commands.  On Ubuntu/Debian this can be installed
by typing:  sudo apt-get install libreadline-dev

To compile naken_asm and naken_util (the disassembler / simulator) type:

./configure
make

As of 2013-Feb-23 there is no installer yet.  The binaries can be copied
to /usr/local/bin.  This will be fixed later.

-------------------------------------------------------------------------

ASSEMBLING

Usage: naken_asm [options] <infile>
   -o <outfile>
   -h             [output hex file]
   -e             [output elf file]
   -b             [output binary file]
   -d             [create .ndbg debug file]
   -l             [create .lst listing file]
   -I             [add to include path]

To compile a simple program, from the naken_asm directory type:

./naken_asm -I include/msp430_old -o launchpad_blink.hex -l testing/msp430/launchpad_blink.asm

The -h option is not needed since the default output file type is hex format.
If ELF is desired the -e option can be used with -o launchpad_blink.elf.
In order to assemble launchpad_blink.asm, an include file is required.
The -I option gives a path to the include file.  The -l option is highly
recommended since it creates a file that combines the original source code
with the same code disassembled.  This can be quite useful for debugging,
plus if there happens to be a problem with the assembler it can help show
what's wrong.  If the naken_asm can figure out cycle counts, the lst file
will also display this.

MSP430 is the default CPU, although it's still recommended to the use the
.msp430 directive at the top of the file.  If another CPU is desired to
assemble against, for example if this was a dsPIC program, the directive
.dspic can be placed at the top of the program.  All assembler directives
are listed below.

The -d option will create a .ndbg file which will help naken_util when
it disassembles to match addresses with symbols.  I may remove this
feature in the future and just rely on the symbol being included in the
ELF file.

To disassemble a program:

./naken_util -disasm launchpad_blink.hex

The simulator (as of the writing of this file only MSP430 is supported) allows
the user to show how their program will run. It gives a view of all the
registers and how many CPU cycles have passed, along with the current
instruction that executed and the next few in memory. To test the simulation,
after assembling launchpad.asm type:

./naken_util launchpad_blink.hex
speed 1
run

This will load the laundpad_blink.hex file and set the CPU speed to 1Hz.
The run command of course will start the simulation. To pause it just press
Ctrl-C. To run in single step mode:

speed 0
run

One instruction is executed and the simulator breaks. Pressing enter or
typing 'run' again will execute one more instruction. If there is a
function needing to be profiled at location 0xf010, typing: call 0xf010
will execute it. The program will stop running at the RET of the function.

Three other useful commands are call, push, and set. To push something on
the stack just do: push 0x1000 for example to push 0x1000 to the stack.
To set the value of a register: set pc=1000 or set r5=0xffff. To call a
function: call 0xf034 to call a function at location 0xf034. This pushes
the return address 0xffff on the stack and sets PC to 0xf034. When the
simulator sees PC==0xffff it returns back to you so the number of clock
cycles it took to run the function.

There are 4 commands for reading and writing memory: bprint, wprint, bwrite,
wwrite. So to write 5 bytes to location 0x1000, I could type:

bwrite 0x1000 100 102 143 0 5

It can confirm it's written by typing: bprint 0x1000

For reading and writing word sized data, wprint and wwrite work the same way.

As of March 16, 2014, I added a -run command to naken_util for MSP430.
A program can now be assembled and then run directly from the command-line
without entering the simulator:

naken_util -run program.hex

If when the program hits a ret instruction that didn't have a matching
call instruction, the program will stop and the registers will be dumped
along with number of cycles passed.  This was added for automated testing
in Java Grinder but could be pretty useful other places.

-------------------------------------------------------------------------

SYNTAX

Like other MSP430 assemblers, naken430asm accepts C style .define, .ifdef,
.if defined(). An example would be:

.define BLAH 50
.define SOMETHING

Alternatively, to help with compatibility with include files from other
assemblers .define and .include can be written as #define and #include:

#define BLAH 50

To test for a definition the following code works:

.ifdef SOMETHING
  mov.w r1, r12
.else
  mov.w r3, r12
.endif

.if defined(SOMETHING) && !defined(ANOTHER) && BLAH>50
  mov.w @r12+, r3
.endif

Standard assembler syntax "equ" is also accepted too:

BLAH equ 50

Also .macro / .endm works like the following:

.macro BLAH
  mov.w #5, r10
  mov.w #6, r11
.endm

or also:

.macro BLAH(a,b)
  mov.w #a, r10
  mov.w #b, r11
.endm

Data bytes and words can be done with db (or dc8) and dw (or dc16). Chunks
of databytes that default to 0 can be set with ds, ds8, ds16. Strings in db
sections are not null terminated. For example:

db "Copyright 2010 by Michael Kohn", 0, 5, -9
dw 100, 2000, 400, 9

Files can be included with a .include "filename.h".

Comments can be done with a standard assembler ; (semicolon) or with
standard C's // and /* */ again to help with compatibility with other
assembler's include files.

As with other assemblers, org or .org is used to tell the assembler what
address a piece of code starts on.

Hex number can be written with either 0xFFD2 or 0FFD2h. Octal numbers can
either start with 0 or end with q: 070 or 70q. Binary numbers can just end
with a b: 11110000b.  For CPU's such as 6500 and STM8, hex numbers can
be written with a dollar sign ($10 is 0x10 for example).

-------------------------------------------------------------------------

DIRECTIVES

All directives can start with a . or a #.  The # was used for compatibility
with some include files.

CPU Selection:
.65xx            6502, 6510, and any other 6500 series cpu
.680x            6800
.68hc08          68HC08
.680x0           Motorola 68000
.8051 or .8052   8051/8052/MCS-51
.arm             All ARM CPU's
.avr8            Atmel AVR8
.dspic           dsPIC
.mips            MIPS including PIC32
.msp430          MSP430
.mps430x         MSP430X
.pic24           PIC24
.stm8            STM8
.thumb           THUMB
.tms1000         TMS1000/TMS1200/TMS1070/TMS1270
.tms1100         TMS1100/TMS1300
.tms9900         TMS9900
.z80             Z80

Assembler Directives:
.align <16 or 32>           Align to 16 bit or 32 bit boundary
.ascii <text>               Insert ASCII chars at memory address
.asciiz <text>              Same as .ascii but zero padded
.big_endian                 Store databytes in big endian format
.binfile "binarydata.bin"   Read in binary file and insert at memory address
.db <data bytes>            8 bit data bytes
.define <macro>             Define a C style #define macro
.dw <data words>            16 bit data bytes
.ds8 <data byte count>      Reserve <count> bytes
.ds16 <data words count>    Reserve <count> 16 bit words
.else <exression>           Else for .if or .ifdef
.endif                      Close an .ifdef or .if
.endm                       End of macro definition
.export                     Export symbol so it shows up in ELF file
.if <exression>             Evaluate an expression and assemble code if true
.ifdef <exression>          If defined, can be used with .define
.ifndef <exression>         If not defined, can be used with .define
.include "includefile.inc"  Include a file of asm source code
.macro <name> (opt. params) Define a macro (should end with .endm
.org <address>              Address where next assembled bytes are written to
.set <symbol>=<value>       Create or modify symbol's value (excluding labels)