MARS MIPS Simulator Lockup Hackfix

If you are attempting to use Missouri State University’s rather excellent MIPS Simulator and IDE, MARS, to develop an application which uses the bundled Keyboard and Display Simulator (though it seems  unlikely that you would be doing so seriously today), you may encounter a sporadic bug where the entire MARS application will lock-up, and you have to end-task it.

I personally encountered this while attempting to make a simple Snake clone just over a year ago, during the Console Development 1 module of my (WIP) BScH Computer Games Programming degree and the University of Derby. At that time me and a friend tore open the MARS .jar in order to probe for the cause of this, and were actually able to implement a little work around. Since posting about this project here and putting a video demonstration up on YouTube, I have been asked several times about how we were able to do this, and rather than repeatedly send out links to the email I originally sent to Ken Vollmar, I thought it might be nice to have a decent guide I can direct people to.

Note that the below instructions cover a quick ‘n’ dirty fix, which may introduce other errors (though I haven’t noticed any). This is why I have elected not to just hand out a new .jar, though I could happily do so under the MIT License. I didn’t then have the know-how to properly dig into the problem, and since lengthly debugging of broken applications is my full-time job right now, I’d rather not do so in my free time.

What You Will Need
Java Tools – Likely an IDE like Eclipse
Archiving Tools – 7Zip or a similar application for looking into the .jars
A copy of MARS.jar

I’m going to assume you’re using Eclipse, because that’s all I know, so you may have to dig for some of the options if you’re using something else. I will assume you may never have encountered Eclipse or Java before though. Java is a lot like C#, but Eclipse is a bit different from Visual Studio. If you’re better at Java than me, do please let me know where I’ve done things the hard way round, and feel free skip the easy sections.

As another heads-up, I’m also using Windows, so this experience may be rather different for anyone hailing from the OSX or Linux world (I’m told that the creation of an executable .jar on Linux is free from some of the woes I encountered).

Project Setup
Firstly, create a new folder, open up Eclipse and select this folder as your workspace. I called mine ‘Mars_4_1_Mod’. You then need to create a new project in this workspace (File->New->Java Project). Name your project, and hit ‘Finish’. Note that my JRE is set to JavaSE1-1.7. This setting may be important – I’m not overly familiar with it myself.

Now right-click on the project in the Package Explorer, and select ‘Import’. You want to import the contents of MARS.jar to the project, so select General->Archive File from the dialog, browse to your copy of MARS, and hit ‘Finish. Your Package Explorer should now look something like this.


Finally, you need to make sure that Eclipse can find the source code in the project. To do this, right-click on your project and select ‘Properties’. Go to Java Build Path->Source, click ‘Add Folder’ and select your project root. You can fiddle with exclusions and stuff if you want, but I preferred the shotgun approach for what it’s worth.

The Fix
You should now be able to build and run the project (Run->Run As…->Java Application, select ‘Mars’ and hit ‘OK’). Mars should run normally and freeze as expected. Alternatively, if you run it via Run->Debug As…->Java Application then you will be able to suspend the application from Eclipse when it locks up, and then investigate the lock-up state for yourself from the Debug perspective.

Great, now go to ‘Navigate->Open Type…’ and use it to find your way to Navigate to line 210. It should look like this:


This is our culprit – a threading issue, a deadlock caused by this function call and another from To implement the workaround as I have, you simply need to replace this line with the following:

//This call caused a deadlock sometimes when using the keyboard and display simulator.
//The syncronized block below simply plucks out the necessary call from
//updateMMIOControlAndData, which is where this call would take us in the end.
synchronized (Globals.memoryAndRegistersLock) {
   try {
      Globals.memory.setRawWord(RECEIVER_CONTROL, 0);
   } catch (AddressErrorException e) {

Now if you run Mars through either Run or Debug you should find that the freeze-up never happens. Feel free to poke around if you want to know more about the original issue – but if you’re just trying to work with Mars for a personal project, this should be good enough.

If you’re a student working on a project for your studies you may wish to provide your marking tutor with a copy of your modified MARS application alongside your assembly program. Now, after much pain I DO have a working .jar of this, and I will detail it’s creation beneath in case you run into difficulties as well, though it’s probably stupid because I’m not experienced enough with Java to know what exactly prevented me from doing it the normal way.

In the beginning it seems there are two options – you can export a Runnable .jar from Eclipse (File->Export->Java->Runnable JAR File – make sure to select ‘Package required libraries into generated JAR, ignore the warnings), or you can try running the script, ‘CreateMarsJar.bat’ which should be in the root of your project.

For me at least, the script somehow creates a .jar with the same bug as the original, and the exported ‘Runnable’ .jar…won’t run. The way around this is to make a copy of the original Mars.jar, open both it and your Eclipse-exported jar using 7Zip or a similar application, and copy the ‘mars’ folder (contains the compiled .class files) from your version into the copy of the original, replacing it’s own.Delete your exported jar and run the copy of the original – it should now perform as well as the version you launch from Eclipse.

Thanks and Stuff
Thanks go to my friend Bombpersons, without whom I might not originally have bothered to look into this issue. If you have any further information on this issue, any corrections to the information provided here, or struggles in doing this yourself, please do get in touch.

MIPS code, 저는 너무 바빠요!

I’m so busy this semester. Five modules at once, lots of assignments, and we’re already so far into the second semester. I want to post a few updates on what I’m up to, I just need to tie up a few loose ends before I have anything decent to show to…whoever is reading this.

Anyhow, I thought it was about time I uploaded the MIPS assembly code for the first console development assignment from last semester, so I’ll be dropping in a link below and amending this page with one too.

Check out that page if you want any information about the project, or click here to see the assembly code. If you have MARS then you’ll be able to run the demo, unlike my snake game which crashed unless you could be bothered to look up the threading issue in the Keyboard and Display Simulator included with MARS, and fix it, like me and my friend did one fateful night.

While the demo may not be too impressive, and there aren’t many drawing functions, writing PrimLib was great challenge. I really enjoyed my time spent with assembly programming – optimizing things at such a low level is surprisingly compelling, implementation of the logic forces concentration, and I generally found the whole experience quite relaxing (except for the debugging – that was horrifying, but still kind of fun).

The greatest thing about my work in MIPS was that it was directly relevant to my work in Introduction to 3D Graphics at the time, where I also had to write Cohen-Sutherland line clipping and Bresenham’s algorithms in C++. It may surprise you to know that I wrote the Cohen Sutherland algorithm in MIPS first, then converted it to C++. Honestly, I might not mind working in assembly professionally if the opportunity ever arose, and my desire to throw down some 6502 for the NES is still as strong as ever.

[Assembly Code]

Enough about that though. I want to give a quick shout out to one of my current time-holes and then head back to more important matters.

Ever heard of Lang-8? If you’re learning a language at an intermediate or advanced level, Lang-8 could be an incredible way to boost your motivation, confidence, and get accurate corrections for real, native speakers. The site is free to use, and relies solely on the kindness of others. Simply put, you make an account, tell it what language you speak, and what you’re learning, then post entries about whatever you like in the language you’re learning. Random strangers from around the globe (preferably native speakers) then post corrections and comments on your entry, and the site even attempts to match you with your language counterparts and suggest friends.

I’ve been using Lang-8 to practice my Korean, even though I’m at a very basic level. There are a lot of Korean people on there learning English and, it seems, not many the other way round, so I’ve been inundated with friend requests. Although I’ve only found time and energy to post three entries of my own, I’ve found crawling and correcting other people’s entries to be almost as addictive as crawling YouTube – albeit in a more altruistic way…