Hello world tutorial

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.

Setting up a minimalist development environment

• Download the latest MAME emulator 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 will be 000-lo.lo (64KiB, the LO ROM), sm1.sm1 (128KiB, the M1 ROM for sound), sp-s2.sp1 (128KiB, the BIOS) 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:
  • 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 make)
  • 052-s1.s1 (S ROM: fix graphics)
  • 052-v1.v1 (V ROM: sound)

If they are named incorrectly (.bin), rename them as MAME wants the files to be named exactly that way.

• You will need a batch file to start MAME with the right parameters. Create a new text file and add these lines:

mame ssideki -debug -nofilter -video d3d -waitvsync -window
pause

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.

• 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 run ASW to assemble your source file. Make 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 bytes up to 512KiB (to match the original ssideki ROM size) and then copied in place of the original Super Sidekicks 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 pretty meaningless and 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 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).

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 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).

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 BIOS 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 BIOS.

Cleaning everything up

Before writing tile number 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 $20). 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. 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...