import com.kotcrab.Brain;

I needed a way to patch games executables. More specifically PSP games executables.

My only other alternative I knew at that time was using assembler built into PPSSPP (PSP emulator).
Then copying the hex value of new instruction and applying that to target executable manually while keeping track of
what I changed in some other file. There are obvious problems with this solution. Which led me into thinking why not
write my own simple assembler.

Quick research into MIPS showed that it would be easy to write it. It’s a RISC architecture with fixed instruction size
and has good documentation online. Instruction set is rather small and there are only 3 types of instruction to implement
(ignoring FPU instructions which I added much later).

Introducing kmips

kmips is a MIPS assembler that is invoked directly from Kotlin code. It doesn’t parse external file with asm code.
Instead it’s a Kotlin DSL.
Each written asm instruction is a call to standard Kotlin method.

The whole assembler which implements MIPS II instruction set including FPU instructions is just
a single file.
There’s also one other file with unit tests for each instruction. They verify correctness against PPSSPP assembler.

The code is available on Github. Kmips can be included in other projects
from Maven Central repository:

Branch delay slot

MIPS has this oddity where after encountering branch or jump instruction CPU will execute one more instruction after it
before changing instruction pointer. This is due to pipeline construction and is called a branch delay slot. kmips doesn’t
do anything about it, you are expected to handle it manually.

Syntax differences

Naturally the syntax is different, after all it’s just calling Kotlin methods. Which normally would be:

12

li$a0,0x42sw$a0,0x0($s0)

becomes:

12

li(a0,0x42)sw(a0,0x0,s0)

It’s actually possible to make Kotlin syntax more natural thanks to extension functions. By adding this:

That’s an idea to include in future version. I’m not really keen on for writing aliases for each store and load methods.
Maybe that won’t be needed in the future.

FPU instructions would normally look like this:

12

add.s$f0,$f12,$f13c.eq.s$f0,$f1

In kmips it would be:

12

add.s(f0,f12,f13)c.eq.s(f0,f1)

I managed to keep the dot from normal syntax by using inner classes. So c is an object which has eq field. eq is another object
with s method.

Advantages

Since this is using fully featured programming language kmips has nice advantage with possibility to script everything.

For example how about helper method to automatically create function prologue and epilogue.
That piece of boilerplate code is responsible for allocating space for function call on stack (by moving down stack
pointer register) and saving registers modified by the function. Epilogue restores those registers and moves up
stack pointer. I can generate it by doing something like this:

Standard MIPS calling convention requires only some register to be saved (callee saved registers, s0-s7).
There is another class of registers that are saved before calling other function (caller saved registers, t0-t9). It’s up to the caller function whether it wants to preserve its temporary registers.
But that’s just a convention. There’s nothing special about those registers. When doing patches I pretty much always
ignored this. It’s simpler to just save all modified registers than
modify original function even more. In original function I only place jump to the new code.

Real life use

Speaking of new code, where to place it? What if you need to inject more code than just simple in-line patches?
Well, while modifying ELF file to allocate more space for code seems possible or finding unused space in executable but
I’ve been using a different way.

It requires finding a file that always gets loaded in memory in early stages of game launch. It can be loading screen
texture or entire archive of files that game load first and never unloads (in my case conveniently named PRELOAD.pak).
Just append new code there and you’re good to go.

This is where another kmips strength comes in. For this auxiliary
code I can set startPc to where the game will load injected file and kmips will
take care of calculating target addresses. Moving the code to different spot is easy.
Of course this is done in compile time so it wouldn’t be useful on systems that use ALSR or when for some other reason
memory addresses are unpredictable. Which fortunately wasn’t a problem on PSP.

PSP executables can be relocatable but so far I’ve found no evidence of loading at different address than 0x8804000.
I verified that in PPSSPP emulator code.

kmips is a great help for assembling but it can only do that. In my project I’m using more of Kotlin DLS capabilities to make patches look a bit prettier. This is the syntax I’m using:

// assembling an external patch that will be placed in PRELOAD.pakprivatefuncreateAuxPatch(patchStart:Int)=assembleAsHexString(patchStart){run{// allocate section for new variablesvars.baseAddress=virtualPcvars.sCustomText=zeroTerminatedString("Some text")//...nop()}run{// start of a custom functionfuncs.customFunc=virtualPcvalctx=preserve(arrayOf(a0,a1,a2,ra))//...la(a0,t0)la(a1,vars.sCustomText)jal(funcs.memcmp)//call to original function from executableli(a2,10)ctx.restoreAndExit()}}// assembling patches applied directly to main executableprivatefuncreateEbootPatches(){with(ebootPatches){patch("Patch name #1"){change(0x0){li(a0,1)}change(0x4){li(a0,1)}}patch("Patch name #2",active=!debugBuild){change(0x20){li(t0,0x10)}change(0x30){lw(s0,0x0,s0)jal(funcs.customFunc)nop()}}}}// class storing address to global variablesclassVar{varbaseAddress:Int=0varsCustomText=0//...}// class storing address to function already present in main executable// as well as to those added by external patchclassFunc{valmemcmp=0x0898CF24varcustomFunc=0//...}

Not bad, eh?

Now I know that there already are assemblers that could do similar things. Still, I like the uniqueness of how this one works. It was a nice learning experience in both low level
assembly and exploring capabilities of high level Kotlin.
That’s it for now. Maybe in the future I will write some more about reverse
engineering and how I’m using Kotlin for it.

Version: 1.3.0 (LibGDX 1.9.6)

Added: VisUI#dispose (boolean disposeSkin)

Updated to libGDX 1.9.6

Excluded AsyncTask API from GWT compilation

I also have an announcement to make: I’ll be no longer maintaining VisEditor and VisRuntime projects. While it was my biggest project and one that was quite successful, it’s never reached the popularity I hoped for and was always surpassed by VisUI. It’s kind of funny considering that VisUI was indented to be internal part of VisEditor. I’d also like to move on to other projects. I feel like I’ve been stuck in the Vis world for too long.

I have to say thanks to everyone who contributed to it, whether it was issue reporting or creating pull requests and I’m sorry to everyone who hoped for more features. To make it clear this deprecation only applies to VisEditor, I’m still going to maintain VisUI project. However, VisUI has reached maturity some time ago and not much needs to be done to maintain it. I’m thinking about moving VisEditor sources to separate repository and renaming main repo to vis-ui. Still not sure, probably not worth it.

PSA: I’ll be no longer posting release notes on this site. They will be kept on GitHub releases page. You can follow me on Twitter if you want to get notified when I release new version of my libraries.

VisUI 1.0.2 was released. Also checkout new vis-ui-contrib project which has more extensions for VisUI and some custom skins.

Version: 1.0.2 (LibGDX 1.9.2)

Changed: #163 - When VisCheckBox or VisTextField is disabled and is marked as invalid then error border won’t be drawn.

Changed: #163 - Added SimpleFormValidator#setTreatDisabledFieldsAsValid (and it’s getter) - allow to control whether to mark form as invalid when invalid but disabled field is encountered. If set to true then all disabled fields are treated as valid, regardless of their state.

Defaults to true! Set to false to preserve old behaviour.

API Changed: DragListener: Draggable argument was added to each method

For some reason I wanted to make emulator for a really long time. There’s something entrancing about this idea that you need to write code to emulate original hardware. It’s quite hard project but it’s certainly fun and rewarding, if you are filling confident enough then definitely try making one!

I’m currently working on Game Boy emulator written in Kotlin using libgdx (cross platform game framework) and VisUI (my UI toolkit). In current state it has fully working CPU emulation (passes cpu_instrs and instr_timing tests), has integrated debugger and simple VRAM viewer. I’ll be focusing on GPU emulation now. Entire project is open source on GitHub so you can check it out here. In this post I would like to focus on general points and observations I made during making this project. I’ll focus more on technical details in next post.

How do I make emulator

Basically you need to write software equivalent of all original hardware parts, certainly biggest of which would be CPU. You start by collecting information about platform you want to emulate - in case of Game Boy it’s
quite well documented so this wasn’t hard. I found CPU manual, opcodes tables, official Nintendo development manual. There is also a lot of forum posts (and StackOverflow questions) from people who attempted this task.
Then you write CPU emulation, and then implement more and more components: memory controllers, timers, GPU, input, serial port, audio processing unit and so on.

You may be wondering what knowledge do you need to have to make emulator. Do you need a lot of background in low level programming? Not really, you don’t even have to know how to make games on the platform
you want to emulate. While it certainly helps that you know even the basic of Assembler etc., it is not needed and with enough self-denial you can learn things while you are making your emulator. That said this is not
a project that you should make using unknown language, libraries and tools - stick with what you know. I kind of ignored this by using new language - Kotlin however it is easy enough to pick up if you know Java,
and has pretty much the same tooling (IDE, build system) so it wasn’t that bad.

Choosing platform to emulate

Try not to pick up too complicated platform or you simply won’t be able to make it. I’ve often seen Chip-8 recommended as starting emulator, it is quite simple and should give you nice overview on how to start creating more complicated emulators. You can also be like me and go directly for something more complicated like the Game Boy. I’ve chosen it mainly because of my sentiment for this console - I still own working Game Boy Pocket with few games.

Tips

Get test ROMs

You will need to test your emulator somehow, of course you can use standard game ROMs but those won’t test it comprehensively. In case of Game Boy it’s very easy - there are test ROMs that were made to specifically test various part of hardware, CPU, timings, sound and so on. They don’t even need an display to run, they output information to serial port which is easy to emulate and some of them write test result in specific position in RAM. From those ROMs my emulator currently passes cpu_instrs and instr_timing tests. cpu_instrs tests almost every op code of CPU, instr_timing tests well.. instruction timing. And if you haven’t know timing is important when emulating something.

Don’t leave stuff half working

In Game Boy there is this thing called Memory Bank Controller (MBC). CPU addressing space is limited, if game is huge and it can’t fit into 32 KB, MBC is used to allow access to other ROM banks by switching available ROM bank
at specific memory address. When running cpu_instrs my emulator was stuck in loop, infinitely running next tests even though there are only 11 test sections. Turned out it wasn’t CPU issue and anything like that but unfinished implementation of MBC1 which did not allowed to switch ROM bank. It resulted in the same code being executed over and over. Lesson? Don’t do that or at least try not to, this can lead to very unexpected issues which may took much time to debug.

Create debugger

This is a must, if you want to efficiently find issues you will need a debugger. Even the simple one is fine, if you can pause execution and step through instructions it will be great help. I’ve observed interesting thing, Run to Line function was more helpful that breakpoints, so much that I haven’t even finished implementing breakpoints. You can see my debugger here. It is showing currently executed op codes, stack, CPU registers and flags status. You can also go to entered memory address and by right clicking instruction run emulator until that instruction is reached. I’ll leave details how exactly debugger is interacting with emulator for another article.

Use multiple info sources

I already mentioned this but it is really important, Game Boy is well documented but I was quite surprised to find so many discrepancies, seriously:

This is wrong - opcode E2 and F2 is 1 byte long, not 2. This single thing caused instr_timing to loop infinitely and took few hours to debug. I found out that only source that you can trust for instruction length and timing is the instr_timing test itself. You can get valid values from it’s source code. That site also get few timings for CB instruction wrong if I remember correctly but that is easy enough to find with instr_timing and not so devastating as wrong instruction length.

Timing for conditional instruction are completely wrong, it ignores the fact that the timing is different depending on whether action was taken or not.

HALT procedure description skips very important thing that interrupt will always wake up CPU, even if Interrupt Master Enable (IME) flag is not set.

Some instruction are missing details on how they affect CPU flags, instead you get: Flags affected: H: Set or reset according to operation - good luck figuring that out.

Use another working emulator

You can use another already working emulator with it’s debugger to test if your emulator is behaving (more or less) the same. Sure you may want not to do that, thinking it will make it too easy (it won’t). This can be somewhat compared to testing on real hardware although made much much easier.

That’s it for the introduction, my tweet gained some attention so I’ll probably write another post explaining more technical details of my emulator.

VisUI 0.0.1 was released on 5th November 2014. Initially meant to be internal VisEditor UI library now became my most popular project, getting about 1500 downloads each month.

Today I can finally announce that VisUI 1.0.0 has been released. Does that mean anything significant? Not really, maybe I will try make less breaking changes now. I’m glad that I was
able to work on this project for such long time. I would also like to thanks everyone who contributed to Vis project, either by reporting issues or by creating pull requests.