




                 GameBoy Advance ROM Manipulator (GBARM) 1.0




                =============================================









                           #001 - Table Of Contents




                          --------------------------









         #001 .................................... Table Of Contents




         #002 ......................................... Introduction




         #003 .............................................. History




         #004 ........................................... How To Use




         #005 ............................. GBA ROM Header Structure




         #006 ....................................... GBARM Commands




         #007 ...................................... Copyright Notes









                             #002 - Introduction




                            ---------------------









GameBoy  Advance  ROM  Manipulator (GBARM in short) is a simple, small tool to




manipulate  the  GameBoy  Advance  ROM  files, mostly the header informations.




Before it was called GameBoy Advance ROM Header Fixer (GBAFix), but due to the




reason  there  was  a tool under this name I renamed it to GameBoy Advance ROM




Manipulator  (GBARM) now. I hope it won't conflict with other GBA related tool




names.









This  tool  is  mostly useful for GameBoy Advance programmers, ROM hackers and




similiar  people,  if you aren't one, this tool is absolutely useless for you.




Special  note  to  AOL  kids:  NO, this won't let you play any pirated Pokemon




games, nor the GameBoy/GameBoy Color, neither the GameBoy Advance ones. :)))









Until  I released the first, beta version of this tool under a different name,




there  wasn't  any  serious  tool to fix the checksum, add the needed Nintendo




logo  (what  isn't  stored  inside  this  tool, but calculated) and manipulate




several  infos  in the GBA ROM headers, that was the reason originally I wrote




this.  Of  course  programmers  can easily add all the needed infos into their




sources  (what will be the header of their GBA ROM after compiling) out of the




checksum,  also  even  everybody can manipulate all these with a hex editor in




the  compiled  ROMs  out  of the checksum. The checksum must be calculated and




that's  really  hard to do manually, so the most important and most basic task




of  this tool was to calculate and store the checksum into the ROM header. And




then  I thought I'll throw a few more functions into this tool, make the whole




header  correct,  change  more  easily  everything  in  the  ROM  header  from




commandline  (so  everybody  can automatize it in a makefile or similiar too),




view  and verify the header infos, pad the ROM size to a valid size, etc. It's




a small, but complete and useful tool for these purposes.









It was tested more or less, if you happen to find some bugs, report them to me




at (credo@resource.cx). You can always find the latest versions on my personal




site (http://credo.resource.cx/), keep an eye on it.









                                #003 - History




                               ----------------









02-07-2001 - I renamed the name of the tool to GameBoy Advance ROM Manipulator




due to name conflicts with already released tools. Also removed the 16 bit CRC




what  is  not  needed,  was just an old, early design plan of Nintendo and was




never  used, so could be only confusing (I'm fixing these to the required $00,




$00  now).  I also added the -i switch to get detailed ROM header info, the -d




switch  to  change  the  device  type and the -n switch to change the mask ROM




version number. I also completely rewrote the documentations from scratch.









13-04-2001  -  The  original  0.1 beta version came out under the name GameBoy




Advance ROM Header Fixer or in short GBAFix.









                              #004 - How To Use




                             -------------------









GBARM  is  a  PC program running under MS-DOS, Windows 95, Windows 98, Windows




98SE,  Windows  Millennium  and  all  the  compatible  operation  systems  and




emulators.  It's  a commandline tool, was compiled with a DOS targeted GCC, so




probably  easily  portable, but I rarely compile to other targets and give out




sources,  sorry.  It  is  supporting  long  filenames too of course, but don't




forget to put the filenames and other infos between "" or '' if they are using




spaces.









As  it  is  a commandline tool, you have to add parameters after the filename,




like  "GBARM  -v  gbarom.gba".  The order of the parameters doesn't count, you




can  mix them up and can use the filename anywhere too. The execution order is




always  fixed  too, checksums are calculated at the final step, so if the file




was  padded or header bytes were changed, that won't corrupt the checksums due




to  the  fixed  order. Parameters can start with the "-" or "/" sign, the sign




must  be followed with the command immediately (capital or lower case letters,




all  are  interpreted)  and that must be followed with the other parameters if




the  command  needs more. At least two parameters are needed, a filename and a




command, in other cases the help screen will pop up.









Most  of the parameters are either ASCII strings or hexadecimal numbers. Don't




use  prefixes  and  postfixes and don't use decimal or other format instead of




these.  Put  the strings too between "" or '' signs in the case they are using




spaces.









                       #005 - GBA ROM Header Structure




                      ---------------------------------









In this section you can learn the GBA ROM header structure, I haven't seen too




many  infos  about  it, so it even can be useful without this tool too, if you




want  to  change  these  manually in your source or in a ROM with a hexeditor.




Learning  this  can be useful to understand the switches of this tool too, but




not absolutely needed of course.









Offset 00h-03h - Start  Address - A 32 bit ARM B command with jump destination




                 to  the  start  address of the program, cannot be manipulated




                 with this tool, there's no reason.









Offset 04h-9fh - Nintendo logo character data - The fix Nintendo logo graphics




                 needed  to  start a ROM on the real machine as it is verified




                 by it.









Offset a0h-abh - Game  title  -  The game title is an ASCII string, officially




                 can  use only ASCII characters between the ASCII code 20h and




                 60h.  Although it is not a strict rule for hobby programmers,




                 it  is  fun  to  follow such a rules in my opinion. As I know




                 developers  can  choose  their own game title here describing




                 the product in short.









Offset ach-afh - Game  code  -  The  4 bytes long code of the game is an ASCII




                 string  too, officially can use only ASCII characters between




                 the ASCII code 20h and 60h. The first letter is always A as I




                 know,  probably  stands  for GBA, so it won't change unless a




                 higher   hardware   with  backwards  compatibility  won't  be




                 introduced  and  this letter could hold some more infos about




                 it. The second and third letters are the shortened version of




                 the  name of the game. And the fourth letter is the territory




                 code. Don't afraid, there's no territory lockout, this is for




                 information  purposes  only.  So  far  as I know J stands for




                 Japan  and  Asia,  E  stands  for  USA and the whole American




                 continent  and  P  stands  for  Europe,  Australia and Africa




                 (probably  came  from  that  these are the PAL video standard




                 territories,  but  I  could  be  wrong). Although it is not a




                 strict rule for hobby programmers, it is fun to follow such a




                 rules  in my opinion. Developers get this 4 letter code right




                 from Nintendo and they have to use that.









Offset b0h-b1h - Maker  code  - The 2 bytes long code of the developer company




                 is  an  ASCII  string  too,  officially  can  use  only ASCII




                 characters between the ASCII code 20h and 60h. Although it is




                 not  a strict rule for hobby programmers, it is fun to follow




                 such a rules in my opinion. Developers get this 2 letter code




                 right from Nintendo and they have to use that.









Offset b2h-b2h - 96h - Fixed 96h byte without any useful information.









Offset b3h-b3h - Main  unit  code  -  This hexadecimal byte is the destination




                 hardware  code.  It  is always 00h at the moment as it stands




                 for  GameBoy Advance, so it won't change in the future either




                 unless  a  higher hardware with backwards compatibility won't




                 be  introduced and this byte could hold some more infos about




                 it.  There's  no  reason  to  change  this or write something




                 different than 00h into it.









Offset b4h-b4h - Device type -  This hexadecimal byte is the device type code.




                 It  is always 00h as the only other possible value stands for




                 a  debugger  cart  what  I  assume  won't be available on the




                 streets  and  I  assume even if a developer works with such a




                 hardware, he or she doesn't have to change this byte, however




                 he  or  she  easily  can  of  course. So there's no reason to




                 change this or write something different than 00h into it.









Offset b5h-bbh - Reserved  area  -  Fixed,  00h filled area without any useful




                 information.









Offset bch-bch - Mask  ROM  version  number  - This hexadecimal byte holds the




                 version  number  of  the ROM. As I know it works somehow that




                 way,  the  first  published  (and released on the streets) is




                 always  the first version and for that 00h is stored here. In




                 the  case it is getting updated, so in the same territory the




                 very  same  game with the very same title is getting replaced




                 with a new version, what is happening rarely, the number here




                 is  getting  increased by one. So usually this byte holds 00h




                 and  there  isn't too much reason to write something here and




                 something else than 00h.









Offset bdh-bdh - Complement   check   -  This  hexadecimal  byte  have  to  be




                 calculated  automatically,  when  the  whole header is in its




                 final  state,  so nothing will change inside of it. (Manually




                 it  would be hard to calculate.) Add the bytes between offset




                 a0h  and bch together, take the number's two's complement and




                 add  19h  to  the  result.  Store  the lowest 8 bits here. Or




                 calculate   automatically   with   GBARM.   The  hardware  is




                 verifying  this  byte  just  like the Nintendo logo character




                 data  and  in the case it isn't correct, the game won't start




                 on the real machine.









Offset beh-bfh - Reserved  area  -  Fixed,  00h filled area without any useful




                 information.









                            #006 - GBARM Commands




                           -----------------------









-h - Get  the  help  screen with a short description about every command and a




     few  examples.  You  also  get  this  when  you start the program without




     parameters  or  with  only  one  parameter  (as  it  needs  at  least two




     parameters, a filename and a command).




     Example: "GBARM -h"









-i - Get  info  about  a  GBA  ROM. This will report whether the ROM header is




     correct,  also  will show the ROM title, game code, maker code, main unit




     code,  device  type,  mask  ROM version number and complement check. Also




     will report whether the complement check is correct.




     Example: "GBARM -i gbarom.gba"









-v - Validate  header  command. This will validate the header of the given ROM




     file.  This  includes  writing out all the fixed values (96h byte, zeroes




     and  Nintendo logo, what is generated by GBARM, but not stored in it) and




     calculating  and  storing  the header complement checksum. So this is the




     most  important  command, probably you won't need the other ones what are




     just extras.




     Example: "GBARM -v gbarom.gba"









-p - Pad  ROM image command. Currently the published ROMs are 4 or 8 megabytes




     large,  maybe  there  will be some 16 or even 32 megabytes large gigantic




     games  in  the  future too. So ROM image sizes are always a power of two,




     just  as it was the case in the GB/GBC games. It can be useful to pad the




     ROM  image.  When  this  command is given alone, it is always padding the




     given  ROM  image  to  the  next  fixed power of two size, for example an




     1,334,123  bytes  long  file  will  be  2,097,152  bytes  long (exactly 2




     megabytes  long),  etc. Nothing will happen if the filesize is already an




     exact  power  of  two.  And  even  a  hexadecimal  number can follow this




     command,  in that case the ROM image will be padded to that exact size in




     the  case  it is larger than the current size. So this way even a 1k long




     file can be padded to 4 megabyte.




     Examples: "GBARM -p gbarom.gba", "GBARM -p800000 gbarom.gba"









-f - Change  the pad filler byte command. With the pad command (unless it does




     nothing)  additional,  useless,  filler  bytes  will  be added to the ROM




     image.  With  this  command  it is possible to control what bytes will be




     used  by  the  pad  command. By default it is hexadecimal ffh, that's the




     most  optimal  in the case of flash ROMs, it can be stored faster. But if




     you  use the pad command, you can add this command too to the commandline




     immediately  followed  by  a  two  digit  hexadecimal  number and the pad




     command will use this instead the default one.




     Example: "GBARM -p -f5a gbarom.gba"









-t - Change the game title command. The game title ASCII string have to follow




     immediately  this  command  and in the case it contains spaces, the title




     have  to  be between "" or ''. The string can be maximum 12 letters long,




     more  will  be  cropped down, less will be filled up with zeroes. See the




     other rules in the previous chapter.




     Examples: "GBAFIX -tHI gbarom.gba", "GBAFIX -t'HELLO WORLD' gbarom.gba"









-c - Change  the  game code command. The game code ASCII string have to follow




     immediately  this  command  and  in the case it contains spaces, the code




     have  to  be  between "" or ''. The string can be maximum 4 letters long,




     more  will  be  cropped down, less will be filled up with zeroes. See the




     other rules in the previous chapter.




     Example: "GBAFIX -cAGRP gbarom.gba"









-m - Change the maker code command. The maker code ASCII string have to follow




     immediately  this  command  and  in the case it contains spaces, the code




     have  to  be  between "" or ''. The string can be maximum 2 letters long,




     more  will  be  cropped down, less will be filled up with zeroes. See the




     other rules in the previous chapter.




     Example: "GBAFIX -mYO gbarom.gba"









-u - Change the main unit code command. As you can see in the previous chapter




     there's  no  reason  to  change  it,  anyway  it can be changed with this




     command  immediately  followed by a two digit hexadecimal number. See the




     infos about this byte in the previous chapter.




     Example: "GBAFIX -u6b gbarom.gba"









-d - Change  the  device  type command. As you can see in the previous chapter




     there's  no  reason  to  change  it,  anyway  it can be changed with this




     command  immediately  followed by a two digit hexadecimal number. See the




     infos about this byte in the previous chapter.




     Example: "GBAFIX -d5c gbarom.gba"









-n - Change  the  mask  ROM  version  number  command.  As  you can see in the




     previous  chapter  there's no reason to change it often, anyway it can be




     changed with this command immediately followed by a two digit hexadecimal




     number. See the infos about this byte in the previous chapter.




     Example: "GBAFIX -n01 gbarom.gba"









                            #007 - Copyright Notes




                           ------------------------









This  tool  is  free,  can  be  used  and spreaded freely in its original form




without  modifications.  However  it  is not public domain and not opensource,




all rights are reserved by the author. No one shall modify or charge money for




this  tool and package. If you use this tool and like it, feel free to send me




greetings in your games and productions, hehe.









                                           CREDO/SCS*TRC^RESOURCE - 02-07-2001