Difference between revisions of "Hello world tutorial"

From NeoGeo Development Wiki
Jump to: navigation, search
m (BIOS -> system ROM)
m (Minor English and wording fixes)
Line 1: Line 1:
This tutorial will guide you through all the necessary steps to make a NeoGeo binary which displays the text "Hello world !". The language we will be using is 68k asm, but good knowledge of it is not needed.
+
This tutorial will guide you through all the necessary steps to make a NeoGeo binary which displays the text "Hello world !".
  
=Setting up a minimalist development environment=
+
The language we will be using is [[68k]] assembly, but good knowledge of it is not needed.
  
*Download the latest MAME emulator binaries from [[http://mamedev.org/release.html this page]]. Extract the zip contents to a folder such as "C:/mame/".
+
=Setting up a minimal development environment=
*To run NeoGeo software with MAME, you will need the dumps of the various ROMs which are part of the system. You can find them as a pack called neogeo.zip (various forms, more or less complete). The files needed will be '''000-lo.lo''' (64KiB, the [[LO ROM]]), '''sm1.sm1''' (128KiB, the [[M1 ROM]] for sound), '''sp-s2.sp1''' (128KiB, the [[System ROM]]) and '''sfix.sfix''' (128KiB, the [[SFIX]] ROM). They will have to be copied to the "c:/mame/roms/neogeo/" folder for them to be recognized by MAME.
+
 
*Use google again to find and download a [[Super Sidekicks]] romset (ssideki.zip), extract it to "c:/mame/roms/ssideki/". Make sure that the following files are present:
+
* Download the latest [[emulators|MAME]] binaries from [[http://mamedev.org/release.html this page]]. Extract the zip contents to a folder such as "C:/MAME/".
**052-c1.c1 and 052-c2.c2 ([[C ROM]] pair, sprite graphics)
+
* To run NeoGeo software with MAME, you will need the dumps of the various ROMs which are part of the system. You can find them as a pack called neogeo.zip (various forms, more or less complete). The files needed are '''000-lo.lo''' (64KiB, the [[LO ROM]]), '''sm1.sm1''' (128KiB, the [[M1 ROM]] for sound), '''sp-s2.sp1''' (128KiB, the [[System ROM]]) and '''sfix.sfix''' (128KiB, the [[SFIX]] ROM). They will have to be copied to the "c:/MAME/roms/neogeo/" folder for them to be recognized by MAME. These ROMs are copyrighted, so you won't find them here.
**052-m1.m1 (Z80 code, we won't mess with that)
+
* Use Google again to find and download a [[Super Sidekicks]] romset (ssideki.zip), extract it to "c:/MAME/roms/ssideki/". Make sure that the following files are present:
**052-p1.p1 (68k code, that's what we'll make)
+
** 052-c1.c1 and 052-c2.c2 ([[C ROM]] pair, sprite graphics)
**052-s1.s1 ([[S ROM]]: fix graphics)
+
** 052-m1.m1 (Z80 code, we won't mess with that)
**052-v1.v1 ([[V ROM]]: sound)
+
** 052-p1.p1 (68k code, that's what we'll replace)
If they are named incorrectly (.bin), rename them as MAME wants the files to be named exactly that way.
+
** 052-s1.s1 ([[S ROM]]: fix graphics, we'll use it)
*You will need a batch file to start MAME with the right parameters. Create a new text file and add these lines:
+
** 052-v1.v1 ([[V ROM]]: sound, won't touch that either)
 +
* You will need a batch file to start MAME easily with the right parameters. Create a new text file and add these lines:
  
 
<pre>
 
<pre>
mame ssideki -debug -nofilter -video d3d -waitvsync -window
+
mame -debug -nofilter -waitvsync -window ssideki
 
pause
 
pause
 
</pre>
 
</pre>
  
Run this batch file, MAME should open the emulation window and its debugger. Don't be scared, just highlight the debugger window and press F5 to see if Super Sidekicks starts. If the romset is bad, the missing and/or invalid files will be shown in the DOS prompt (bad checksum, missing files...). When everything works, close the debugger and the emulation window.
+
Save it with the .bat extension and run it. MAME should open the emulation window and its debugger. Don't be scared, just highlight the debugger window and press F5 to see if Super Sidekicks starts. If the romset is bad, the missing and/or invalid files will be shown in the DOS prompt (bad checksum, missing files...). When everything works, close the debugger and the emulation window.
  
*Download [[http://john.ccac.rwth-aachen.de:8000/ftp/as/precompiled/i386-unknown-win32/aswcurr.zip the macro assembler AS (ASW)]] and [[Flip_pad.zip|this zip file]]. There is no installation required, just extract those files to a folder like "C:/neogeo/asw/".
+
* Download [[http://john.ccac.rwth-aachen.de:8000/ftp/as/precompiled/i386-unknown-win32/aswcurr.zip the macro assembler AS (ASW)]] and [[Flip_pad.zip|this zip file]]. There is no installation required, just extract those files to a folder like "C:/neogeo/asw/".
*For the purpose of this tutorial, notepad can be used as a code editor. Make a folder for this project such as "c:/neogeo/helloworld/".
+
* For the purpose of this tutorial, Notepad can be used as a code editor. Make a folder for this project such as "c:/neogeo/helloworld/".
*You will need to add a batch file in this folder to run ASW to assemble your source file. Make a new text file with the following contents:
+
* You will need to add a batch file in this folder to make ASW assemble your source file. Create a new text file with the following contents:
  
 
<pre>
 
<pre>
Line 36: Line 37:
 
And save it as "make.bat" in the "c:/neogeo/helloworld/" folder.
 
And save it as "make.bat" in the "c:/neogeo/helloworld/" folder.
  
'''Asw''' assembles your code, '''p2bin''' makes the [[P ROM]] with the right size (128KiB), '''flip.exe''' inverts bytes by pairs (byteswapping) because P ROMs have to be that way, '''pad.exe''' fills up the P ROM with $FF bytes up to 512KiB (to match the original ssideki ROM size) and then copied in place of the original Super Sidekicks rom.
+
'''ASW''' assembles your code, '''p2bin''' makes the [[P ROM]] with the right size (128KiB), '''flip.exe''' inverts bytes by pairs (byteswapping) because P ROMs have to be that way, '''pad.exe''' fills up the P ROM with "$FF" (255) bytes up to 512KiB to match the original ssideki P ROM size and make MAME happy, and it's finally copied in place of the original Super Sidekicks P ROM.
  
 
Be aware that only the P ROM is replaced, all graphics, musics and sounds are still the Super Sidekicks ones.
 
Be aware that only the P ROM is replaced, all graphics, musics and sounds are still the Super Sidekicks ones.
Line 44: Line 45:
 
=The code=
 
=The code=
  
*Go to the [[68k ASM defines]] page, copy everything, paste it in a new text file and save it as "regdefs.asm" in "c:/neogeo/helloworld/". This allows you to use register names in place of their pretty meaningless and hard-to-remember addresses. For example, instead of writing '''$300001''' in your code, you'll be able to write {{Reg|REG_DIPSW}} instead and ASW will take care of translating that to $300001.
+
* Go to the [[68k ASM defines]] page, copy everything, paste it in a new text file and save it as "regdefs.asm" in "c:/neogeo/helloworld/". This allows you to use register names in place of their hard-to-remember addresses. For example, instead of writing <pre>$300001</pre> in your code, you'll be able to write <pre>REG_DIPSW</pre> instead and ASW will take care of translating that to $300001.
*Start a new text file and add the following:
+
* Start a new text file and add the following:
 
<pre>
 
<pre>
 
     cpu 68000
 
     cpu 68000
Line 55: Line 56:
 
==A bit of thinking==
 
==A bit of thinking==
  
To display the "Hello world !" text, there are basically two options: using sprites (one sprite for each letter, for example), or using the [[fix layer]]. To avoid having the need to edit the sprite ROMs and create an alphabet, we will use the alphabet that is already stored in the fix ROM (052-s1.bin).
+
To display the "Hello world !" text, there are basically two options: using [[sprites]] (one sprite for each letter, for example), or using the [[fix layer]]. To avoid needing to edit the sprite ROMs and create an alphabet, we will use the alphabet that is already stored in the fix ROM (052-s1.bin).
  
If you look at the contents of a typical S ROM (like on [[SFIX|this page]]), you will see that the first bank ($100) of tiles contains a 8x8 pixels alphabet, which is often customized for the game. The Super Sidekicks one uses color gradients, so we will use the 8x16 pixels alphabet instead, which is simpler (2 colors), and which is found in the next two banks (tiles $100 to $2FF).
+
If you look at the contents of a typical S ROM (like on [[SFIX|this page]]), you will see that the first bank ($100) of tiles contains a 8x8 pixels alphabet, which is often customized for each game. The Super Sidekicks one uses color gradients, so we will use the 8x16 pixels alphabet instead, which is simpler (2 colors), and which is found in the next two banks (tiles $100 to $2FF).
  
 
As shown in the SFIX tileset reference, the bank 1 (tiles $100 to $1FF) contains the upper tiles (the top of the letters), and the bank 2 (tiles $200 to $2FF) contains the lower tiles (the bottom of the letters).
 
As shown in the SFIX tileset reference, the bank 1 (tiles $100 to $1FF) contains the upper tiles (the top of the letters), and the bank 2 (tiles $200 to $2FF) contains the lower tiles (the bottom of the letters).
Line 63: Line 64:
 
By mapping those tiles correctly on the '''fix map''', text can be displayed.
 
By mapping those tiles correctly on the '''fix map''', text can be displayed.
  
Know that there is a special System ROM call ([[MESS_OUT]]) which purpose is to simplify text writing to the fix. For the purpose of this tutorial, we'll do it the hard way, without using the System ROM.
+
Know that there is a special [[system ROM]] call named [[MESS_OUT]], which purpose is to simplify text writing to the fix. For the purpose of this tutorial, we'll do it the hard way, without using the system ROM.
  
 
==Cleaning everything up==
 
==Cleaning everything up==
  
Before writing tile number to the fix map, we need to make sure it's empty.
+
Before writing tile numbers to the fix map, we need to make sure it's empty.
 
For this, we will fill it with the tile $FF (which is filled with color 1).
 
For this, we will fill it with the tile $FF (which is filled with color 1).
 
A loop is used to fill in the 40*32 map:
 
A loop is used to fill in the 40*32 map:
Line 81: Line 82:
  
 
Register D0 is used as the loop counter, which will be decremented each iteration. The count must be 1 less because DBRA branches again when D0=0.
 
Register D0 is used as the loop counter, which will be decremented each iteration. The count must be 1 less because DBRA branches again when D0=0.
Keep in mind that the VRAM is accessed '''only by words''', and that the fix map also holds the '''palette number''' for each tile. So we need to write $00FF (palette 0, tile $20).
+
Keep in mind that the [[VRAM]] is accessed '''only by words''', and that the fix map also holds the '''palette number''' for each tile. So we need to write $00FF (palette 0, tile $0FF).
The byte write to REG_DIPSW kicks the [[watchdog]], this has to be done regularly otherwise the Neogeo '''will reset'''.
+
The byte write to REG_DIPSW kicks the [[watchdog]], this has to be done regularly otherwise the NeoGeo '''will reset'''.
  
Now that the fix is cleared, the palette needs to be set up. We'll use 2 colors of the palette zero.
+
Now that the fix is cleared, the palette needs to be set up. We'll use the first 2 colors of palette 0.
 
The first color is the background, the second is the text.
 
The first color is the background, the second is the text.
  

Revision as of 05:15, 6 April 2016

This tutorial will guide you through all the necessary steps to make a NeoGeo binary which displays the text "Hello world !".

The language we will be using is 68k assembly, but good knowledge of it is not needed.

Setting up a minimal development environment

  • Download the latest MAME binaries from [this page]. Extract the zip contents to a folder such as "C:/MAME/".
  • To run NeoGeo software with MAME, you will need the dumps of the various ROMs which are part of the system. You can find them as a pack called neogeo.zip (various forms, more or less complete). The files needed are 000-lo.lo (64KiB, the LO ROM), sm1.sm1 (128KiB, the M1 ROM for sound), sp-s2.sp1 (128KiB, the System ROM) and sfix.sfix (128KiB, the SFIX ROM). They will have to be copied to the "c:/MAME/roms/neogeo/" folder for them to be recognized by MAME. These ROMs are copyrighted, so you won't find them here.
  • Use Google again to find and download a Super Sidekicks romset (ssideki.zip), extract it to "c:/MAME/roms/ssideki/". Make sure that the following files are present:
    • 052-c1.c1 and 052-c2.c2 (C ROM pair, sprite graphics)
    • 052-m1.m1 (Z80 code, we won't mess with that)
    • 052-p1.p1 (68k code, that's what we'll replace)
    • 052-s1.s1 (S ROM: fix graphics, we'll use it)
    • 052-v1.v1 (V ROM: sound, won't touch that either)
  • You will need a batch file to start MAME easily with the right parameters. Create a new text file and add these lines:
mame -debug -nofilter -waitvsync -window ssideki
pause

Save it with the .bat extension and run it. MAME should open the emulation window and its debugger. Don't be scared, just highlight the debugger window and press F5 to see if Super Sidekicks starts. If the romset is bad, the missing and/or invalid files will be shown in the DOS prompt (bad checksum, missing files...). When everything works, close the debugger and the emulation window.

  • Download [the macro assembler AS (ASW)] and this zip file. There is no installation required, just extract those files to a folder like "C:/neogeo/asw/".
  • For the purpose of this tutorial, Notepad can be used as a code editor. Make a folder for this project such as "c:/neogeo/helloworld/".
  • You will need to add a batch file in this folder to make ASW assemble your source file. Create a new text file with the following contents:
@echo off
c:\neogeo\asw\asw main -L -quiet
c:\neogeo\asw\p2bin main -r $000000-$01FFFF
c:\neogeo\asw\flip main.bin 052-p1.bin
c:\neogeo\asw\pad 052-p1.bin 524288 255
copy 052-p1.bin c:\mame\roms\ssideki\052-p1.bin

And save it as "make.bat" in the "c:/neogeo/helloworld/" folder.

ASW assembles your code, p2bin makes the P ROM with the right size (128KiB), flip.exe inverts bytes by pairs (byteswapping) because P ROMs have to be that way, pad.exe fills up the P ROM with "$FF" (255) bytes up to 512KiB to match the original ssideki P ROM size and make MAME happy, and it's finally copied in place of the original Super Sidekicks P ROM.

Be aware that only the P ROM is replaced, all graphics, musics and sounds are still the Super Sidekicks ones.

Now that you have everything to assemble and run the ROM, you can start coding.

The code

  • Go to the 68k ASM defines page, copy everything, paste it in a new text file and save it as "regdefs.asm" in "c:/neogeo/helloworld/". This allows you to use register names in place of their hard-to-remember addresses. For example, instead of writing
    $300001
    in your code, you'll be able to write
    REG_DIPSW
    instead and ASW will take care of translating that to $300001.
  • Start a new text file and add the following:
    cpu 68000
    supmode on
    INCLUDE "regdefs.asm"

This indicates ASW what CPU we're writing code for (Motorola 68000), that the code will be run in supervisor mode (allows us to use special instructions), and to include our previous "regdefs.asm" file. Save this file as "main.asm".

A bit of thinking

To display the "Hello world !" text, there are basically two options: using sprites (one sprite for each letter, for example), or using the fix layer. To avoid needing to edit the sprite ROMs and create an alphabet, we will use the alphabet that is already stored in the fix ROM (052-s1.bin).

If you look at the contents of a typical S ROM (like on this page), you will see that the first bank ($100) of tiles contains a 8x8 pixels alphabet, which is often customized for each game. The Super Sidekicks one uses color gradients, so we will use the 8x16 pixels alphabet instead, which is simpler (2 colors), and which is found in the next two banks (tiles $100 to $2FF).

As shown in the SFIX tileset reference, the bank 1 (tiles $100 to $1FF) contains the upper tiles (the top of the letters), and the bank 2 (tiles $200 to $2FF) contains the lower tiles (the bottom of the letters).

By mapping those tiles correctly on the fix map, text can be displayed.

Know that there is a special system ROM call named MESS_OUT, which purpose is to simplify text writing to the fix. For the purpose of this tutorial, we'll do it the hard way, without using the system ROM.

Cleaning everything up

Before writing tile numbers to the fix map, we need to make sure it's empty. For this, we will fill it with the tile $FF (which is filled with color 1). A loop is used to fill in the 40*32 map:

move.l   #(40*32)-1,d0
move.w   #FIXMAP,REG_VRAMADDR
.clearfix:
move.w   #$00FF,REG_VRAMRW
move.b   d0,REG_DIPSW
dbra     d0,.clearfix

Register D0 is used as the loop counter, which will be decremented each iteration. The count must be 1 less because DBRA branches again when D0=0. Keep in mind that the VRAM is accessed only by words, and that the fix map also holds the palette number for each tile. So we need to write $00FF (palette 0, tile $0FF). The byte write to REG_DIPSW kicks the watchdog, this has to be done regularly otherwise the NeoGeo will reset.

Now that the fix is cleared, the palette needs to be set up. We'll use the first 2 colors of palette 0. The first color is the background, the second is the text.

move.w   #BLACK,PALETTES
move.w   #WHITE,PALETTES+2

Writing the text

The text can now be mapped to the fix map.

  • To be continued...