"Hello, World!" Tutorial By Adam Trionfo December 2011 ------------------------ How to get a "Hello World" program running on a Bally Arcade / Astrocade. This article is aimed at those who want to get started programming the Astrocade using an assembler. For those people playing with classic systems, the words "assembler" and "assembly language" are thrown around rather often with little or no explanation of what the words mean. If you're just playing cartridges on your Bally/Astrocade, or loading a few BASIC programs, then there is no reason to understand how the game cartridges work. However, if the idea of what is going on DOES interest you, then this article will benefit you. After you finish reading, you will not only have a better understanding of an assembler, but you will also know how to use one. At its most basic level, an assembler is a programmer's tool that takes a text file filled with assembly mnemonics and programmer comments and turns it into a machine language program. It is a similar concept to a C compiler-- but NOT exactly the same. The binary output of an assembler is EXACTLY the same no matter what assembler is used, but the output of a compiler will vary using different C compilers (but the program should still run the same for the user). The machine language program is represented to humans in hexadecimal form, but the computer will see it as ones and zeros (or, if you want to get really specific, not even ones and zeros but voltages that vary from, usually, zero volts to 5 volts, but that represent ones and zeros). To give a better idea of this, I wrote the shortest program that I could. This is the program that is usually presented as someone's first program: "HELLO, WORLD." In BASIC this program is one line and simply looks like this: 10 PRINT"HELLO, WORLD" That's it. It's a bit more complicated in assembly language because the programmer has control over so much more of the computer system. Since there isn't a "Hello, World" available for the Astrocade on BallyAlley.com I took a few minutes and modified a program that was available. Here is the program, followed by plenty of explanations and also instructions on how to actually assemble it. You can look the program over, but there is no need to understand it or how it works. ; Title - Hello World ; By - Adam Trionfo ; Rev - 1.0 - July 27, 2011 ; ; About this Program ; ------------------ ; ; This program displays a short string, "HELLO, WORLD" ; ; To assemble Z-80 source code using ZMAC: ; ; zmac -i -m -o hello.bin -x hello.lst hello.asm INCLUDE "HVGLIB.H" ORG $2000 ; First byte of Cartridge DB "U" ; User System Sentinel DW MENUST ; Next menu link DW PRGNAM ; Address of title for program DW PRGST ; Jump here if prog is selected ; Main Program PRGST: DI SYSTEM (INTPC) DO (SETOUT) DB $B0 ; Vertical Blanking Line DB $2C ; Left/Right Color Boundary DB $08 ; Interrupt Mode DO (COLSET) DW COLTAB ; Color Table DO (FILL) DW NORMEM ; Destination DW 4000D ; Bytes to move DB $00 ; Background color DO (STRDIS) DB 0 ; X coordinate DB 0 ; Y coordinate DB $0C ; Options DW STRING ; Address of string to display EXIT LOOP: NOP JP LOOP ; Infinite loop ; Color Table #1 COLTAB: DB $00 ; Color 3 Left - Black DB $5A ; Color 2 Left - Red DB $77 ; Color 1 Left - Yellow DB $07 ; Color 0 Left - White DB $00 ; Color 3 Right - Black DB $5A ; Color 2 Right - Red DB $77 ; Color 1 Right - Yellow DB $07 ; Color 0 Right - White PRGNAM: DB "DISPLAY STRING" DB $00 ; End String STRING: DB "HELLO WORLD" DB $00 ; End string That's the program used to display "Hello World." To someone that doesn't know assembly language it probably looks pretty complicated. The comments (which are anything written after a semi-colon) are ignored by the assembler and are meant for the person writing and/or reading the program. This program makes heavy use of HVGLIB.H, which is the Home Video Game Library Header file (these are routines that interact with the Bally's On-Board 8K ROM). In fact, without those routines, this program would have been MUCH longer and wouldn't have used the Bally's menu. Even though the above assembly source code is about 1.9K as a text file, after it is assembled the computer code that will run on the Astrocade is just 69 bytes. In fact, here is what the assembled program looks like (each line is 16 bytes long, for ease of reading): 5518022A200720F3FF0017B02C081922 201B0040A00F003500000C39200200C3 1E20005A7707005A7707444953504C41 5920535452494E470048454C4C4F2057 4F524C4400 You could copy and paste the long string of numbers into a hex editor and then save the binary file. You could then run this file in the Astocade MESS emulator and it would run the "Hello World" program. If you wanted, the file could be burned to an EPROM and run on a real Astrocade. Luckily for us, MOST of the time humans don't have to worry about those hex digits. The exception is during debugging when it is very useful to understand them... but we'll ignore that (there is no need to debug the program so we'll just pretend I never said that). A programmer works with the assembly source code and the assembler. I'm now going to explain how to assemble the above program using the ZMac assembler. 1) First off, I'm presuming that you're using a 32-bit version of windows. I've tested this under Windows XP, but it should work on other versions of Windows too. Also, I presume you know a little bit about the command line interface (but you don't need to be an expert by any means). 2) Copy and paste the above program into a text file. Start from the first line, "; Title - Hello World" and continue to the last line, " DB $00 ; End string". Put a blank line after the end of the source code. If you don't put an extra line, then you may get an assembly error on the last line of code. I've never figured out what exactly causes the error, but a blank line after the code is a simple fix to avoid it. For simplicity, save this file under c:\hello as hello.asm. 3) Download and unzip the ZMac assembler. Save it at c:\hello. The assembler is here: http://www.ballyalley.com/ml/ml_tools/Zmac13_win32.zip 4) Download and unzip the Home Video Game Library Header file to C:\hello. The header file, called HVGLIB.H, is here: http://www.ballyalley.com/ml/ml_tools/HVGLIB.zip 5) Your C:\hello directory will now contain quite a few files. The only important ones for right now are: Hello.asm, HVGLIB.H, and zmac.exe 6) Open a command window. The simplest way is to go to Start > Run and type CMD. Navigate to c:\hello. 7) To assemble the "Hello World" program, type: zmac -i -m -o hello.bin -x hello.lst hello.asm 8) After you press the enter key, it should appear as though nothing happened. That is okay. The assembler has already assembled the program. Check your c:\hello directory. You should now have two new files. They are: hello.bin and hello.lst. 9) Hello.bin is the actual 69-byte program. Try running hello.bin using the MESS Astrocade emulator. 10) The Hello.lst program is very useful, especially with debugging, but contains too much detail to explain right now. If you decide to look at it, it can be opened in any text editor. Some of the more important parts of it are: the hex numbers on the left side of most lines and the symbol table. As long as this program is, there are actually only about three lines of code-- the rest is all interaction with the Bally's On-Board ROM. Pretty neat, right? All those other hex numbers contain information that will be used by the On- Board ROM in some way or another. If you want to delve into understanding the On-Board ROM's routines used in the "Hello World" (INTPC, SETOUT, COLSET, FILL, STRDIS and EXIT), then they are all fully described in the ""Home Video Game Manual for the Bally Astrocade" by Dave Nutting Associates (much more commonly known as the "Nutting Manual"). That manual is here: http://www.ballyalley.com/ml/ml_docs/nutting_manual_project_2-1.pdf These directions and the short program were written explicitly to give an idea of what an assembler is and what it does. I wrote these instructions to be easy to follow, but if you encounter any difficulty getting "Hello World" to assemble then be sure to go over the instruction carefully again or make a posting to the Bally Alley discussion group. If you examined the source code then you may have noticed an error. The following line will work fine, but is not grammatically correct: STRING: DB "HELLO WORLD" Why not modify it to what it SHOULD be: STRING: DB "HELLO, WORLD" After the modification assemble the program again. The program will be 70 bytes. It will take hardly any time to correct the program using an assembler. Without an assembler, the program would have had to be modified in a hex editor. With this simple example no jumps are affected, but normally a change like this, which shifts the program one byte, can make a huge difference. Other changes to the program would have been required if an assembler wasn't used. An assembler takes care of a ton of extra baggage so that the programmer doesn't have to worry about it. It's for this reason that I think it's amazing that people could program long programs in hexadecimal only. Assemblers are any machine language programmer's best friend. Good luck... and HAVE FUN! Adam