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.

Updates, Updates Everywhere

Spent a good amount of time in the last two days putting up more videos and pages around the place. Most changes have occurred over on my YouTube channel and on the Year2 page. I also have new pages for all of my Console Development projects, and my first attempt at a DirectX game engine, DacquoiseX. Hopefully this place is presentable enough for now, and I can get back to applying for jobs, and doing actual work.


The End of a Short Year

Not to say that it’s been an easy one, but this year sure has flown. This last semester was a particular challenge due to dealing with five modules at once, rather than the usual four (or the three we had in the first semester). What’s more, I really poured a lot of effort into every assignment, which has left me completely drained after the last five or so weeks of pure work.

I’m back at my parents’ place right now, catching a bit of rest before I engage in any personal projects, or go on the placement-searching-rampage that will be needed if I’m to find something good for next year. That said, having only handed in my last assignment yesterday, I’ve already set about grinding through my backlog of Anki cards and reading one of the many programming/maths books I’ve had on my shelf for some weeks.

This ‘blog’ has been long neglected while I’ve been working on my Interactive 3D and Console Development assignments, so I’ll try and overhaul it at some point with a proper Console Development page and information about my latest works. While I’d like to have a proper personal website, I’ve no experience in web development and it’s not on my agenda right now. I’ll even put up source once we’re a safe distance away from assignment submissions, though I’m not sure how much of my work with the PSP SDK is mine to broadcast, and I won’t put up source for my Android game, Mega Driller Mole, because my friends at Pillowdrift are considering taking over that project.

Three Weeks Freedom

Lectures an tutorials are of course important, but it has to be said that the journey to and from the university, and their inflexible schedules are rarely convenient things. More and more of late I’m finding I’d rather be off investigating things for myself than being forced down particular avenues. I’d love, for instance, to be looking into WebGL and x86 assembly right now, having greatly enjoyed the time I spent with MIPS last semester. Meanwhile, I feel that modules like Team Software Development have long since served their purpose in teaching me in the value of effective teamwork strategies, and now now do nothing but eat into my time. It was with great relief last weekend that I entered the start of a three-week break from such activities.

Three weeks to get well ahead with my assignments, three weeks to get some more job applications off, three weeks to resume my studies of the Korean language, three weeks to look into WebGL or x86 assembly, three weeks to properly maintain my online presence or pursue my artistic interests. So many choices.

One week of that time has already elapsed, and I elected to spend it in the labs, where the PSP dev kits are, working on an optimized, billboarded, particle system for our Console Development 2 assignment. This is the module I’ve enjoyed the most this semester, and the module within which I feel that I have learned the most. Which of these is resultant of the other? Well, personally I think that it’s reciprocal. I’ve not only learned about PSP specific programming and optimization, but also finally found the opportunity to gain an understanding of threading – it’s a lot simpler than it seems on the surface – and undertake a complicated project in straight C. I’ll explain more about this assignment when it’s all tied up.

Speaking of threading, this has also been a feature of my Operating Systems and Mobile Development modules. My OS assignment is pretty much complete, and of little interest – it’s a simple benchmark of communications between processes and threads using the Windows API, and I plan to clear up the written part in the coming week. As soon as my PSP work is done I’ll sort out the write up for that too, leaving me only three modules to worry about when I go back for the last three weeks of the semester.

My Mobile Development project is a 2D game for Android. I’ll make another post about this in the coming weeks, but for now know that it’s a simple points-orientated game about drilling, I’m using the incredible libGDX framework, and the game may someday see itself published if my friends at Pillowdrift decide to take it on once I’m gone.

By gone I mean off on placement at whatever company wants me. I’m still looking, and I’m not worried about the time yet – the deadline is the end of summer and I’m sure I’ll find something excellent. If you’ve found your way here via my CV, a belated welcome to you! I hope you’ll take a quick look at my work under the Projects tab. Anyhow, my housemates and another friend are setting up shop as an indie company next year, and while I wish them the best of luck, I’d rather siphon the experience of industry veterans and prove myself in the real working world. I’ve told them they can have my Mobile Development project, polish and publish it if they wish, so I’m trying to keep the project as tidy and flexible as possible.

Seems there’s only one module I’ve yet to talk about, and this one comes with pictures! No really, I’d happily put up pictures of my other projects but I don’t have access to everything since I’m at my parents’ place right now. Interactive 3D Graphics Programming has taken me through the pains and pleasures of shaders lately, including a brief expedition into PIX to determine the root of some HLSL failures. As best I can tell I now have per-pixel diffuse and specular ambient, directional, point and spot lights working, and a system in place for managing them, attaching them to nodes in a scene graph for transformation. I recently added a similar method for attaching cameras to nodes and now need to re-implement my controllable camera nodes. By re-implement, I mean replace with controllable transformation nodes and attach cameras to those. Specular lighting looks fantastic on my terrain, though the terrain itself is a little bumpy, and I probably should decrease it’s shininess value. The one thing that’s been bugging me with my framework for this project is my use of DirectX constant buffers. Currently I only allow for a single constant buffer per shader set, and all of it’s data is copied across every time something draws. A better, more efficient, more flexible system would be to have multiple constant buffers updated hierarchically in my scene graph. In this way lighting data and other items would only be copied across when they are actually changed, saving a significant amount of time. Implementation of this system is of course dependent on the impending deadline, and seems unlikely, as I also need to implement render targets, collisions, player physics, and a demo. Still, you don’t learn the pitfalls until you try things, and I’ll remember this for future projects.

Let’s wrap this up with some screenshots from my DirectX engine, DacquoiseX. The model of Princess Peach is an adaptation of retrotails‘s over on Google 3D Warehouse, and I intend to use it for my current PSP project, recreating a scene from the ice levels from Super Mario Brothers 2 in 3D, with peach standing on the back of a black whale, spurting watery-foamy-particle-goodness from it’s spout-hole. The demo for this project? Well, that’s gonna be a bit stranger…

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…

PSP Demo Video!

So I had a chat with one of the Techs from uni yesterday and managed to get a video capture of my PSP Demo from Console Development last semester. It’s not the greatest quality rip, but then the PSP’s screen is pretty crappy too. That said, it is much darker, grainier, and more contrasty than the demo appears when running on a PSP.

I overlaid the music from the closing titles on which the demo was based in VirtualDub while I was fixing the aspect ratio and tweaking the contrast, since I didn’t get time to actually figure out audio streaming on the PSP. Yes, the frame rate is poor because of the high-poly hummer model I used for See-Through, and a few bits of code which I’m going to look into optimising on monday, since this semester’s Console Development module is all about optimisation, and I get to play with the PSP tuner for monitoring the performance of my applications.

I’ll embed the video below and get back to work on the here and now. Maybe I’ll be back later to post about Battenberg. Maybe I won’t.

See-Through, PSPudding

A follow-up to, and second entry regarding.

The fruits of my labour: A cleaned up photograph taken on my phone of my 3D PSP scene part-way complete, and a lovely reflection of myself in the screen.

Sadly I neglected to take a photo of the completed version, which utilised point lights for the vehicle’s headlights, and set ambient lighting to 0x00000000 so that you would never see the ends of the road plane. The camera is rotatable, the car is moveable (with its headlights), the Mudkips – which are spawned randomly on the road ahead – are squishable, and the program keeps a count of your current kill streak at the top left, rather than the total kill count shown above. I won’t detail the workings of my solution for this assignment, as it was put together in quite a short amount of time using the incomprehensible samples and documentation provided by Sony, so I’m sure it’s not optimal. Hopefully PSP work will continue next semester and I’ll get to make something I can really be proud of.

Despite being guided towards using C for PSP development due to our lecturer’s preference, I chose to use C++ because of the ambitious concept of my demo, and my greater wealth of experience working with C++ than C. I really think this was the right thing to do as it allowed me to throw together a rough framework very quickly and get to the more complicated (and fun) parts of developing my demo. In this way I’ve managed to gain experience with numerous parts of the PSP API over a short period of time, and needless to say I’ve learned a lot.

Problems? Well well well:

I’d never used Makefiles before this project, so that was a challenge in the beginning. Once I’d wrapped my head around the syntax and failed to implement automatic dependency generation due to some timing bug, I settled on a solution which used multiple Makefiles to go through headers, src, and assets directories and compile and link any cpp file in sight, as well as convert all of my textures and models and send everything to an output directory.

The PSP is really not very powerful, so I had to be careful with the quality of models and textures I used. The 15 fps you mark in the photograph above is the result of a ridiculously high-poly model of a HummerH1 I had to tear limb from limb in order to get into memory. Once it was in memory I continued to strip the model of course – currently it has about a quarter of the number of vertices it originally had, and the textures are much, much smaller.

For the life of me I could not get spotlights to look good as the headlights of the Hummer. This was partly due to the lack of per pixel lighting and low number of faces in the road, but also due to a lack of understanding of the parameters, which the documentation and samples once again failed to assist me in.

Finally, I’d like to have gotten audio working so I could have played a certain theme song along with my demo, but time constraints, other deadlines, and the lack of any feature-full library for streaming audio prohibited me from doing so. I still really want to get this working though, so maybe I’ll get chance to sort it out during the study weeks in January.

But enough of my problems; what I really want to do now is get a video of my scene up on YouTube, but that, like Pastry3D’s video, will have to wait till I go back to university. Unfortunately I don’t have the money to shell out for a PSP devkit of my own – nor do I think Sony would sell me one if I did.

We don’t talk about Ludum Dare 22

Okay, it wasn’t all that bad. The theme was ‘Alone’, as I had hoped, and we had plenty of good ideas to play with before coming up with a really good concept, that almost panned out. I’m back at home now, having had a couple more days rest since then, and looking back at what we made from the outside, it’s really not bad. You can play our finished game here. Problems? Well, we started out completely unprepared, had to whip together tile engine out of thin air and make do with poorly outlined classes as we resorted to sloppy coding far too early. We’re planning on entering again at the next opportunity though, as a team or as individuals, with all the knowledge and experience garnered from this first attempt. It can only get better.

Being back at home is also giving me real opportunity to stress test the laptop I bought a few months back from PCSPECIALIST, and I am very impressed. Devil May Cry 4 looks better than it does on an Xbox 360 (dated, perhaps, but still a damn pretty game), the keyboard is spaced perfectly and tap taps in a satisfying manner, the screen is crisp, bright, perfect, and the battery life isn’t at all bad if you’re just browsing. With this I look forward to the rest of my christmas break spent searching for work placements, getting a head start on DirectX for next semester – and playing a few games of course.

Now that I’m perfectly work-free for the time being, I WILL get around to updating the other pages around here, though I won’t be able to get a video of my software renderer up until I get access to my desktop, or one of the labs computers – my laptop isn’t quite good enough to deal with video recording and software rendering at the same time. I also have a few pictures of my PSP dev work that I took on my phone, directly from the ghosty, reflective, crappy screen of a PSP in the over-lit labs, but I may be able to clean these up enough for show.

I’ll be back soon, with a massive drill.

From Deadline to Deadline

So I got my assignments in a couple of days before the deadline, and I’ve had a more relaxing couple of days since then – I think I’ve earned them. I also think it’s important that I got in a bit of relaxation so I’m not already burnt out at the start of the 22nd Ludum Dare which starts tomorrow morning. Me and the guys I live with are participating as a team – pillowdrift – hoping to make something awesome out of whatever theme we get. Personally I’m routing for ‘Alone’ or ‘Moon’, but there are some other themes in the final round that I’m really not excited about.

And yes – I will be updating this space with information on my completed assignments, including Pastry3D, screenshots of my demo application, maybe even a video and downloads. My PSP graphics demo assignment is another story – I may be able to get a video-out recording of it next semester, but we’ll have to wait and see.

MIPS, Snake, PrimLib

Note: This post is rather out of date now. There’s a page on this over here. Feel free to read on, but note that one or two of the links to elsewhere will not work.


Today it’s all about MIPS. This post’ll get a shout out over on the Console Development page I just created, but I felt I should keep all the MIPS stuff concentrated in a post since it didn’t really warrant its own page and I didn’t want to pollute the Console Dev page.

MIPS is a RISC (reduced instruction set computer) architecture used in CPUs such as the 32-bit MIPS Allegrex R4000 found in Sony’s PlayStation Portable. Throughout the first semester of Console Development we’ve been programming simple applications using MIPS assembly language. Personally, I find programming in assembly language very relaxing when compared to regular programming, and I hope to soon find the time to look into 6502 assembly as a step towards a long-standing dream.

Following is the description of my main two achievements to date using MIPS: Snake, and PrimLib.

A few days after being introduced to the MARS MIPS simulator I dropped on the Bitmap Display and Keyboard and Display Simulator tools included with it. Being primarily a games programmer, the first thought that occurred to me was ‘I can use this’. Move ahead a few hours and I had the basis of a working snake game written in assembly. Another few days and a recode later the game was near complete, but there was one error that reared it’s head, whereby the entire MARS simulator would randomly crash while running snake.

As it turns out, the fault wasn’t in my code, but in a threading issue with the Keyboard and Display Simulator. An hour or so of poking around in the java source provided with MARS enabled me and my friend to make a quick fix to stop the lock-up from occurring, and I sent a quick email off to about the issue.

My MIPS Snake game is now complete and I’ll provide the assembly for it should you wish to try it out,. I warn you though: it won’t run for long unless you care to fix the same problem I did. I will not distribute the modified version of MARS I’m using – that’s not my place.

How Snake Works
The main issue I ran into when programming snake was how to store data about all the entities. But at some point I discovered that the two alpha bytes in the colours used for the display were simply being wasted, so I opted to store only the colour data for the display, the address of the head and tail of the snake, and store all other information in the alpha bytes using different numbers for different meanings. As the snake moves around a new head segment is placed at the front, and the old head position is replaced with a block of the same colour, but with a code in the alpha bytes indicating the direction of the new head. When that segment is at the address in the tail register the direction stored is recovered and used to swap the address in the tail register to the next segment along. The old segment is then replaced with the background colour so that the snake’s tail follows its path. Information on food and walls is also stored in the alpha bytes, and this system could potentially be used to identify an even larger number of entities.

DOWNLOAD (*.asm)

PrimLib was written for the first Console Development assignment. It’s a collection of functions which draw primitives to the Bitmap Display included in MARS. The assignment was marked for efficiency and the algorithms implemented. Out of personal preference I chose to prioritize reliability at the sacrifice of some performance by ensuring that all of my functions performed boundary checks and clipping where necessary. Going out of bounds in the Bitmap Display tool doesn’t usually crash MARS, but it does wrap around and produce undesirable results.

I won’t go into much detail about PrimLib, and I will not distribute the source so soon after handing in an assignment (lest I be accused of plagiarizing myself o_O). Most of the algorithms are fairly easy to implement and/or are based on existing algorithms such as the Bresenham’s Line Drawing and Cohen-Sutherland Line Clipping algorithms. The screenshot seen above is running the test data I implemented to stress test all of the algorithms implemented. What remains then is to list the functionality of PrimLib:

EDIT 27/02/2012: Uploaded the assembly code for PrimLib here:
Download (*.asm)
EDIT 14/06/2012: Oh, I gave this it’s own page a while ago. Nevermind.

setpixel(int x, int y, int colour)
drawline(int x1, int y1, int x2, int y2, int colour)
drawrectangle(int x, int y, int width, int height, int colour)
drawfilledrectangle(int x, int y, int width, int height, int colour)
drawpolygon(point[] points, int count, int colour)
drawcircle(int x, int y, int radius, int colour)
drawfilledcircle(int x, int y, int radius, int colour)
clipline(int x1, int y1, int x2, int y2)

That’s all for now. I’ll go sort out that Console Development page, drink some milk, and get some sleep before tomorrow’s early start.