CS 2110 Homework 8 GBA Solution

1 Overview
1.1 Purpose
The goal of this assignment is to make a C program that will run on the GBA emulator. Your program will be an interactive graphical application. Your program can be a game, or any other interactive program that meets the requirements outlined below.
While completing this program, you will learn about low level hardware programming in C. This program is similar to how you would write device drivers or parts of an operating system, which are typically written in C. The GBA devices (screen, buttons, DMA controller, etc.) are accessed via memory-mapped I/O. You will access specific hard-coded memory addresses in your C code. You will gain experience with bit masks and bitwise operators to set bits in the device registers.
The GBA is also a very slow computer. You will learn tricks to optimize the performance on a resourcelimited hardware device (such as DMA, integer math instead of floating point, and so forth).
1.2 Tasks
You will write an interactive graphical application in C that runs on the GBA emulator. This application can be a game, or any application that meets the feature and technical requirements below. For ideas on what you could do, please see What to Make in the Appendix. This is an open-ended assignment. Just be sure that your program meets all the requirements.

We have provided some resources to help you get started. You can use the outline structure of a program, and fill in code to do what your application specifically does. You should have at least one .h header file and one .c file. You can have more if you wish.

1.3 Criteria
You will be evaluated on meeting all the feature requirements and technical requirements described below.

You will also demo this assignment to one of your TAs.
This assignment offers an opportunity for you to be creative if you want to. However, creativity (and artistic ability) are NOT required. Your grade will be based on meeting all the requirements outlined below.
If you write a very creative program, but do not meet all the requirements, you will lose points. On the other hand, if you write a minimal program that works and meets all the requirements, but is not exciting, you will get full credit. So please do not feel pressure to be creative if that is not your personality, or if you do not have time to do so.
2 Before You Start
2.1 Resources
To tackle this homework, we’ve provided:
• A gba.h file that contains all of the necessary GBA declarations such as DMA, videoBuffer, etc.
• Several other files which contain more “starter” code to get you rolling. See Section 5.7 for details.
• A makefile that you can use to compile and run your program by typing or make med In addition, here are some other helpful resources:
• Lab Guides
• Lecture Slides L17 and L18
• TONC - full documentation of the GBA, including advanced features
• Lecture Demo Code: Canvas>Files>Source Code>GBAdemo
• the Appendix, including GBA Coding Guidelines

Feel free to use code from class resources as you need to, but as always, not from your friends or random sketchy internet sites.
Your main.c should be something different from lecture code, since in this homework you will be creating your own program. But, you should keep the core setup with videoBuffer, MODE 3, waitForVBlank, etc.
Additionally, we want to make one point very clear: please do not rehash lecture code in your program. This means that you are not allowed to just slightly modify lecture code and to call it a day. If we open your program and we see several boxes flying in random directions, that will be a very bad sign, and you will not receive a very pleasant grade.
• Do not use floats or doubles in your code. Doing so will slow your code down greatly. The ARM7 processor the GBA uses does not have a floating-point unit which means floating point operations are slow as they are done in software, not hardware. Anywhere you use floats, gcc has to insert assembly code to convert integers to that format. If you do need such things that you think requires floats or doubles, you should look into fixed point math.
• We strongly recommend that you do not use dynamic memory allocation in your program. Although malloc() will work on the emulator, it is not necessary. Instead just use arrays large enough to hold all possible images (game characters, etc.) that you could possibly have at one time. You can use an array of structs, as in the lecture code example.
• Only call waitForVBlank once per iteration of your main loop
• Keep your code efficient. If an O(1) solution exists to an algorithm and you are using an O(n2) algorithm then that’s bad (for larger values of n)! Contrary to this only worry about efficiency if your program is showing signs of tearing!
• If you choose to use more advanced GBA features like sprites or sound, making them work is your responsibility; we (the TAs) do not really know how they work, so we sadly can’t help you.
3 Requirements
3.1 Feature Requirements
• Include a readme.txt file with your submission that briefly explains the program and the controls.
• You must use 3 distinct images in your program, all drawn with DMA.
– Two full screened images sized 240x160. One of these images should be the first screen displayed when launching your program.
– A third image which will be used during the course of your program. The width of this image must be less than 240 pixels and the height of this image must be less than 160 pixels.
– Note: all images should be included in your submission.
• You must be able to reset the program to the title screen AT ANY TIME using the select key. This resets the ENTIRE program, including game state.
• Button input should visibly and clearly affect the flow of the program
• You must have 2-dimensional movement of at least one entity (an entity that moves both left/right and up/down). One entity moving up/down and another moving left/right alone does not count.
• Use text to show progression in your program. Use the example files from lecture as reference. You can also find more information in Tonc:http://www.coranac.com/tonc/text/text.htm

• There must be no tearing in your program. Make your code as efficient as possible!
3.2 Technical Requirements
• Your program must be in Mode 3! – Mode 3 should be the very first thing set in the main method.
• You must implement waitforVBlank()!
• You must use at least one struct.
• You can create your own header file or use the game.h header already available. You must move any #defines, function prototypes, and typedefs to this file from your code, along with your extern videoBuffer statement if you wish to use videoBuffer in other files. Remember that function and variable definitions should not go in header files, just prototypes, extern variable declarations, and struct declarations.
– As always, do not include .c files into other files. Only .h files should be included and .h files should contain no functional code.
– It is optional for you to use other .c/.h files to organize your logic if you wish. Just make sure you include them in your submission and Makefile.
4 Deliverables
Please archive all of your source code files as a zip or a tar and upload to Gradescope under the Homework 8 assignment. This includes all .c and .h files needed for your program to compile and run. Do not submit any compiled files. You can use make clean to remove any compiled files, or make submit to remove compiled files and create the tar archive!
5 Appendix
5.1 Appendix A: What to Make?
5.1.1 Example Programs
Interactive Storybook:
• Recreate a story from a movie or a book using the GBA
• Use text to narrate what is currently happening in the scene
• Use the controls to advance to the next scene or control a character within the scene
• Smooth movement (for any moving characters or objects)
• Start off with a full screen title image and end with a full screen credits image
• Characters represented by structs
Galaga:
• Use text to show lives
• Game ends when all lives are lost. Level ends when all aliens are gone.
• Different types of aliens: there should be one type of alien that rushes towards the ship and attacks it
• Smooth movement (aliens and player)
• Aliens and the ship represented by structs
The World’s Hardest Game:
• Smooth motion for enemies and player (no jumping around)
• Confined to the boundaries of the level
• Enemies moving at different speeds and in different directions
• Sensible, repeating patterns of enemy motion
• Enemies and the player represented by structs Flyswatter:
• Images of flies moving smoothly across the screen
• Player controlled flyswatter to swat the flies
• Score counter to keep track of how many flies have been swatted
• Fullscreen image for title screen and game background
• Enemies and the player represented by structs
5.2 Appendix B: GBA Coding Guidelines
5.2.1 Building and Running your Code
To build your code and run the emulator, run
$ make med
5.2.2 Images
As a requirement, you must use at least 3 images in your program. To use images in GBA, you will first have to convert them into the suitable format. We recommend using a tool called nin10kit, which is pre-installed on the Docker image, or you just installed using the command above.
You can read about nin10kit in the nin10kit documentation (there are pictures!):
https://github.com/TricksterGuy/nin10kit/raw/master/readme.pdf nin10kit reads in, converts, and exports image files into C arrays in .c/.h files ready to be copied to the GBA video buffer by your implementation of drawImageDMA()! It also supports resizing images before they are exported.
You want to use Mode 3 since this assignment requires it, so to convert a picture of smelly festering garbage into GBA pixel format in garbage.c and garbage.h, resizing it to 50 horizontal by 37 vertical pixels, you would run nin10kit like
$ nin10kit --mode=3 --resize=50x37 garbage garbage.png This creates a garbage.h file containing
extern const unsigned short garbage[1850];
#define GARBAGE_SIZE 3700
#define GARBAGE_LENGTH 1850
#define GARBAGE_WIDTH 50 #define GARBAGE_HEIGHT 37
which you can use in your program by saying #include "garbage.h".
The garbage.c generated, which you should add to the Makefile under OFILES as garbage.o if you plan to use it, contains all of the pixel data in a huge array:
const unsigned short garbage[1850] =
{
0x7fff,0x7fff,0x7fff,0x7fff,0x7fff, // ...
0x7fff,0x7fff,0x7fff,0x7fff,0x7fff, // ... // ...
0x7fff,0x7fff,0x7fff,0x7fff,0x7fff, // ...
0x7fff,0x7fff,0x7fff,0x7fff,0x7fff, // ...
};
We’ve included garbage.png, garbage.c, and garbage.h in the homework zip so you can check them out yourself. To draw the garbage in your own game, you can pass the array, width, height to your drawImageDMA() like drawImageDMA(10, 20, GARBAGE WIDTH, GARBAGE HEIGHT, garbage) (to draw at row 10 and col 20). The next section will cover drawImageDMA() in more detail.
5.2.3 DMA / drawImageDMA
In your program, you must use DMA to code drawImageDMA.
The GBA screen is represented with a short pointer declared as videoBuffer in the gba.h file. The pointer represents the first pixel in a 240 by 160 screen that has been flattened into a one dimensional array. Each pixel is a short and has red, green, and blue channels.
If you want to wait, then you can choose to implement drawImageDMA without DMA and then when you learn DMA rewrite it using DMA. Your final answer for drawImageDMA must use DMA.
You must not use DMA to do one pixel copies (Doing this defeats the purpose of DMA and is actually slower than just using setPixel!). Solutions that do this will receive no credit for that function. The prototype and parameters for drawImageDMA are as follows.
/* drawImageDMA
* A function that will draw an arbitrary sized image* onto the screen (with DMA).
* @param row the row coordinate to start drawing the image at
* @param col the col coordinate to start drawing the image at
* @param width width of the image
* @param height height of the image
* @param image pointer to the first element of the image
*/ void drawImageDMA (int row, int col, int width, int height, const u16* image) {
// Todo implement :)
}
Protip: if your implementation of this function does not use all the parameters that are passed in then you are not implementing the function correctly. You should know that DMA acts as a for loop, but it is done in hardware.
5.2.4 GBA Controls
Here are the inputs from the GameBoy based on the keyboard for the default emulator vbam:
Gameboy Keyboard
Start Enter
Select Backspace
A Z
B X
L A
R S
The directional arrows are mapped to the same directional arrows on the keyboard.
5.2.5 C Coding Conventions
• Do not jam all your code into one function (i.e. the main function)
• Split your code into multiple files (for example, you can have your main logic in your game files, but other helper functions for drawing or assessing the game state in external files)
• Do not include .c files into other files. Only .h files should be included.
• .h files should contain no functional code.
• Comment your code, and comment what each function does.
5.2.6 Making Sense of the Files
• Makefile
• game.c
This file contains a state machine which ultimately calls all other functionality in the program. It is also the main entry point to the entire application.
• game.h
This file should contain any function prototypes and structs that you create.
• gba.h
This file contains a large collection of useful macros and constants which will help primarily with GBA-specific tasks. These include macros for handling GBA input, DMA graphics, and general GBA graphics.
The file also contains an extern declaration of the font data found in font.c, which is necessary for drawing text.
This file also contains some prototypes for functions in gba.c.
• gba.c
The functions you will write in this file do the “dirty” work, executing graphics updates with both DMA and non-DMA strategies. All of this code will be very specific to the GBA platform and the way it handles graphics.
The file also comes with some prepackaged functions for drawing text.
• font.c
Simply exists to store a large amount of font data. No real need to mess around with this file.
• Various Image Files
When you create your own image files, you will need to include the relevant header files in any file you’d like to reference these images from. The data stored in each of these files (and how to create them) is pretty well explained in section 5.3.
• Personal .c files and .h files
You are heavily encouraged to split your code up into separate .c and .h files! Do not put everything in your main method. Keep your code organized and readable.
NOTE: For any .c files you create please place its respective .o file in the OFILES variable in the Makefile. For example, if you create newFile.c you will need to update the Makefile to reference the newFile object file.
OFILES = gba.o font.o game.o images/garbage.o newFile.o
5.2.7 Submit
To submit your code:
1. Make sure your code compiles by running make med
2. Clean the code by running make clean
3. Create the submission tar by running make submit
4. Turn in submission.tar.gz on gradescope!
5.2.8 Installing Dependencies
If you are not using Docker, you will have to install some dependencies before you are able to begin using GBA. Run the following commands (don’t worry about these if you are using Docker).
$ sudo apt update
$ sudo apt install gcc-arm-none-eabi cs2110-vbam-sdl mednafen cs2110-gba-linker-script nin10kit
Note that this requires Brandon “The Machine” Whitehead’s CS 2110 PPA, which you should’ve added earlier in the class for complx. If you didn’t (or this is a new VM/dual boot or something), run the following and then run the two commands above again:
$ sudo add-apt-repository ppa:tricksterguy87/ppa-gt-cs2110
5.3 Appendix C: Rules and Regulations
5.3.1 General Rules
1. Starting with the assembly homeworks, any code you write must be meaningfully commented. You should comment your code in terms of the algorithm you are implementing; we all know what each line of code does.
3. Please read the assignment in its entirety before asking questions.
5. If you find any problems with the assignment it would be greatly appreciated if you reported them to the author (which can be found at the top of the assignment). Announcements will be posted if the assignment changes.
5.3.2 Submission Conventions
1. All files you submit for assignments in this course should have your name at the top of the file as a comment for any source code file, and somewhere in the file, near the top, for other files unless otherwise noted.
3. Do not submit compiled files, that is .class files for Java code and .o files for C code. Only submit the files we ask for in the assignment.
4. Do not submit links to files. The autograder does not understand it, and we will not manually grade assignments submitted this way as it is easy to change the files after the submission period ends.
5.3.3 Submission Guidelines
2. You are also responsible for ensuring that what you turned in is what you meant to turn in. After submitting you should be sure to download your submission into a brand new folder and test if it works. No excuses if you submit the wrong files, what you turn in is what we grade. In addition, your assignment must be turned in via Canvas/Gradescope. Under no circumstances whatsoever we will accept any email submission of an assignment. Note: if you were granted an extension you will still turn in the assignment over Canvas/Gradescope.
5.3.4 Syllabus Excerpt on Academic Misconduct
Academic misconduct is taken very seriously in this class. Quizzes, timed labs and the final examination are individual work.
Homework assignments are collaborative, In addition many if not all homework assignments will be evaluated via demo or code review. During this evaluation, you will be expected to be able to explain every aspect of your submission. Homework assignments will also be examined using computer programs to find evidence of unauthorized collaboration.
You are expressly forbidden to supply a copy of your homework to another student via electronic means. This includes simply e-mailing it to them so they can look at it. If you supply an electronic copy of your homework to another student and they are charged with copying, you will also be charged. This includes storing your code on any site which would allow other parties to obtain your code such as but not limited to public repositories (Github), pastebin, etc. If you would like to use version control, use github.gatech.edu
5.3.5 Is collaboration allowed?

Figure 1: Collaboration rules, explained colorfully