Setting up the MSX-C environment (part 1)

Note: this article was published originally as the 5th chapter in my Relearning MSX series. Cover photo by Markus Vordermeier. Used under permission.

(This is a long post. If you're reading it from the blog's list of posts then be sure click the "Read more" button to read the whole text.)

It's about time we start doing real work. This is what we will do next:

  1. Set up the emulator (openMSX) that we will use for development
  2. Set up the storage device (hard drive)
  3. Download and install MSX-DOS2, MSX-DOS2 TOOLS, MSX-C v1.2 and MSX-C Library
  4. Create a few batch files to set up the environment at boot and compile C programs
  5. Compile a simple test program in C

 

I won't go deep into technical details or long explanations for now. I'll assume that you're new to MSX computers and aren't familiar with the equipment nor the software.

Also, if you have a real MSX2 (or higher) with a hard drive then feel free to use it instead of the emulator. However, unless you have an MSX turbo R then it's still a good idea to work in the emulator, to speed up compile times.

Please post a comment below if at any time you have questions, or there's something that I didn't explain clearly enough.

Without further ado...


Setting up an MSX emulator

An emulator is a program that simulates a computer inside another computer. Its purpose is to run software that was written for a different computer platform. In this case, we will use an emulator to run MSX software on a Mac or a Windows PC.

We will use openMSX just because it's my favorite, but feel free to use a different emulator if you prefer. openMSX is available for OS X, Windows, Android, and can be easily compiled on Linux. Go to their homepage (http://openmsx.sourceforge.net), download the package appropriate for your computer, and install it.

If you try and run openMSX now as it is you'll see the splash screen below, followed by an error message:

openMSX_cbios_boot

C-BIOS splash screen under openMSX

openMSX_cbios_message

C-BIOS message under openMSX

What you're seeing is C-BIOS, which wasn't part of any MSX computer. The reason why you're seeing this screen is that the emulator software only simulates the electronic parts (hardware) that compose the computer. However, every computer also requires some software to be able to start up and run programs. In the case of the MSX, that software is inside a memory (ROM), and in many cases it can't be distributed with the emulator because the copyright still belongs to ASCII or Microsoft.

C-BIOS was written from scratch by MSX users as a partial solution to this problem. It allows emulator developers to distribute a minimal base software on which to run cartridge software. It is freely distributable, and openMSX is one of the emulators that include it by default.

We won't be using it C-BIOS because we wouldn't be able to boot to the operating system and develop software. Instead, we'll set up openMSX to run as a Panasonic FS-A1GT, the last MSX computer built.

Panasonic FS-A1GT. Photo from msx.org.

This computer came with MSX-DOS2 embedded, so we won't need to add it as an extension to the emulator.

To speed up MSX-C compile times we will also add a hard drive to the emulated computer. We will use the Sunrise ATA-IDE interface. This wasn't an official peripheral, but it was a very professionally-built device. It came with a 40-pin parallel ATA connector on the top side of the case were you could attach any standard PC hard drive. There was also a later version that used Compact Flash cards instead of a hard drive, but is otherwise equivalent.

We will set up openMSX to emulate a 128 MB hard drive attached to the emulated MSX.

Sunrise ATA-IDE cartridge. Photo from msx.org.

Run openMSX now if you haven't done so yet, then quit the emulator when you see the C-BIOS error message. This will create the openMSX folder structure under your home directory.


Download the ROMs

First, download the following files from msxarchive.nl:


Put these three files in the systemroms folder of your openMSX directory. The default location is:

  • OS X: ~/.openMSX/share/systemroms
  • Windows: C:\Users\your_user_name\My Documents\openMSX\share\systemroms


Next, we'll confirm that the emulator runs properly as a Panasonic FS-A1GT with the ATA-IDE extension.

If you're on a Mac: open the Terminal application (it's under Applications > Utilities), and run this command (this assumes that you put openMSX under /Applications):

/Applications/openMSX.app/Contents/MacOS/openmsx -machine Panasonic_FS-A1GT -ext ide

If you're on Windows: right-click the openMSX icon on the Start menu, then click Properties. Go to the Shortcut tab and add the following parameters at the end of the Target field:

-machine Panasonic_FS-A1GT -ext ide

openmsx_shortcut_windows

openMSX shortcut properties on Windows, after adding the machine and extension parameters.

After editing the shortcut, click OK and then click the openMSX icon in the Start menu.

If you installed the ROMs correctly then you should see the Panasonic FS-A1GT boot screen inside the openMSX window:

openMSX_Panasonic_FS-A1GT_BASIC

Panasonic FS-A1GT booted to MSX BASIC under openMSX

If this is what you see then before going on enter the following MSX BASIC commands one by one, and press ENTER after each one:

SCREEN 0
WIDTH 80
SET SCREEN

The first one changes the screen to a text-only mode that supports up to 80 columns of text. The second command changes the screen to 80 columns of text per row, and the last one saves these settings in the computer's non-volatile memory, so the next time the MSX restarts it will go directly to the 80-column text mode.

If you reset the MSX now you should see something like this:

openMSX_Panasonic_FS-A1GT_BASIC:SCREEN_0

Panasonic FS-A1GT booted to MSX BASIC in SCREEN 0

At this point the MSX screen may be too small to comfortably read text on your computer screen. If that's the case then go into the openMSX menu (press CMD+O on a Mac, or the Menu key on Windows), then go into Video Settings and increase the value of Scale Factor until the text size is big enough to be comfortable to read.

Set up the storage

Next we'll create a 128 MB virtual hard drive to store development files (and any other files you want to store in your emulated MSX). This disk will be split in four 32 MB partitions because of limitations in MSX-DOS2 that I won't discuss now.

Start openMSX (if it isn't running already) and open the openMSX console (CMD+L on a Mac, F10 on Windows), and enter the following commands one by one:

set power off
diskmanipulator create MSXC12HD.dsk 32m 32m 32m 32m
hda MSXC12HD.dsk
set power on
set save_settings_on_exit on

These commands will power off the emulated MSX, create a 128 MB disk with four 32 MB partitions (this command will take a while to complete), attach the new disk image to the virtual MSX, turn it on, and ensure that settings will remain saved after the emulator is restarted.

At this point we're emulating the following computer setup: a Panasonic FS-A1GT with an ATA-IDE interface to which there's a 128 MB generic hard drive connected.

Emulated_Panasonic_FS-A1GT_layout

We need to make sure that the emulator will always use the MSXC12HD.dsk hard drive image that we created. To do this we modify the command line to launch openMSX:

  • On a Mac, add -hda MSXC12HD.dsk to the command line
  • On Windows, edit the openMSX shortcut again and add -hda MSXC12HD.dsk to the end of the shortcut's Target field


In the following posts we'll install MSX-DOS2 in the hard drive, then MSX-DOS2 TOOLS, plus a couple other utilities that will be useful in the future. After that, we'll set up MSX-C v1.2 and compile a short program.

Comments

Thank you for the post.

What kind of projects do you develope in C? Which libraries are there available?

I would be interested in developing a game in C but I haven't heard anyone using C for this...

We are developing a game engine in C, so it's possible to make games. In fact, I see that compiled languages as Pascal or C are more flexible to make games that ASM or Basic since you have a very powerful language.

http://www.msxblog.es/giles-odyssey-juego-para-msx2-en-desarrollo/

Sorry for the Spanish, game under development in C. With official msx libs from ASCII, you already have a big work done.





Personally, so far I've only used it for small tools. However, as AxelStone said, it's perfectly possible to use it to code games.

Regarding the libraries, the default library that comes with MSX-C supports most of the standard functionality you'd expect from a normal C compiler: string manipulation, file operations (including MSX-DOS2 path/directory support), input/output, and BIOS or inter-slot calls.

Besides the default library, there's an optional disk called MSX-C Library that includes extra functionality in several groups of library functions:

Graphics

  • Access to VDP registers and VRAM
  • Sprites
  • Screen modes / interlace
  • Drawing operations: pset, paint, line, circle, box
  • Copy / move bitmaps
  • Print text in bitmap modes

Mathematical functions

  • Support for 32-bit and 64-bit floats and integers
  • 32-bit and 64-bit arithmetic and type conversion
  • 32-bit and 64-bit bitwise and logical operations
  • Trigonometric functions
  • MATH-PACK support

Others

  • Interrupt support
  • Extended BIIOS/BDOS and inter-slot calls
  • PSG support
  • Keyboard matrix
  • Printer
  • Cursor / joystick / mouse and trigger support
  • MSX-CURSES terminal library

Besides, there's a lot of extra code released in MSX Magazine to support MSX-MUSIC, MIDI, etc...

I agree, ASCII's MSX-C with full libraries, is a great tool, even for games. For game developement, you need to make sure you also understand all the options in the individual programs (linker, assembler etc) to make sure you are not getting stuck with a symbol table which is too small for instance or to how to link c files in the right order to compile it correctly to one program file etc etc.

Great programming toolset, keep in mind it uses an old fashioned syntax (K&R) and differs slightly from ANSI C.

I did try to create a Shoot 'm up game, from which the basics did work, player controls, shooting, enemies, score count, but wanted to try and create it in assembly, so I learn assembly (I can compare then the projects as well).

Looking forward to the next chapter Javi ;)

Nice article, looking forward for the next chapter. As I will be using my real MSX to learn MSX-C :-)

It's nice to see people interested in MSX-C. From my point of view, compiled languages are the big forgotten languages in MSX and they have a great potential. They are very prowerful, supports complex types, function oriented, dynamic memory allocation and has something that is not present in ASM / Basic: they are really reusable. A library made in MSX-C is totally reusable in any other game, no need to rewrite anything.

Let's hope to see a growing MSX-C comunity and share knowledge :-).


It looks very interesting. I will look forward for next posts related to MSX-C.

My actual project is in Assembler but it is a personal challenge.

Thank you very much.

openMSX has a default machine setting which is usually set to one of the C-BIOS configurations, but allows a different machine as well. You put the machine in your shortcut definition, which works fine of course, though you can also change the default machine to boot with using (in case of your example): set default_machine Panasonic_FS-A1GT, followed by a save_settings,so you can keep the command line shorter since you can l leave out the -machine part on the command line.

Post a comment

You need to sign in in order to comment.