lips

An assembler for the MIPS R4300i architecture, written in Lua.

Not for production. Much of the code and syntax is untested and likely to change. Even this README is incomplete.

Integer Precision

Please note: some builds of Lua cannot precisely handle integers larger than 24 bits. This can cause errorenous instructions to be assembled. LuaJIT and Lua 5.3 shouldn't have this issue by default.

Just to be safe, try running the following script:

local precise = 0x1000000 + 1 ~= 0x1000000
if precise then
    print("You're all set!")
else
    print("You will have a bad time.")
end

Syntax

(TODO)

A derivative of CajeASM's syntax.

Instructions

Instructions were primarily referenced from the N64 Toolkit: Opcodes.

A more in-depth look at instructions for MIPS IV processors in general is given by the MIPS IV Instruction Set manual.

There's also a brief and incomplete overview of MIPS instructions. First-time writers of MIPS assembly may find this the most useful.

Unimplemented

As far as I know, all native R4300i instructions have been implemented. Whether or not they output the proper machine code is another thing.

Unimplemented Pseudo-Instructions

Besides implicit arguments for existing instructions, there are:

• ABS, MUL, DIV, REM

• SEQ, SEQI, SEQIU, SEQU

• SGE, SGEI, SGEIU, SGEU

• SGT, SGTI, SGTIU, SGTU

• SLE, SLEI, SLEIU, SLEU

• SNE, SNEI, SNEIU, SNEU

• BEQI, BNEI, BGE, BGEI, BLE, BLEI, BLT, BLTI, BGT, BGTI

Registers

In order of numerical value, with intended usage:

• R0: always zero; cannot be written to. 'zero' is an acceptable alias.

• AT: assembler temporary. used by various pseudo-instructions. user may use freely if they're wary.

• V0, V1: subroutine return values.

• A0 A1 A2 A3: subroutine arguments.

• T0 T1 T2 T3 T4 T5 T6 T7: temporary registers.

• S0 S1 S2 S3 S4 S5 S6 S7: saved registers.

• T8 T9: more temporary registers.

• K0 K1: kernel registers. not recommended to use outside of kernel code.

• GP: global pointer.

• SP: stack pointer.

• FP: frame pointer. 'S8' is an acceptable alias.

• RA: subroutine return address.

• REG#: whereas # is a decimal number from 0 to 31. aliased to the appropriate register. eg: REG0 is R0, REG1 is at, REG2 is V0.

• F#: coproccesor 1 registers, whereas # is a decimal number from 0 to 31.

Unimplemented

all coprocessor 0 registers:

Index,     Random,    EntryLo0,     EntryLo1,
Context,   PageMask,  Wired,        RESERVED,
BadVAddr,  Count,     EntryHi,      Compare,
Status,    Cause,     ExceptionPC,  PRId,
Config,    LLAddr,    WatchLo,      WatchHi,
XContext,  RESERVED,  RESERVED,     RESERVED,
RESERVED,  RESERVED,  RESERVED,     CacheErr,
TagLo,     TagHi,     ErrorEPC,     RESERVED

Directives

• .byte {numbers...}
  writes a series of 8-bit numbers until end-of-line. be wary of potential alignment issues.

• .halfword {numbers...}
  writes a series of 16-bit numbers until end-of-line. be wary of potential alignment issues.

• .word {numbers...}
  writes a series of 32-bit numbers until end-of-line.

• .align [n] [fill]
  aligns the next datum to a n*2 boundary using fill for spacing. if n is not given, 2 is implied. if fill is not given, 0 is implied.

• .skip {n} [fill]
  skips the next n bytes using fill for spacing. if fill is not given, no bytes are overwritten, and only the position is changed.

• .org {address}
  set the current address for writing to; seek. until lips is a little more optimized, be cautious of seeking to large addresses.

• HEX { ... }
  write a series of bytes given in hexadecimal. all numbers must be given in hex — no prefix is required.

butts:  HEX {
    F0 0D
    DE AD BE EF
}
.align

Unimplemented

• FLOAT: writes a list of 32-bit floating point numbers until end-of-line. this may not get implemented due to a lack of aliasing in vanilla Lua, and thus accuracy issues.

• ASCII: writes a string using its characters' ASCII values.

• ASCIIZ: same as ASCII, but with a null byte added to the end.

• INC, INCASM, INCLUDE: include an external assembly file as-is at this position.

• INCBIN: write an external binary file as-is at this position.