1# ARMIPS assembler v0.10 2* Author: Kingcom 3* Source: https://github.com/Kingcom/armips 4* Automated builds: http://buildbot.orphis.net/armips 5 6# 1. Introduction 7 8Note: This file is still incomplete, some information is missing or may be outdated. 9 10## 1.1 Usage 11 12The assembler is called from the command line. There is both an x86 and an x86-64 version. Depending on the version, the usage is as follows: 13 14``` 15armips code.asm [optional parameters] 16armips64 code.asm [optional parameters] 17``` 18 19`code.asm` is the main file of your assembly code, which can open and include other files. 20The following optional command line parameters are supported: 21 22#### `-temp <filename>` 23Specifies the output name for temporary assembly data. Example output: 24``` 25; 1 file included 26; test.asm 27 2800000000 .open "SLPM_870.50",0x8000F800 ; test.asm line 1 298000F800 .org 0x800362DC ; test.asm line 5 30800362DC jal 0x801EBA3C ; test.asm line 7 31800362E0 .Close ; test.asm line 9 32``` 33 34#### `-sym <filename>` 35Specifies the output name for symbol data in the sym format. This format is supported by the debuggers in NO$PSX and NO$GBA. Example output: 36``` 3700000000 0 3880000000 .dbl:0010 3980000010 main 408000002C subroutine 4180240000 newblock 42``` 43 44#### `-sym2 <filename>` 45Specifies the output name for symbol data in the sym2 format. This format is supported by the debuggers in PCSX2 and PPSSPP. Example output: 46``` 4700000000 0 4880000000 .dbl:0010 4980000010 Main 508000002C Subroutine,0000001C 5180240000 NewBlock,00000014 52``` 53 54#### `-erroronwarning` 55Specifies that any warnings shall be treated like errors, preventing assembling. This has the same effect as the `.erroronwarning` directive. 56 57#### `-equ <name> <replacement>` 58Equivalent to using `name equ replacement` in the assembly code. 59 60#### `-strequ <name> <replacement>` 61Equivalent to using `name equ "replacement"` in the assembly code. 62 63#### `-root <directory>` 64Specifies the working directory to be used during execution. 65 66# 2. Installation 67 68## 2.1 Download binary 69Download the latest Windows 32-bit binary from the [Automated ARMIPS builds](http://buildbot.orphis.net/armips) site. You will need the [Microsoft Visual Studio 2015 x86 Redistributable](https://www.microsoft.com/en-US/download/details.aspx?id=48145). 70 71## 2.2 Building from source 72 73The latest code is available at the [ARMIPS GitHub repository](https://github.com/Kingcom/armips). Make sure to also initialize and update submodules. This can be accomplished with one command: 74```bash 75$ git clone --recursive https://github.com/Kingcom/armips.git 76``` 77 78Build instructions per platform: 79* Building on Windows: You will need Visual Studio 2015 (Community Edition is sufficient). Simply open armips.sln, select the desired configuration and platform, and build the solution. Alternatively, you can build using [CMake](https://cmake.org/) with [MSYS2/MinGW](https://msys2.github.io/), but the VS2015 project is the only Windows build officially supported. 80* Building on Unix: You will need CMake and a C++11 compliant compiler (recent versions of both gcc and clang have been tested). Create a build directory, invoke CMake from there, and then simply run `make`. 81```bash 82$ mkdir build && cd build 83$ cmake -DCMAKE_BUILD_TYPE=Release .. 84$ make 85``` 86 87# 3. Overview 88 89The assembler includes full support for the MIPS R3000, MIPS R4000, and Allegrex instruction sets, partial support for the EmotionEngine instruction set, as well as complete support for the ARM7 and ARM9 instruction sets, both THUMB and ARM mode. Among the other features of the assembler are: 90 91* a full fledged C-like expression 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 92* 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 93* local, static, and global labels (see [4.3 Labels](#43-labels)) 94* table support for user defined text encodings (see [4.7 Strings](#47-strings)) 95* several MIPS macros to make writing code easier and faster (see [5.1 General directives](#51-general-directives)) 96* user defined macros (see [6.3 User defined macros](#63-user-defined-macros)) 97* built-in checks for possible load delay problems (see [4.6 Load delay detection](#46-load-delay-detection)) 98* optional automatic fix for said problems by inserting a nop between the instructions 99* output of the assembled code to a text file, with memory addresses and origin (see [1.1 Usage](#11-usage)) 100* a directive to ensure that data is not bigger than a user defined size (see [4.8 Areas](#48-areas)) 101 102# 4. Features 103 104## 4.1 Files 105 106Unlike 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 files that are currently not opened as well. 107 108``` 109.Open "SLPS_035.71", 0x8000F800 110; ... 111.Close 112.Open "System\0007.dat", 0x800CC000 113; ... 114.Close 115``` 116 117## 4.2 Syntax 118 119### Comments 120Both `;` and `//` style single-line comments are supported. 121`/* */` style block comments are also accepted. 122 123### Statement separator 124Statements are separated by newlines or `::` can be used between statements on the same line. For example, to insert four `nop` instructions, this could be written on one line: 125``` 126nop :: nop :: nop :: nop 127``` 128 129### Statement line spanning 130Single statements can continue on to the next line by inserting a `\` at the end of a line. Comments and whitespace can follow. For example: 131``` 132addiu t3, t4, \ 133 FunctionJumpTable - headersize() + 0x1000 * filesize("blob.bin") 134``` 135 136## 4.3 Labels 137 138There is support for both local, global and static 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. 139 140``` 141GlobalLabel: ; This is a global label 142@@LocalLabel: ; This is a local label, it is only 143 ; valid until the next global one 144OtherGlobalLabel: ; this will terminate the area where 145 ; @@LocalLabel can be used 146 b @@LocalLabel ; as a result, this will cause an error 147``` 148 149Static labels behave like global labels, but are only valid in the very file they were defined. Any included files or files that include it cannot reference it. They can, however, contain another static label with the same name. 150 151``` 152@StaticLabel: 153``` 154 155A label name can contain all characters from A-Z, numbers, and underscores. However, it cannot start with a digit. All label names are case insensitive. 156 157Additionally, `.` can be used to reference the current memory address. 158 159## 4.4 equ 160 161The `equ` directive works as a text replacement and is defined as follows: 162 163``` 164@@StringPointer equ 0x20(r29) 165``` 166 167There has to be a space before and after `equ`. The assembler will replace any occurrence 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: 168 169``` 170@@StringPointer equ 0x20(r29) 171 172 lw a0,@@StringPointer 173 nop 174 sw a1,@@StringPointer 175``` 176 177will assemble to this: 178 179``` 180 lw a0,0x20(r29) 181 nop 182 sw a1,0x20(r29) 183``` 184 185There can be both global and local `equ` directives, but unlike normal labels, they must be defined before they are used. 186 187 188## 4.5 Expression parser 189 190A standard expression 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 ternary 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 cannot be used in expressions for them. The following bases are supported: 191 192* `0xA` and `0Ah` for hexadecimal numbers 193* `0o12` and `12o` for octal numbers 194* `1010b` and `0b1010` for binary numbers 195 196Everything 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. For example, as `FFh` is a perfectly valid label name, you have to write `0FFh` in this case. Labels, on the other hand, cannot start with a digit. 197 198A few examples: 199 200``` 201 mov r0,10+0xA+0Ah+0o12+12o+1010b 202 ldr r1,=ThumbFunction+1 203 li v0,Structure+(3*StructureSize) 204``` 205 206### Built-in functions 207 208Below is a table of functions built into the assembler that can be used with the expression parser for runtime computation. 209 210| Function | Description | 211|----------|-------------| 212| `version()` | armips version encoded as int | 213| `endianness()` | current endianness as string `"big"` or `"little"` | 214| `outputname()` | currently opened output filename | 215| `org()` | current memory address (like `.`) | 216| `orga()` | current absolute file address | 217| `headersize()` | current header size (displacement of memory address against absolute file address) | 218| `fileexists(file)` | `1` if `file` exists, `0` otherwise | 219| `filesize(file)` | size of `file` in bytes | 220| `tostring(val)` | string representation of int or float `val` | 221| `tohex(val, optional digits = 8)` | hex string representaion of int `val` | 222| `round(val)` | float `val` rounded to nearest int | 223| `int(val)` | cast float `val` to int, dropping fractional part | 224| `float(val)` | cast int `val` to float | 225| `frac(val)` | fractional part of float `val` | 226| `abs(val)` | absolute value of int or float `val` | 227| `hi(val)` | High half of 32-bit value `val`, adjusted for sign extension of low half (MIPS) | 228| `lo(val)` | Sign-extended low half of 32-bit value `val` (MIPS) | 229| `strlen(str)` | number of characters in `str` | 230| `substr(str, start, count)` | substring of `str` from `start`, length `count` | 231| `regex_match(source, regex)` | `1` if `regex` matched entire `source`, `0` otherwise| 232| `regex_search(source, regex)` | `1` if `regex` matched subsequence of `source`, `0` otherwise| 233| `regex_extract(source, regex, optional index = 0)` | string of `regex` matched in `source` | 234| `find(source, substr, optional start = 0)` | lowest index of `substr` in `source` from `start`, else `-1` | 235| `rfind(source, substr, optional start = -1)` | highest index of `substr` in `source` from `start`, else `-1` | 236| `readbyte(file, optional pos = 0)` | read unsigned 8-bit value from `file` at position `pos` | 237| `readu8(file, optional pos = 0)` | read unsigned 8-bit value from `file` at position `pos` | 238| `readu16(file, optional pos = 0)` | read unsigned 16-bit value from `file` at position `pos` | 239| `readu32(file, optional pos = 0)` | read unsigned 32-bit value from `file` at position `pos` | 240| `readu64(file, optional pos = 0)` | read unsigned 64-bit value from `file` at position `pos` | 241| `reads8(file, optional pos = 0)` | read signed 8-bit value from `file` at position `pos` | 242| `reads16(file, optional pos = 0)` | read signed 16-bit value from `file` at position `pos` | 243| `reads32(file, optional pos = 0)` | read signed 32-bit value from `file` at position `pos` | 244| `reads64(file, optional pos = 0)` | read signed 64-bit value from `file` at position `pos` | 245| `readascii(file, optional start = 0, optional len = 0)` | read ASCII string from `file` at `start` length `len` | 246| `isarm()` | `1` if in ARM mode, `0` otherwise | 247| `isthumb()` | `1` if in Thumb mode, `0` otherwise | 248 249## 4.6 Load delay detection 250 251This feature is still unfinished and experimental. It works in most cases, though. On certain MIPS platforms (most notably the PlayStation 1), any load is asynchronously delayed by one cycle and the CPU won't stall if you attempt to use it before. Attempts to use it will return the old value on an actual system (emulators usually 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: 252 253``` 254 lw a0,0x10(r29) 255 lbu a1,(a0) 256``` 257 258This 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: 259 260``` 261 lw a0,0x10(r29) 262 nop 263 lbu a1,(a0) 264``` 265 266The assembler can optionally automatically insert a `nop` when it detects such an issue. This can be enabled with the [`.fixloaddelay`](#load-delay) directive. 267However, as there is no control flow analysis, there is a chance of false positives. For example, a branch delay slot may cause a warning for the opcode that follows it, even if there is no chance that they will be executed sequentially. The following example illustrates this: 268 269``` 270 bnez a0,@@branch1 271 nop 272 j @@branch2 273 lw a0,(a1) 274@@branch1: 275 lbu a2,(a0) 276``` 277 278You can fix the false warning by using the [`.resetdelay`](#load-delay) directive before the last instruction. 279 280``` 281 bnez a0,@@branch1 282 nop 283 j @@branch2 284 lw a0,(a1) 285.resetdelay 286@@branch1: 287 lbu a2,(a0) 288``` 289 290## 4.7 Strings 291 292You can write ASCII text by simply 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 using [`.loadtable <tablefile>`](#load-a-table-specifying-a-custom-encoding), and then use the [`.string`](#write-text-with-custom-encoding) 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. 293 294``` 295.loadtable "custom.tbl" 296.string "Custom text",0xA,"and more." 297``` 298 299The first and third argument are encoded according to the table, while the second one is written as-is. 300 301Quotation marks can be escaped by prefixing them with a backslash. Any backlash not followed by a quotation mark is kept as-is. If you want to use a backslash at the end of a string, prefix it by another backlash. 302For example, to write a quotation mark followed by a backlash: 303 304``` 305.ascii "\"\\" 306``` 307 308## 4.8 Areas 309 310If 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 specify the maximum size allowed. 311 312``` 313.area 10h 314 .word 1,2,3,4,5 315.endarea 316``` 317 318This 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: 319 320``` 321.org 8000000h 322.area 8000020h-. 323 .word 1,2,3,4,5 324.endarea 325``` 326 327Here, the area is 32 bytes, which is sufficient for the 20 bytes used by .word. 328Optionally, a second parameter can be given. The remaining free size of the area will then be completely filled with bytes of that value. 329 330## 4.9 Symbol files 331 332Functions. 333 334## 4.10 C/C++ importer 335 336You can link object files or static libraries in ELF format. The code and data is relocated to the current output position and all of its symbols are exported. You can in turn use armips symbols inside of your compiled code by declaring them as `extern`. Note: As armips labels are case insensitive, the exported symbols are treated the same way. Be aware of name mangling when trying to reference C++ functions, and consider declaring them as `extern "C"`. 337 338``` 339.importobj "code.o" 340``` 341 342You can optionally supply names for constructor and destructor functions. Functions with those names will be generated that call of the global constructors/destructors of the imported files. 343 344``` 345.importlib "code.a",globalConstructor,globalDestructor 346``` 347 348# 5. Assembler directives 349 350These commands tell the assembler to do various things like opening the output file or opening another source file. 351 352## 5.1 General directives 353 354### Set the architecture 355 356These directives can be used to set the architecture that the following assembly code should be parsed and output for. The architecture can be changed at any time without affecting the preceding code. 357 358| Directive | System | Architecture | Comment | 359| --------- |:-------|:-------------|:--------| 360| `.psx` | PlayStation 1 | MIPS R3000 | - | 361| `.ps2` | PlayStation 2 | EmotionEngine | - | 362| `.psp` | PlayStation Portable | Allegrex | - | 363| `.n64` | Nintendo 64 | MIPS R4000 | - | 364| `.rsp` | Nintendo 64 | RSP | - | 365| `.gba` | GameBoy Advance | ARM7 | Defaults to THUMB mode | 366| `.nds` | Nintendo DS | ARM9 | Defaults to ARM mode | 367| `.3ds` | Nintendo 3DS | ARM11 | Defaults to ARM mode, incomplete | 368| `.arm.big` | - | ARM | Output in big endian | 369| `.arm.little` | - | ARM | Output in little endian | 370 371### Open a generic file 372 373``` 374.open FileName,Offset 375.open OldFileName,NewFileName,Offset 376``` 377 378Opens the specified file for output. If two file names are specified, then the assembler will copy the file specified by the file name to the second path. If relative include is off, all paths are relative to the current working directory. Otherwise the path is relative to the including assembly file. `Offset` specifies the difference between the first byte of the file and its position in memory. So if file position 0x800 is at position 0x80010000 in memory, the header size is 0x80010000-0x800=0x8000F800. It can be changed later with the [`.headersize`](#changing-the-header-size) directive. 379Only the changes specified by the assembly code will be inserted, the rest of the file remains untouched. 380 381### Create a new file 382 383``` 384.create FileName,Offset 385.createfile FileName,Offset 386``` 387 388Creates the specified file for output. If the file already exists, it will be overwritten. If relative include is off, all paths are relative to the current working directory. Otherwise the path is relative to the including assembly file. `Offset` specifies the difference between the first byte of the file and its position in memory. So if file position 0x800 is at position 0x80010000 in memory, the header size is 0x80010000-0x800=0x8000F800. It can be changed later with the [`.headersize`](#changing-the-header-size) directive. 389 390### Close a file 391 392``` 393.close 394.closefile 395``` 396 397Closes the currently opened output file. 398 399### Set the output position 400 401``` 402.org RamAddress 403.orga FileAddress 404``` 405 406Sets the output pointer to the specified address. `.org` specifies a memory address, which is automatically converted to the file address for the current output file. `.orga` directly specifies the absolute file address. 407 408### Change the header size 409 410``` 411.headersize Offset 412``` 413 414Sets the header size to the given value which is the difference between the file position of a byte and its address in memory. This is used to calculate all addresses up until the next `.headersize` or `.open`/`.create` directive. The current memory address will be updated, but the absolute file offset will remain the same. The header size can be negative so long as the resulting memory address remains positive. 415 416### Include another assembly file 417 418``` 419.include FileName[,encoding] 420``` 421 422Opens the file called `FileName` to assemble its content. If relative include is off, all paths are relative to the current working directory. Otherwise the path is relative to the including assembly file. You can include other files up to a depth level of 64. This limit was added to prevent the assembler from getting stuck in an infinite loop due to two files including each other recursively. If the included file has an Unicode Byte Order Mark then the encoding will be automatically detected. If no Byte Order Mark is present it will default to UTF-8. This can be overwritten by manually specifying the file encoding as a second parameter. 423 424The following values are supported: 425* `SJIS`/`Shift-JIS` 426* `UTF8`/`UTF-8` 427* `UTF16`/`UTF-16` 428* `UTF16-BE`/`UTF-16-BE` 429* `ASCII` 430 431## Text and data directives 432 433### Align the output position 434 435``` 436.align num 437``` 438 439Writes zeros into the output file until the output position is a multiple of `num`. `num` has to be a power of two. 440 441### Fill space with a value 442 443``` 444.fill length[,value] 445defs length[,value] 446``` 447 448Inserts `length` amount of bytes of `value`. If `value` isn't specified, zeros are inserted. Only the lowest 8 bits of `value` are inserted. 449 450### Skip bytes 451 452``` 453.skip length 454``` 455 456Skips `length` amount of bytes without overwriting them. 457 458### Include a binary file 459 460``` 461.incbin FileName[,start[,size]] 462.import FileName[,start[,size]] 463``` 464 465Inserts the file specified by `FileName` into the currently opened output file. If relative include is off, all paths are relative to the current working directory. Otherwise the path is relative to the including assembly file. Optionally, start can specify the start position in the file from it should be imported, and size can specify the number of bytes to read. 466 467### Write bytes 468 469``` 470.byte value[,...] 471.db value[,...] 472.ascii value[,...] 473.asciiz value[,...] 474dcb value[,...] 475``` 476 477Inserts the specified sequence of bytes. Each parameter can be any expression that evaluates to an integer or a string. If it evaluates to an integer, only the lowest 8 bits are inserted. If it evaluates to a string, every character is inserted as a byte. `.asciiz` inserts a null terminator after the string, while the others omit it. 478 479### Write halfwords 480 481``` 482.halfword value[,...] 483.dh value[,...] 484dcw value[,...] 485``` 486 487Inserts the specified sequence of 16-bit halfwords. Each parameter can be any expression that evaluates to an integer or a string. If it evaluates to an integer, only the lowest 16 bits are inserted. If it evaluates to a string, every character is inserted as a halfword. 488 489 490### Write words 491 492``` 493.word value[,...] 494.dw value[,...] 495dcd value[,...] 496``` 497 498Inserts the specified sequence of 32-bit words. Each parameter can be any expression that evaluates to an integer, a string, or a floating point number. If it evaluates to an integer, only the lowest 32 bits are inserted. If it evaluates to a string, every character is inserted as a word. Floats are inserted using an integer representation of the single-precision float's encoding. 499 500### Write doublewords 501 502``` 503.doubleword value[,...] 504.dd value[,...] 505dcq value[,...] 506``` 507 508Inserts the specified sequence of 64-bit doublewords. Each parameter can be any expression that evaluates to an integer, a string, or a floating point number. If it evaluates to a string, every character is inserted as a doubleword. Floats are inserted using an integer representation of the double-precision float's encoding. 509 510### Write floating point numbers 511 512``` 513.float value[,...] 514.double value[,...] 515``` 516 517`.float` inserts the specified sequence of single-precision floats and `.double` inserts double-precision floats. Each parameter can be any expression that evaluates to an integer or a floating point number. If it evaluates to an integer, it will be converted to a floating point number of that value. 518 519### Load a table specifying a custom encoding 520 521``` 522.loadtable TableName[,encoding] 523.table TableName[,encoding] 524``` 525 526Loads `TableName` for using it with the `.string` directive. The encoding can be specified in the same way as for `.include`. 527 528The table file format is a line-separated list of key values specified by `hexbyte=string` and optional termination byte sequence by `/hexbytes` 529 530``` 53102=a 5321D=the 5332F=you 534/FF 535``` 536 537`FF` will be used as the termination sequence. If it is not given, zero is used instead. Strings are matched using the longest prefix found in the table. 538 539 540### Write text with custom encoding 541 542``` 543.string "String"[,...] 544.stringn "String"[,...] 545.str "String"[,...] 546.strn "String"[,...] 547``` 548 549Inserts the given string using the encoding from the currently loaded table. `.string` and `.str` insert the termination sequence specified by the table after the string, while `.stringn` and `.strn` omit it. 550 551### Write text with Shift-JIS encoding 552 553``` 554.sjis "String"[,...] 555.sjisn "String"[,...] 556``` 557 558Inserts the given string using the Shift-JIS encoding. `.sjis` inserts a null byte after the string, while `.sjisn` omits it. 559 560## Conditional directives 561 562### Begin a conditional block 563 564``` 565.if cond 566.ifdef identifier 567.ifndef idenifier 568``` 569 570The content of a conditional block will only be used if the condition is met. In the case of `.if`, it is met of `cond` evaluates to non-zero integer. `.ifdef` is met if the given identifier is defined anywhere in the code, and `.ifndef` if it is not. 571 572### Else case of a conditional block 573 574``` 575.else 576.elseif cond 577.elseifdef identifier 578.elseifndef identifier 579``` 580 581The else block is used if the condition of the condition of the if block was not met. `.else` unconditionally inserts the content of the else block, while the others start a new if block and work as described before. 582 583### End a conditional block 584 585``` 586.endif 587``` 588 589Ends the last open if or else block. 590 591### Define labels 592 593``` 594.definelabel Label,value 595``` 596 597Defines `Label` with a given value, creating a symbol for it. This can be used similar to `equ`, but symbols can be used before labels are defined and can be used in conjunction with the `.ifdef/.ifndef` conditionals. These can also be useful for declaring symbols for existing code and data when inserting new code. 598 599### Areas 600 601``` 602.area SizeEquation[,fill] 603.endarea 604``` 605 606Opens a new area with the maximum size of `SizeEquation`. If the data inside the area is longer than this maximum size, the assembler will output an error and refuse to assemble the code. The area is closed with the `.endarea` directive and if `fill` parameter is provided, the remaining free space in the area will be filled with bytes of that value. 607 608### Messages 609``` 610.warning "Message" 611.error "Message" 612.notice "Message" 613``` 614 615Prints the message and sets warning/error flags. Useful with conditionals. 616 617## 5.2 MIPS directives 618 619### Load delay 620 621``` 622.resetdelay 623``` 624 625Resets 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. 626 627``` 628.fixloaddelay 629``` 630 631Automatically fixes any load delay problems by inserting a `nop` between the instructions. Best used in combination with `.resetdelay`. 632 633``` 634.loadelf name[,outputname] 635``` 636 637Opens the specified ELF file for output. If two file names are specified, then the assembler will copy the first file to the second path. If relative include is off, all paths are relative to the current working directory, so from where the assembler was called. Otherwise the path is relative to the including assembly file. All segments are accessible by their virtual addresses, and all unmapped sections can be accessed by their physical position (through `.orga`). 638Currently this is only supported for the PSP architecture, and only for non-relocateable files. The internal structure of the file may be changed during the process, but this should not affect its behavior. 639 640## 5.3 ARM Directives 641 642### Change instruction set 643 644``` 645.arm 646.thumb 647``` 648 649These directives can be used to select the ARM or THUMB instruction set. `.arm` tells the assembler to use the full 32 bit ARM instruction set, while `.thumb` uses the cut-down 16 bit THUMB instruction set. 650 651### Pools 652 653``` 654.pool 655``` 656 657This directive works together with the pseudo opcode `ldr rx,=value`. The immediate is added to the nearest pool, and the instruction is turned into a PC relative load. The range is limited, so you may have to define several pools. 658Example: 659 660``` 661ldr r0,=0xFFEEDDCC 662; ... 663.pool 664``` 665 666`.pool` will automatically align the position to a multiple of 4. 667 668### Debug messages 669 670``` 671.msg 672``` 673 674Inserts a no$gba debug message as described by GBATEK. 675 676# 6. Macros 677 678## 6.1 Assembler-defined MIPS macros 679 680There are various macros built into the assembler for ease of use. They are intended to make using some of the assembly simpler and faster. 681At the moment, these are all the MIPS macros included: 682 683### Immediate macros 684 685``` 686li reg,Immediate 687la reg,Immediate 688``` 689 690Loads Immediate into the specified register by using a combination of `lui`/`ori`, a simple `addiu`, or a simple `ori`, depending on the value of the Immediate. 691 692### Immediate float macros 693 694``` 695li.s reg,Immediate 696``` 697 698Loads float value Immediate into the specified FP register by using a combination of `li` and `mtc1`. 699 700### Memory macros 701 702``` 703lb reg,Address 704lbu reg,Address 705lh reg,Address 706lhu reg,Address 707lw reg,Address 708lwu reg,Address 709ld reg,Address 710lwc1 reg,Address 711lwc2 reg,Address 712ldc1 reg,Address 713ldc2 reg,Address 714``` 715 716Loads a byte/halfword/word from the given address into the specified register by using a combination of `lui` and `lb`/`lbu`/`lh`/`lhu`/`lw`/`ld`/`lwc1`/`lwc2`/`ldc1`/`ldc2`. 717 718``` 719ulh destreg,imm(sourcereg) 720ulh destreg,(sourcereg) 721ulhu destreg,imm(sourcereg) 722ulhu destreg,(sourcereg) 723ulw destreg,imm(sourcereg) 724ulw destreg,(sourcereg) 725uld destreg,imm(sourcereg) 726uld destreg,(sourcereg) 727``` 728 729Loads an unaligned halfword/word/doubleword from the address in sourcereg by using a combination of several `lb`/`lbu` and `ori` or `lwl`/`lwr` or `ldl`/`ldr` instructions. 730 731``` 732sb reg,Address 733sh reg,Address 734sw reg,Address 735sd reg,Address 736swc1 reg,Address 737swc2 reg,Address 738sdc1 reg,Address 739sdc2 reg,Address 740``` 741 742Stores a byte/halfword/word/doubleword to the given address by using a combination of `lui` and `sb`/`sh`/`sw`/`sd`/`swc1`/`swc2`/`sdc1`/`sdc2`. 743 744``` 745ush destreg,imm(sourcereg) 746ush destreg,(sourcereg) 747usw destreg,imm(sourcereg) 748usw destreg,(sourcereg) 749usd destreg,imm(sourcereg) 750usd destreg,(sourcereg) 751``` 752 753Stores an unaligned halfword/word/doubleword to the address in sourcereg using a combination of several `sb`/`sbu` and shifts or `swl`/`swr`/`sdl`/`sdr` instructions. 754 755### Branch macros 756 757``` 758blt reg1,reg2,Dest 759bltu reg1,reg2,Dest 760bgt reg1,reg2,Dest 761bgtu reg1,reg2,Dest 762bge reg1,reg2,Dest 763bgeu reg1,reg2,Dest 764ble reg1,reg2,Dest 765bleu reg1,reg2,Dest 766bltl reg1,reg2,Dest 767bltul reg1,reg2,Dest 768bgtl reg1,reg2,Dest 769bgtul reg1,reg2,Dest 770bgel reg1,reg2,Dest 771bgeul reg1,reg2,Dest 772blel reg1,reg2,Dest 773bleul reg1,reg2,Dest 774blt reg,Imm,Dest 775bltu reg,Imm,Dest 776bgt reg,Imm,Dest 777bgtu reg,Imm,Dest 778bge reg,Imm,Dest 779bgeu reg,Imm,Dest 780ble reg,Imm,Dest 781bleu reg,Imm,Dest 782bne reg,Imm,Dest 783beq reg,Imm,Dest 784bltl reg,Imm,Dest 785bltul reg,Imm,Dest 786bgtl reg,Imm,Dest 787bgtul reg,Imm,Dest 788bgel reg,Imm,Dest 789bgeul reg,Imm,Dest 790blel reg,Imm,Dest 791bleul reg,Imm,Dest 792bnel reg,Imm,Dest 793beql reg,Imm,Dest 794``` 795 796If reg/reg1 is less than/greater than or equal to/equal to/not equal to reg2/Imm, branches to the given address. A combination of `sltu` and `beq`/`bne` or `li`, `sltu` and `beq`/`bne` is used. 797 798### Set macros 799 800``` 801slt reg1,reg2,Imm 802sltu reg1,reg2,Imm 803sgt reg1,reg2,Imm 804sgtu reg1,reg2,Imm 805sge reg1,reg2,Imm 806sgeu reg1,reg2,Imm 807sle reg1,reg2,Imm 808sleu reg1,reg2,Imm 809sne reg1,reg2,Imm 810seq reg1,reg2,Imm 811sge reg1,reg2,reg3 812sgeu reg1,reg2,reg3 813sle reg1,reg2,reg3 814sleu reg1,reg2,reg3 815sne reg1,reg2,reg3 816seq reg1,reg2,reg3 817``` 818 819If reg2 is less than/greater than or equal to/equal to/not equal to reg3/Imm, sets reg1 to `1`, otherwise sets reg1 to `0`. Various combinations of `li`, `slt`/`sltu`/`slti`/`sltiu` and `xor`/`xori` are used. 820 821### Rotate macros 822 823``` 824rol reg1,reg2,reg3 825ror reg1,reg2,reg3 826rol reg1,reg2,Imm 827ror reg1,reg2,Imm 828``` 829 830Rotates reg2 left/right by the value of the lower 5 bits of reg3/Imm and stores the result in reg1. A combination of `sll`, `srl` and `or` is used. 831 832### Absolute value macros 833 834``` 835abs reg1,reg2 836dabs reg1,reg2 837``` 838 839Stores absolute value of word/doubleword in reg2 into reg1 using a combination of `sra`/`dsra32`, `xor`, and `subu`/`dsubu`. 840 841### Upper/lower versions 842 843Additionally, there are upper and lower versions for many two opcode macros. They have the same names and parameters as the normal versions, but `.u` or `.l` is appended at the end of the name. 844For example, `li.u` will output the upper half of the `li` macro, and `li.l` will output the lower half. The following macros support this: `li`,`la`,`lb`,`lbu`,`lh`,`lhu`,`lw`,`lwu`,`ld`,`lwc1`,`lwc2`,`ldc1`,`ldc2`,`sb`,`sh`,`sw`,`sd`,`swc1`,`swc2`,`sdc1`,`sdc2` 845 846This can be used when the two halves of the macros need to be used in nonconsecutive positions, for example: 847 848``` 849li.u a0,address 850jal function 851li.l a0,address 852``` 853 854## 6.2 Assembler-defined ARM macros 855 856The assembler will automatically convert the arguments between the following opcodes if possible: 857 858``` 859mov <-> mvn 860bic <-> and 861cmp <-> cmn 862``` 863 864E.g., `mov r0,-1` will be assembled as `mvn r0,0` 865 866Additionally, `ldr rx,=immediate` can be used to load a 32-bit immediate. The assembler will try to convert it into a mov/mvn instruction if possible. Otherwise, it will be stored in the nearest pool (see the .pool directive). `add rx,=immediate` can be used as a PC-relative add and will be assembled as `add rx,r15,(immediate-.-8)` 867 868 869## 6.3 User defined macros 870 871The assembler allows the creation of custom macros. This is an example macro, a recreation of the builtin MIPS macro `li`: 872 873``` 874.macro myli,dest,value 875 .if value & ~0xFFFF 876 ori dest,r0,value 877 .elseif (value & 0xFFFF8000) == 0xFFFF8000 878 addiu dest,r0,value & 0xFFFF 879 .elseif (value & 0xFFFF) == 0 880 lui dest,value >> 16 881 .else 882 lui dest,value >> 16 + (value & 0x8000 != 0) 883 addiu dest,dest,value & 0xFFFF 884 .endif 885.endmacro 886``` 887 888The 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 then 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 invoked like this: 889 890``` 891myli a0,0xFFEEDDCC 892``` 893 894In this case, the code will assemble to the following: 895 896``` 897lui a0,0xFFEF 898addiu a0,a0,0xDDCC 899``` 900 901Like all the other code, any equs are inserted before they are resolved. 902 903Macros can also contain local labels that are changed to an unique name. Global labels, however, are unaffected by this. The label name is prefixed by the macro name and a counter id. This label: 904 905``` 906.macro test 907 @@MainLoop: 908.endmacro 909``` 910 911will therefore be changed to: 912 913``` 914@@test_00000000_mainloop 915``` 916 917Each call of the macro will increase the counter. 918 919# 7. Meta 920 921## 7.1 Change log 922 923* Version 0.10 924 * many bugfixes and enhancements 925 * several new MIPS macros and pseudo-ops 926 * improved command argument handling, allows the input file argument to be after flag arguments and detects errors better 927 * C-style block comments supported 928 * expression values are now signed 929 * 64-bit data defines now written in generated symbol files, same command as 32-bit for compatibility with current emulators 930 * ELF relocator now checks object file machine and endianness before linking 931 * new directives: `.asciiz`, `.skip` 932 * new expression functions: `hi` (MIPS only), `lo` (MIPS only), `reads{8,16,32,64}` 933 * float division by zero in expression now has standard float behaviour (returns `±∞` or `NaN`), while integer divisions by zero returns dummy value `-1` 934 * exponential notation for floats supported 935* Version 0.9 936 * huge rewrite with many enhancements and fixes 937 * can now read from UTF8, UTF16, and Shift-JIS files and convert the input correctly 938 * several new MIPS pseudo-ops, new COP0 and FPU control register types 939 * Nintendo 64 CPU + RSP support 940 * PSP support, load ELFs with `.loadelf` 941 * able to import and relocate static C/C++ libraries 942 * new `-sym2` format for use with PPSSPP and PCSX2 943 * new directives: `.sym`, `.stringn`, `.sjis`, `.sjisn`, `.function`, `.endfunction`, `.importlib`, `.loadelf`, `.float`, `.dd`, `.double` 944 * removed directives: `.ifarm`, `.ifthumb`, `.radix` 945 * added support for floats in data directives 946 * added expression functions 947 * variable expressions supported in `.org`/`.orga`/`.headersize` 948 * new statement syntax with `::` as separator and `\` as line continuation. 949* Version 0.7d 950 * added automatic optimizations for several ARM opcodes 951 * many bugfixes and internal changes 952 * added static labels 953 * new directives: `.warning`, `.error`, `.notice`, `.relativeinclude`, `.erroronwarning`, `.ifarm`, `.ifthumb` 954 * quotation marks can now be escaped in strings using `\"`. 955* Version 0.7c 956 * Macros can now contain unique local labels 957 * `.area` directive added 958 * countless bugfixes 959 * no$gba debug message support 960 * full no$gba sym support 961* Version 0.7b 962 * ARM/THUMB support 963 * fixed break/syscall MIPS opcodes 964 * added check if a MIPS instruction is valid inside a delay slot 965 * fixed and extended base detection 966 * added `.` dummy label to the math parser to get the current memory address 967 * added `dcb`/`dcw`/`dcd` directives 968* Version 0.5b 969 * Initial release 970 971## 7.2 Migration from older versions 972 973There are several changes after version 0.7d that may break compatibility with code written for older versions. These are as follows: 974 975* String literals now require quotation marks, e.g. for file names 976* `$XX` is no longer supported for hexadecimal literals 977 978## 7.3 License 979 980MIT Copyright (c) 2009-2018 Kingcom: [LICENSE.txt](LICENSE.txt) 981