Skip to content
Find file
Fetching contributors…
Cannot retrieve contributors at this time
791 lines (551 sloc) 21.6 KB
ARMIPS assembler v0.7c, released 11th December 2010
by Kingcom
#################################
# 0. TABLE OF CONTENTS #
#################################
1. Introduction
1.1 Motivation
1.2 Usage
1.3 Change log
2. General Information
3. Features
3.1 Files
3.2 Comments
3.3 Labels
3.4 equ
3.5 Math Parser
3.6 Load delay detection
3.7 Strings
3.8 Areas
4. Assembler Directives
4.1 General Directives
4.2 MIPS Directives
4.3 ARM Directives
5. Macros
5.1 Assembler defined MIPS macros
5.2 User defined macros
6. Known issues
#################################
# 1. INTRODUCTION #
#################################
1.1 Motivation
I started writing this assembler when I got into PSX hacking,
as the only available assemblers were less than user friendly.
This assembler is an attempt to fix of all of the problems
with currently available assemblers and to allow working with
several different code binaries in the same game. It won't
erase any code, it will just overwrite what the user wants
to overwrite.
In this second version, ARM/THUMB support is finally finished.
It can be used for both GBA and NDS and includes both
instruction sets. ARM has been implemented according to GBATEK
by Martin Korth, and most pseudo opcodes and aliases are
included (for example, mov for mcr/mrc and mrs/msr).
PS2 support is also planned. You can contact me on the
RomHacking.net forums. My nickname there is KC.
Thanks to Gemini for testing it and providing the initial idea.
He also wrote the sample assembly file.
1.2 Usage
The assembler is called from the command line, and the
arguments are as follows:
armips.exe code.asm [-temp tempfile.txt] [-sym symfile.sym]
Code.asm is the main file of your assembly code. It can
open and include other files, and basically do everything
you want. The optional -temp parameter specifies a
text file where all the temporary assembly data will be
written to for debugging purposes. It will look like this:
; 1 file included
; test.asm
00000000 .open "SLPM_870.50",0x8000F800 ; test.asm line 1
8000F800 .org 0x800362DC ; test.asm line 5
800362DC jal 0x801EBA3C ; test.asm line 7
800362E0 .Close ; test.asm line 9
The other optional parameter, -sym, allows you to specify
a file to output all the labels to. This can be used with
no$gba for easier debugging.
1.3 Change log
0.7c -Macros can now contain unique local labels
-area and no$gba debug message directives added
-sym output enhanced
-countless bugfixes
-no$gba debug message support
-full no$gba sym support
0.7b -ARM/THUMB support
-fixed break/syscall MIPS opcodes
-added check if a MIPS instruction is valid inside
a delay slot
-fixed and extended base detection
-added "." dummy label to the math parser to get the
current memory address
-added dcb/dcw/dcd directives
0.5b -Initial release
#################################
# 2. GENERAL INFORMATION #
#################################
The assembler includes the whole MIPS R3000 instruction
set, as well as the complete ARM7/ARM9 instruction set
used by GBA and NDS, both THUMB and ARM mode. There are
also several other features. Among these features are:
-a full fledged C-like math parser. It should behave
exactly like in any C/C++ code, including all the
weirdness. All immediate values can be specified by
an expression, though some directives can't use
variable addresses including labels
-you can open several files in a row, but only one
output file can be open at any time. You can specify
its address in memory to allow overlay support. Any
file can cross-reference any other included file
-labels and local labels (see 3.3)
-table support for user defined text encodings (see 3.7)
-several MIPS macros to make writing code easier and
faster (see 4.1)
-user defined macros (see 4.2)
-built-in checks for possible load delay problems (see 3.6)
-optional automatic fix for said problems by inserting
a nop between the instructions
-output of the assembled code to a textfile, with RAM
addresses and origin (see 1.2)
-a directive to ensure that data is not bigger than a
user defined size (see 3.8)
#################################
# 3. FEATURES #
#################################
3.1 Files
Unlike other assemblers, you don't specify the input/output
file as a command line argument. You have to open the file
in the source code, and also close it yourself. This was
done in order to support overlays, which are very common
in PSX and NDS games. Instead of only having one output file,
you can have as many as you need - each with its own address
in memory. The files can cross-reference each other without
any problems, so you can call code from other, currently
not opened files as well.
.Open "SLPS_035.71", 0x8000F800
; ...
.Close
.Open "System\0007.dat", 0x800CC000
; ...
.Close
3.2 Comments
Both ; and // are supported for comments.
3.3 Labels
There is support for both local and global labels. Local
labels are only valid in the area between the previous
and the next global label. Specific directives, like .org,
will also terminate the area. A label is defined by writing
a colon after its name. All labels can be used before they
are defined.
GlobalLabel: ; This is a global label
@@LocalLabel: ; This is a local label, it is only
; valid until the next global one
OtherGlobalLabel: ; this will terminate the area where
; @@LocalLabel can be used
b @@LocalLabel ; as a result, this will cause an error
A label name can contain all characters from A-Z and numbers.
However, it cannot start with a digit. All label names are
case insensitive.
3.4 equ
This works as a text replacement and is defined as follows:
@@StringPointer equ 0x20(r29)
There has to be a space before and after equ. The assembler
will replace any occurance of @@StringPointer with "0x20(r29)".
As it is a local equ, it will only do so in the current
section, which is terminated by any global label or specific
directives. This code:
@@StringPointer equ 0x20(r29)
lw a0,@@StringPointer
nop
sw a1,@@StringPointer
will assemble to this:
lw a0,0x20(r29)
nop
sw a1,0x20(r29)
There can be both global and local equs, but unlike normal
labels, they have to be defined before they are used.
3.5 Math Parser
A standard math parser with operator precedence and bracket
support has been implemented. It is intended to behave exactly
like any C/C++ parser and supports all unary, binary and
tertiary operators of the C language. Every numeral argument
can be given as an expression, including label names.
However, some directives do not support variable addresses,
so labels can not be used in expressions for them.
The following bases are supported:
$A, 0xA and 0Ah for hexadecimal numbers
0o12 and 12o for octal numbers
1010b for binary numbers
Everything else is interpreted as a decimal numbers, so a
leading zero does not indicate an octal number. Be aware that
every number has to actually start with a digit, unless you
use $ for hexadecimal numbers. For example, as FFh is a
perfectly valid label name, you have to write 0FFh in this case.
Labels, on the other hand, can not start with a digit.
A few examples:
mov r0,10+0xA+$A+0Ah+0o12+12o+1010b
ldr r1,=ThumbFunction+1
li v0,Structure+(3*StructureSize)
3.6 Load delay detection
This feature is still unfinished and experimental. It works
in most cases, though. On MIPS platforms, any load is
asynchronously delayed by one cycle. This means that the CPU
won't stall if you attempt to use it before - and instead
returns the old value on real hardware (emulators do not emulate
this, which makes spotting these mistakes even more difficult).
Therefore, the assembler will attempt to detect when such a
case happens. The following code would result in a warning:
lw a0,0x10(r29)
lbu a1,(a0)
This code doesn't take the load delay into account and will
therefore only work on emulators. The assembler detects it
and warns the user. In order to work correctly, the code should
look like this:
lw a0,0x10(r29)
nop
lbu a1,(a0)
Here, one cycle is wasted with the nop and there will be no
problems.
However, the detection doesn't work in all cases. It can't
check if the instruction at a branch destination uses a
register that was loaded in the branch's delay slot, and it
will give it a false alarm in the following example:
bnez a0,@@branch1
nop
j @@branch2
lw a0,(a1)
@@branch1:
lbu a2,(a0)
You can fix the false warning by using the .resetdelay
directive before the last instruction.
bnez a0,@@branch1
nop
j @@branch2
lw a0,(a1)
.resetdelay
@@branch1:
lbu a2,(a0)
This behavior may be fixed in a future revision.
3.7 Strings
You can write ASCII text by simple using the .db/.ascii
directive. However, you can also write text with custom
encodings. In order to do that, you first have to load a table,
and then use the .string directive to write the text.
It behaves exactly like the .db instruction (so you can also
specify immediate values as arguments), with the exception
that it uses the table to encode the text, and appends a
termination sequence after the last argument. This has to
be specified inside the table, otherwise 0 is used.
.loadtable "custom.tbl"
.string "Custom text",0xA,"and more."
The first and third argument are encoded according to the
table, while the second one is written as-is.
3.8 Areas
If you overwrite existing data, it is critical that you
don't overwrite too much. The area directive will take care
of checking if all the data is within a given space. In order
to do that, you just have to give it the maximum size allowed.
.area 10h
.word 1,2,3,4,5
.endarea
This would cause an error on assembling, because the word
directive takes up 20 bytes instead of the 16 that the
area is allowed to have. This, on the other hand, would
assemble without problems:
.org 8000000h
.area 8000020h-.
.word 1,2,3,4,5
.endarea
Here, the area is 32 bytes, which is sufficient for the 20
bytes used by .word.
#################################
# 4. ASSEMBLER DIRECTIVES #
#################################
These commands tell the assembler to do various things
like opening the output file or opening another source
file.
4.1 General Directives
.psx
Sets the architecture to PSX.
.gba
Sets the architecture to GBA. It will default to THUMB
mode, but it can switch to ARM at any time. ARM9 specific
opcodes are disabled, so it is also usable for NDS ARM7
code.
.nds
Sets the architecture to NDS. It will default to ARM mode,
but it can switch to THUMB at any time.
.open FileName,RamAddress
.open OldFileName,NewFileName,RamAddress
Opens the specified file for output. If two file names
are specified, then the assembler will copy the first
file to the second path. All paths are relative to the
current working directory, so from where the assembler
was called. RamAddress specifies the difference between
the first byte of the file and its position in RAM.
So if file position 0x800 is at position 0x80010000 in
RAM, the header size is 0x80010000-0x800=0x8000F800.
Only the changes specified by the assembly code will
be inserted, the rest of the file remains untouched.
.create FileName,RamAddress
.createfile FileName,RamAddress
Creates the specified file for output. If the file already
exists, it will be erased. All paths are relative to the
current working directory, so from where the assembler was
called. RamAddress specifies the difference between the
first byte of the file and its position in RAM. So if file
position 0x800 is at position 0x80010000 in RAM, the header
size is 0x80010000-0x800=0x8000F800.
.close
.closefile
Closes the currently opened output file.
.headersize RamAddress
Sets the header size to the given size. It will be
used to calculate all addresses from that point on.
.org RamAddress
Sets the output pointer to the specified address. The file
address is computed by subtracting the header size from
the given address.
.orga FileAddress
Sets the output pointer to the specified address. The
absolute file address is given.
.include FileName
Opens the file called FileName to assemble it. All paths
are relative to the current working directory, so from
where the assembler was called. You can include other
files up to a depth level of 64. This limit was added
to prevent the assembler from crashing due to two files
including each other over and over again.
.incbin FileName
.import FileName
Inserts the file specified by FileName into the currently
opened output file. All paths are relative to the current
working directory, so from where the assembler was called.
.align [num]
Writes zeroes into the output file until the output
position is divisible by num. If num is not given,
4 will be used by default. num has to be a power of two.
.fill length[,value]
defs length[,value]
Inserts length amount of bytes of value. If value isn't
specified, inserts zeros. Only the lowest 8 bits of
value are inserted.
.byte value[,...]
.db value[,...]
.ascii value[,...]
dcb value[,...]
Inserts up to 128 bytes specified by the arguments. Value
can be any equation, but only the lowest 8 bits are inserted.
Value can also be a string in quotation marks.
.halfword value[,...]
.dh value[,...]
dcw value[,...]
Inserts up to 128 halfwords specified by the arguments. Value
can be any equation, but only the lowest 16 bits are inserted.
Value can also be a string in quotation marks, in that case,
every letter is inserted as a halfword.
.word value[,...]
.dw value[,...]
dcd value[,...]
Inserts up to 128 words specified by the arguments. Value can
be any equation. Value can also be a string in quotation marks,
in that case, every letter is inserted as a word.
.if equation
Assembles the next block only if equation is nonzero. Can be
inverted by .else or .elseif and has to be terminated by
.endif. The code is still verified even if the condition is
not met.
.else
Inverts previous .if or .elseif statement.
.elseif equation
Equation will only be checked if previous .if or .elseif
statement was not met. Assembles the next block only if
equation is nonzero. Can be inverted by .else or .elseif
and has to be terminated by .endif. The code is still
verified even if the condition is not met.
.ifdef label
Assembles the next block only if label is defined. Can be
inverted by .else or .elseif and has to be terminated by
.endif. The code is still verified even if the condition is
not met.
.ifndef label
Assembles the next block only if label is not defined. Can
be inverted by .else or .elseif and has to be terminated by
.endif. The code is still verified even if the condition
is not met.
.loadtable TableName
.table TableName
Loads TableName for using it with the .string directive.
The encoding has to be same as the assembly file's,
as a simple binary comparison is used. All paths are relative
to the current working directory, so from where the assembler
was called. You can specify one or several termination bytes
like this:
02=a
/FF
FF will be inserted at the end of the string. If it is not
given, zero is used instead.
.string "String"
.str "String"
Inserts the given string using the previously opened table.
.definelabel Label,value
Defines Label with the given value. This may seem similar to equ,
but you don't have to use this before using the label. It will also
be added to the sym output.
.area SizeEquation
Opens a new area with the maximum size of SizeEquation. If the
data inside the area is bigger than the maximum, the assembler
will output an error and refuse to assemble the code. It has to
be closed by a .endarea directive.
.endarea
Closes a previously opened area. If the difference between the
current ram address and that of the previous .area directive is
bigger than the given size, an error will prevent successful
assembling.
4.2 MIPS Directives
.resetdelay
Resets the current load delay status. This can be useful if
the instruction after a delay slot access the delayed register,
as the assembler can't detect that yet.
.fixloaddelay
Automatically fixes any load delay problems by inserting a
nop between the instructions. Best used in combination with
.resetdelay.
4.3 ARM Directives
.arm
This tells the assembler to use the full 32 bit ARM instruction
set. It can be switched to THUMB at any time. NDS will default
to this instruction set.
.thumb
This tells the assembler to use the cut-down 16bit THUMB
instruction set. It can be switched to ARM at any time. GBA will
default to this instruction set.
.pool
This directive works together with a pseudo opcode. In the code,
you can use an ldr instruction to load a full 32 bit immediate.
This immediate will be saved inside one of these pools.
Example:
ldr r0,=0xFFEEDDCC
; ...
.pool
Here, the ldr instruction will be assembled as a PC-relative
load and the value will be written into the pool. The range is
limited, so you may have to define several pools.
.pool will automatically align the position to a multiple of 4.
.msg
Adds a no$gba debug message as described by GBATEK.
#################################
# 5. MACROS #
#################################
5.1 Assembler defined MIPS macros.
There are various macros built into the assembler for ease
of use. They are intended to make using some of the assembly
simpler and faster.
At the moment, these are all the MIPS macros included:
li reg,Immediate
la reg,Immediate
Loads Immediate into the specified register by using a
combination of lui/ori, a simple addiu or a simple ori.
lb reg,Address
lbu reg,Address
lh reg,Address
lhu reg,Address
lw reg,Address
Loads a byte/halfword/word from the given address into
the specified register by using a combination of lui
and lb/lbu/lh/lhu/lw.
ulh destreg,imm(sourcereg)
ulh destreg,(sourcereg)
ulhu destreg,imm(sourcereg)
ulhu destreg,(sourcereg)
Loads an unaligned halfword from the address in sourcereg.
It uses a combination of several lb/lbus and oris.
ulw destreg,imm(sourcereg)
ulw destreg,(sourcereg)
Loads an unaligned word from the address in sourcereg.
It uses a combination of lwl/lwr.
sb reg,Address
sh reg,Address
sw reg,Address
Writes a byte/halfword/word to the given address by
using a combination of lui and sb/sh/sw.
ush destreg,imm(sourcereg)
ush destreg,(sourcereg)
Loads an unaligned halfword to the address in sourcereg.
It uses a combination of several sb/sbus and shifts.
usw destreg,imm(sourcereg)
usw destreg,(sourcereg)
Loads an unaligned word to the address in sourcereg.
It uses a combination of swl/swr.
blt reg1,reg2,Dest
bge reg1,reg2,Dest
If reg1 is lower than/greate or equal than reg2, branches
to the given address. A combination of sltu and beq/bne
is used.
blt reg,Imm,Dest
bge reg,Imm,Dest
If reg is lower than/greater or equal than Imm, branches
to the given address. A combination of li, sltu and beq/bne
is used.
bne reg,Imm,Dest
beq reg,Imm,Dest
If reg is not the same/the same as Imm, branches to the
given address. A combination of li and beq/bne is used.
rol reg1,reg2,reg3
ror reg1,reg2,reg3
Rotates reg2 left/right by the value of the lower 5 bits
of reg3 and stores the result in reg1. A combination of
sll, srl and ori is used.
rol reg1,reg2,Imm
ror reg1,reg2,Imm
Rotates reg2 left/right by Imm and stores the result in
reg1. A combination of sll, srl and ori is used.
5.2 User defined macros
The assembler allows the user to create his own macros.
This is an example macro, a recreation of the builtin
macro for li:
.macro myli,dest,value
.if value < 0x10000
ori dest,r0,value
.elseif (value & 0xFFFF8000) == 0xFFFF8000
addiu dest,r0,value & 0xFFFF
.elseif (value & 0xFFFF) == 0
lui dest,value >> 16
.else
lui dest,value >> 16 + (value & 0x8000 != 0)
addiu dest,dest,value & 0xFFFF
.endif
.endmacro
The macro has to be initiated by a .macro directive. The
first argument is the macro name, followed by a variable
amount of arguments. The code inside the macro can be
anything, and it can even call other macros (up to a nesting
level of 128 calls). The macro is terminated by a .endmacro
directive. It is not assembled when it is defined, but other
code can call it from now on. All arguments are simple text
replacements, so they can be anything from a number to a
whole instruction parameter list.
The macro is then called like this:
myli a0,0xFFEEDDCC
This code will, in this case, assemble to the following:
lui a0,0xFFEF
addiu a0,a0,0xDDCC
The user can define a theoretically infinite amount of
macros. Like all the other code, any equs are inserted
before they are resolved.
With the latest revision, macros can also contain local
labels that are changed to an unique name. Global labels,
however, are uneffected by this. The label name is prefixed
by the macro name and a counter id. This label:
.macro test
@@MainLoop:
.endmacro
will therefore be changed to:
@@test_00000000_mainloop
Each call of the macro will increase the counter.
#################################
# 6. KNOWN ISSUES #
#################################
-the last line of any file has to be empty, otherwise
it is ignored due to limitations in the code
-the load delay check can't detect if an opcode is inside
a delay slot, and if it will be used by the first
instruction of the branch destination
Jump to Line
Something went wrong with that request. Please try again.