Difference between revisions of "Hello world tutorial"

From NeoGeo Development Wiki
Jump to: navigation, search
m
m
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 !".
+
This tutorial will guide you through all the necessary steps to make a NeoGeo romset which displays the text "Hello world !". It is written for Windows but all the necessary tools have equivalents on MacOS and Linux.
  
The language we will be using is [[68k]] assembly, but good knowledge of it is not needed.
+
The programming language used is [[68k]] assembly, but good knowledge of it is not needed as all instructions will be detailed.
  
 
=Setting up a minimal development environment=
 
=Setting up a minimal development environment=
  
* 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/".
+
* Download the latest [[emulators|MAME]] binaries from [[http://mamedev.org/release.html mamedev.org]]. 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.
+
* 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. Like original games 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:
+
* As a base, find and download a [[Super Sidekicks]] romset (ssideki.zip) and extract it to "C:/MAME/roms/ssideki/". Make sure that the following files are present and make sure they are named correctly (MAME is picky about file names and extensions):
 
** 052-c1.c1 and 052-c2.c2 ([[C ROM]] pair, sprite graphics)
 
** 052-c1.c1 and 052-c2.c2 ([[C ROM]] pair, sprite graphics)
 
** 052-m1.m1 (Z80 code, we won't mess with that)
 
** 052-m1.m1 (Z80 code, we won't mess with that)
Line 13: Line 13:
 
** 052-s1.s1 ([[S ROM]]: fix graphics, we'll use it)
 
** 052-s1.s1 ([[S ROM]]: fix graphics, we'll use it)
 
** 052-v1.v1 ([[V ROM]]: sound, won't touch that either)
 
** 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:
+
* Write a short batch file to start MAME easily with the right parameters. Create a new text file and add these lines:
  
 
<pre>
 
<pre>
mame -debug -nofilter -waitvsync -window ssideki
+
mame -debug -nofilter -window ssideki
 
pause
 
pause
 
</pre>
 
</pre>
  
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.
+
Save it with the .bat extension in "C:/MAME/" 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 in the main window. If the romset is bad, the missing and/or invalid files will be shown in the command line prompt (bad checksum, missing files...). When the game runs correctly, 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 make ASW assemble your source file. Create a new text file with the following contents:
+
* Write a batch file in this folder to make ASW assemble your code. Create a new text file with the following contents:
  
 
<pre>
 
<pre>
Line 35: Line 35:
 
</pre>
 
</pre>
  
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" (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.
+
'''ASW''' assembles your code, '''p2bin''' makes the [[P ROM]] with the right size ($1FFFF = 128KiB), '''flip.exe''' flips bytes in 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 file is replaced, all graphics, musics and sounds will still be those from Super Sidekicks.
  
 
Now that you have everything to assemble and run the ROM, you can start coding.
 
Now that you have everything to assemble and run the ROM, you can start coding.
Line 45: 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 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.
+
* 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 addresses (easier to remember). 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:
+
* Create a new text file and add the following lines:
 
<pre>
 
<pre>
 
     cpu 68000
 
     cpu 68000
Line 52: Line 52:
 
     INCLUDE "regdefs.asm"
 
     INCLUDE "regdefs.asm"
 
</pre>
 
</pre>
This indicates ASW what CPU we're writing code for ([[68k|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".
+
These aren't assembly instruction but directives that only ASW will understand. '''cpu 68000''' indicates what CPU we're writing code for ([[68k|Motorola 68000]]), '''supmode on''' indicates that the code will run in '''supervisor''' mode (allows us to use special instructions, the NeoGeo always runs in supervisor mode), and '''INCLUDE''' tells ASW to take a look in our previous "regdefs.asm" file. Save this file as "main.asm" in "c:/neogeo/helloworld/".
 +
 
 +
==Formalities==
 +
 
 +
For the "cartridge" to be recognized by the system ROM and launched, header data must be present. Copy the [[68k_program_header|minimal header]] to a new "header.asm" file.
 +
 
 +
This will also set up the [[68k interrupts|v-blank interrupt]] vector to a label called '''VBLANK'''.
  
 
==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 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).
+
To display the "Hello world !" text, there are basically two methods:
 +
* Use [[sprites]] (one sprite for each letter, for example)
 +
* Use the [[fix layer]] (one tile per letter)
 +
 
 +
To avoid the need to edit the sprite ROMs and draw a font, we will use the one that is already stored in the ssideki's fix ROM (052-s1.bin).
  
If you look at the contents of a typical S ROM (like on [[SFIX_ROM|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).
+
If you look at the contents of a typical S ROM (like on [[SFIX_ROM|this page]]), you will see that the first bank ($100) of tiles contains a 8x8 pixels character set, 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). It is found in the next two tile 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, bank 1 (tiles $100 to $1FF) contains the upper tiles (the top of the letters), and 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.
 
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.
+
Note that there is a [[Category:BIOS_calls|system ROM call]] named [[MESS_OUT]] which purpose is to simplify text writing to the fix layer. For the purpose of this tutorial we'll do it the hard way, without using this call.
  
 
==Cleaning everything up==
 
==Cleaning everything up==
  
Before writing tile numbers to the fix map, we need to make sure it's empty.
+
Before writing tile numbers to the fix map, we want to make sure it's cleared.
For this, we will fill it with the tile $FF (which is filled with color 1).
+
For this, we will fill it with 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 fix map:
  
 
<syntaxhighlight>
 
<syntaxhighlight>

Revision as of 17:07, 13 March 2017

This tutorial will guide you through all the necessary steps to make a NeoGeo romset which displays the text "Hello world !". It is written for Windows but all the necessary tools have equivalents on MacOS and Linux.

The programming language used is 68k assembly, but good knowledge of it is not needed as all instructions will be detailed.

Setting up a minimal development environment

  • Download the latest MAME binaries from [mamedev.org]. 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. Like original games these ROMs are copyrighted, so you won't find them here.
  • As a base, find and download a Super Sidekicks romset (ssideki.zip) and extract it to "C:/MAME/roms/ssideki/". Make sure that the following files are present and make sure they are named correctly (MAME is picky about file names and extensions):
    • 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)
  • Write a short batch file to start MAME easily with the right parameters. Create a new text file and add these lines:
mame -debug -nofilter -window ssideki
pause

Save it with the .bat extension in "C:/MAME/" 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 in the main window. If the romset is bad, the missing and/or invalid files will be shown in the command line prompt (bad checksum, missing files...). When the game runs correctly, 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/".
  • Write a batch file in this folder to make ASW assemble your code. 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 ($1FFFF = 128KiB), flip.exe flips bytes in 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 file is replaced, all graphics, musics and sounds will still be those from Super Sidekicks.

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 addresses (easier to remember). 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.
  • Create a new text file and add the following lines:
    cpu 68000
    supmode on
    INCLUDE "regdefs.asm"

These aren't assembly instruction but directives that only ASW will understand. cpu 68000 indicates what CPU we're writing code for (Motorola 68000), supmode on indicates that the code will run in supervisor mode (allows us to use special instructions, the NeoGeo always runs in supervisor mode), and INCLUDE tells ASW to take a look in our previous "regdefs.asm" file. Save this file as "main.asm" in "c:/neogeo/helloworld/".

Formalities

For the "cartridge" to be recognized by the system ROM and launched, header data must be present. Copy the minimal header to a new "header.asm" file.

This will also set up the v-blank interrupt vector to a label called VBLANK.

A bit of thinking

To display the "Hello world !" text, there are basically two methods:

  • Use sprites (one sprite for each letter, for example)
  • Use the fix layer (one tile per letter)

To avoid the need to edit the sprite ROMs and draw a font, we will use the one that is already stored in the ssideki's 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 character set, 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). It is found in the next two tile banks (tiles $100 to $2FF).

As shown in the SFIX tileset reference, bank 1 (tiles $100 to $1FF) contains the upper tiles (the top of the letters), and 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.

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

Cleaning everything up

Before writing tile numbers to the fix map, we want to make sure it's cleared. For this, we will fill it with tile $FF (which is filled with color 1). A loop is used to fill in the 40*32 fix 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...