devkitSMS Programming Setup II

In 2017, we checked out devkitSMS Programming Setup to build 8-bit video games in C for the Sega Master System (SMS). Here we use SDCC v3.6.9 which allows maximum 32KB for your main ROM game code size.

Now, the latest devkitSMS requires SDCC 4.x which supports banked code which means it is now possible to page code out transparently. Plus we'd also like to build SMS projects cross platform for Windows and Linux.


Let’s check it out!

devkitSMS
The devkitSMS is a collection of tools and code built specifically for the Sega Master System but also supports homebrew development using C language for SG-1000, SC-3000 and the Sega Game Gear.

Software
Follow all instructions from the previous post: this documents how to setup the pre-requisite software.

Here is a summary of all required software to be installed:

Name  Version  C IDE Editor  Visual Studio 2015  C IDE Editor  Visual Studio Code  Cross compiler  Small Device C Compiler

Name  Version  Make files  Cygwin  Emulators  Emulicious, Fusion, Meka  Debugger  Emulicious Debugger

Note: Emulicioushas dependency on Java therefore launch using java -jar ~/Sega/Emulicious/Emulicious.jar

Windows
Download and install sdcc-4.1.0-x64-setup.exe to C:\Program Files\SDCC. Choose all features to install.


There should be no extra configuration except add C:\Program Files\SDCC\bin to the Environment PATH.


Start | Run | cmd. Type sdcc --version. The following info should display to confirm SDCC version 4.1.0:


Linux
Download and extract sdcc-4.1.0-amd64-unknown-linux2.5.tar.bz2 to ~/sdcc. This should install all features.


There should be no extra configuration except add $HOME/sdcc/bin to the ~/.bashrc file so always available.

gedit ~/.bashrc  export PATH="$PATH:$HOME/sdcc/bin"

Launch Terminal. Type sdcc --version [sdcc -v]. The following should display to confirm SDCC version 4.1.0:


Directories

Windows	C:\Program Files\SDCC\bin
Linux	~/sdcc/bin

devkitSMS
Navigate to the devkitSMS repository on github. @sverx has full instructions here and advises to copy the following 4x executables into SDCC bin folder: assets2banks.exe, folder2c.exe, ihx2sms.exe, makesms.exe.

# Clone devkitSMS
git clone https://github.com/sverx/devkitSMS.git

# Copy 4x files
cd devkitSMS
copy assets2banks/%PLATFORM%/assets2banks %INSTALLATION%/SDCC/bin
copy folder2c/%PLATFORM%/folder2c.exe %INSTALLATION%/SDCC/bin
copy ihx2sms/%PLATFORM%/ihx2sms.exe %INSTALLATION%/SDCC/bin
copy makesms/%PLATFORM%/makesms.exe %INSTALLATION%/SDCC/bin

Note: my preference is to usually copy the relevant files up-to-date as each Master System project is built.

Example
As an example, replicate the simple program from 2017 that sets the border colors of the screen using devkitSMS but this time we will port the Windows build cross platform to Linux and include debugging!

Create new directory HelloWorld: ~/HelloWorld. Copy these files across crt0_sms.rel, SMSlib.h, SMSlib.lib. Launch Visual Studio Code. Open HelloWorld directory. Create new file main.c and enter the following code:

main.c

#include "SMSlib.h"
void main ( void )
{
  SMS_setSpritePaletteColor( 0, RGB( 3, 3, 3 ) );
  SMS_displayOn();
  for ( ;; )
  {
    SMS_waitForVBlank();
  }
}

SMS_EMBED_SEGA_ROM_HEADER(9999, 0);
SMS_EMBED_SDSC_HEADER(1, 0, 2017, 9, 15, "StevePro Studios", "Hello World", "Simple Sega Master System demo to run on real hardware!");

Build
Manually compile, link and execute the Hello program. Launch command prompt: Start | Run | cmd.


Change directory cd ~/HelloWorld. Next, execute following 3x commands (in bold) but add debug keyword:

ACTION	COMMAND	OUTPUT
Compile	sdcc --debug -c -mz80 main.c	main.rel
Link	sdcc --debug -o output.ihx -mz80 --data-loc 0xC000 --no-std-crt0 crt0_sms.rel  main.rel SMSlib.lib	output.ihx
Exceute	ihx2sms output.ihx output.sms	output.sms

Finally, type java -jar ~/Sega/Emulicious/Emulicious.jar output.sms to launch the Hello program.
Congratulations! You have just written your first SMS program using devkitSMS.


Automate
Let's automate the build process: create build script file that contains the previous commands. On Windows name the file build.bat. On Linux name the file build.sh and add EXE permissions as chmod +x build.sh.

@echo off
sdcc --debug -c -mz80 main.c
sdcc --debug -o output.ihx -mz80 --data-loc 0xC000 --no-std-crt0 crt0_sms.rel main.rel SMSlib.lib
ihx2sms output.ihx output.sms
java -jar ~/Sega/Emulicious/Emulicious.jar output.sms

Visual Studio Code
Finally, add hidden .vscode folder in Visual Studio Code + include tasks.json and launch.json files beneath:

tasks.json

{
    "version": "2.0.0",
    "label": "build",
    "type": "shell",
    "linux": {
        "command": "./build.sh"
    },
    "windows": {
        "command": "./build.bat"
      },
    "presentation": {"echo": true, "reveal": "always", "focus": false, "panel": "shared", "showReuseMessage": false, "clear": true},
    "group": {"kind": "build", "isDefault": true},
}

Important: On Windows prefer the ./build syntax as Linux otherwise an "unrecognized cmdlet" may result.

launch.json

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "emulicious-debugger",
            "request": "launch",
            "name": "Launch in Emulicious",
            "program": "${workspaceFolder}/output.sms",
            "port": 58870,
            "stopOnEntry": true
        }
    ]
}

On Linux, launch Emulicious as above. Press Ctrl + Shift + B to build code and F5 to debug step thru code:


Visual Studio 2015
For completeness, if the main workstation is Windows then another option is Visual Studio 2015 can also be used to debug step thru the ANSI-C source code. For more background info see this. Here is the alternative:

main.c

#include "main.h"
void main( void )
{
  devkit_SMS_init();
  devkit_SMS_setSpritePaletteColor( 0, devkit_RGB( 3, 3, 3 ) );
  devkit_SMS_displayOn();
  for( ;; )
  {
    devkit_SMS_waitForVBlank();
  }
}

Summary
To summarize, the Sega Master System development process has been very consistent after the SDCC 4.x upgrade plus the ability to support banked code means initial 32KB ROM restriction now no longer applies!
This will be the topic of the next post.