HLL65F - INDEN/UNDEN

Notes: Since writing this post I have solved the mystery of the two cryptic lines, I wrote another post about this: 

https://dansdigitalarchaeology.blogspot.com/2022/09/hll65f-indenunden-mystery-solved.html

In my last post I introduced the HLL65 high level language 6502 macro library used in the Atari Crystal Castles source code. The macro definitions used macros called INDEN and UNDEN that I assume are for handling indentation of the code in the listing file. Exactly how these work is a little but of a mystery to me. Here is the code for INDEN:

.MACRO $INDEN
.PUSH REGSAV,...S1

.IF LT,..NST$
.ERROR ..NST$ ; STACK UNDERFLOW
..NST$ = 0
.ENDC

...S1 = ..NST$+1*3+..SRC$
.IIF GT,...S1-<9.*3+..SRC$>,...S1 = 9.*3+..SRC$
.LIST SRC(...S1,1)
.PRINT ..NST$(37,1,16,1,38'->')
..NST$ = ..NST$ + 1
.POP REGSAV,...S1
.ENDM

Like most macros is starts by saving a variable on the stack. The ..NST$ variable is used to keep track of the depth of the indent, so the next block of lines checks to be sure the code hasn't undented further then it has indented and if it did it throws an assembler error. 

When the macro library is initialized ..SRC$ is set to 41, so the next line sets ...S1 to 41 + 3 times the current number of indents. The next line checks if ...S1 is beyond 9 indents and if it is, it sets it back to the value for 9 indents. 

The next line is the first one I don't understand. According to documentation I found for a VAX assembler, .LIST is used to control what gets displayed in the listing, but the documentation does not list the argument syntax used in this code. It's possible this is displaying the current line at a specific place on the line. 

The .PRINT pseudo-op is used to write text to the listing output, but the rest of this line is quite cryptic. The string '->' makes sense as an indication of indentation, but I am not sure what the numbers before it do. I also don't understand the parenthesis right after the ..NST$ variable. 

The next line increments the indent counter and finally the value of ...S1 is restored. 

The OUTDEN macro works the exact same way as this macro, but it just reduces the indent. 

If anyone has any ideas about the two cryptic lines, let me know. 

HLL65F.MAC

HLL65F.MAC is a standard Atari macro library that adds some high-level language constructs to the 6502 assembler. It adds IF/THEN statements, conditional loops and a few other miscellaneous helper macros. Let's start by looking at an example of a conditional:

CPX #78
IFEQ
   ADC #2
ENDIF

First, keep in mind that this is not conditional assembly, there are pseudo ops for that, this is an actual runtime conditional. This macro check if the zero flag is set and if it is the code between the IFEQ and ENDIF is executed. Let's look at how these macros are expanded. First, a macro is used to define the IFEQ macro:

    DEFIF IFEQ,BNE

DEFIF is defined with this macro:

.MACRO DEFIF .1.,.2.

.NOCROSS .1.
  .MACRO .1.
IFXX .2.
.ENDM
.ENDM

It will expand to this:

.NOCROSS IFEQ

.MACRO IFEQ

    IFXX BNE

.ENDM

.NOCROSS tells the assembler not to add this symbol to the cross reference list. The rest of the expansion is the definition of a new macro which is just the IFXX macro with "bne" as the parameter. Here is the IFXX macro:

.MACRO IFXX .1.

LOC 0
.1. .
.ENDM

This expands to:

LOC 0

bne .

The first line is another macro which we will look at next. The second line branches back to itself. Since the macro is looking for Equals, this line will branch over the code in the block if the condition is Not Equals. Until the ENDIF is assembled the assembler doesn't know what the actual branch target should be, so the branch to self is used as a placeholder. Here is the LOC macro:

.MACRO LOC type

$INDEN

.PUSH REGSAV,...P0,...S0,...P1,...S1

...P0 = .

...S0 = type

.PUSH PC,...P0,...S0

.POP REGSAV,...S1,...P1,...S0,...P0

.ENDM

and here is the expansion:

$INDEN

.PUSH REGSAV,...P0,...S0,...P1,...S1

...P0 = .

...S0 = 0

.PUSH PC,...P0,...S0

.POP REGSAV,...S1,...P1,...S0,...P0

There are two possible values for the type parameter, 0 for IF blocks and 2 I believe is for a loop block but I haven't figured that one out yet. The INDEN macro is for doing indents in the listing and doesn't impact the code that is generated, I will code this macro in another post since it is a little mysterious. The second line saves a couple variables onto the REGSAV stack. ...P1 and ...S1 aren't  used so they didn't actually have to save then. Next it puts the current program counter into ...P0 and the type into ...S0 and pushes these on the PC stack, these will be used later to end the block. Finally the original variable values are restored from the stack.

Now that the block has been started we need to look at how it ends, in this case with the ENDIF macro:

.MACRO ENDIF

THEN

.ENDM

This macro is simply composed of another macro called THEN. I haven't dug into how you would use THEN by itself. THEN looks like this:

.MACRO THEN

FND

$UNDEN

.ENDM

just like $INDEN, $UNDEN is used for indentation in the list and I will cover this in another post, so that just leaves the FND macro:

.MACRO FND

.PUSH REGSAV,...P0,...S0,...P1,...S1

...P0 = .

.POP PC,...S1,...P1

.if eq,...s1&2

    . = ...P1+1

    .IF EQ,...S1&1

        ...S0 = ...P0-...P1-2

        .IIF GT,...S0-127.,.ERROR ...S0 ; BRANCH OUT OF RANGE

        .IIF LT,...S0+128.,.ERROR ...S0 ; BRANCH OUT OF RANGE

        .BYTE ...S0

    .IFF

        .WORD ...P0

    .ENDC

     . = ...P0

 .iff

     .ERROR TYPE ;inappropriate END for structure type

  .endc

 .POP REGSAV,...S1,...P1,...S0,...P0

.ENDM

This is the workhorse of this entire macro. It is basically going to use the information on the stack to modify the BNE opcode that was assembled in the IF macro so that it will branch past the block of code if the condition wasn't met. 

 First it saves that registers on the REGSAV stack so they can be restored at the end of the macro. Next the type is popped from the stack and stored in ...S1 and the program counter is popped and stored in ...P1. Next it checks if bit 1 or the type is set, in this case it will not be since the type is 0 so the condition will be met since the conditions is "equals zero". The next line will set the current program counter to the original program counter + 1 which will point it to the offset in the BNE opcode. Next bit 0 of the type is checked and again the condition is met. Next the offset for the branch is calculated by subtracting the original program counter from the program counter as it was when the macro started and then subtracting 2 and storing the result in ...S0. The next two lines check if the branch will be out of range, and if it is shows an assembler error.   After the just check is a .BYTE pseudo op that injects the new calculated offset into the BNE opcode that was assembled in the IF part of the macro. After the inner condition the current program counter is restored to where it was at the start of the macro, and then finally the registers are restored. 

These macros are a little complex but they do provide a clever way of implementing run time conditional blocks. The use of the assembler stack in the macros allows you to next IF blocks several levels deep just like in a higher level language. 

Crystal Castles Assembler - Stacks

This is a continuing look at some of the features of the 6502 assembler Atari used for arcade games like Crystal Castles. One of the unique features, one I haven't seen in any other 6502 assembler, is the ability to define assembler level stacks. These have nothing to do with the 6502 stack, but instead are used to control the assembly process. 

You start by defining a stack using this pseudo op:

.DEFSTACK REGSAV, 4

There are two parameters. The first, in this case "REGSAV", is the name you want to give to the stack. You will use this to interact with the stack.

The second parameters, 4, is the size of the stack, so this stack will be able to hold up to 4 values.

To put a value on the stack you use the .PUSH pseudo op:

.PUSH REGSAV,1

This will push the value 1 onto the stack named REGSAV. The second parameter can also be an expression. I don't know if the original assembler allowed text strings to be pushed onto the stack but my version of the assembler only allows numbers to be pushed onto the stack. 

To get a value off the stack you use the .POP pseudo op:

.POP REGSAV,S1

This will pull the top value off the stack named REGSAV and put it into variable S1. The second parameter here must be a variable, not an expression.

You can use the .GETPOINTER pseudo op to get the stack pointer for a specific stack:

.GETPOINTER REGSAV,P1

This will put the stack pointer for stack REGSAV into variable P1. The stack pointer works from high to low, so if you declare a stack with the size 4, the initial pointer will be 4. If the pointer is 0 it means that stack is full.

Since I can only go by the source code I don't know what happens if you try to push a value onto a full stack or pull a value from an empty one. My version of the assembler currently doesn't handle these scenarios.

In a later post I will show how this features is used in the Crystal Castles source.

Crystal Castles Assembler

When I found the Crystal Castles Source code I thought it would be cool to able to re-assemble the source so modifications could be made to the game from the original source. I didn't take long to realize that the assembler used by Atari had a lot of differences from assemblers I was familiar with. I started Googling some of the unusual pseudo ops in the source to see if I could identify an assembler that was compatible with this code. I found manuals for similar assemblers but nothing was a perfect match.

The best resource I found was the VAX MACRO and Instruction Set Reference Manual:

https://www.ece.lsu.edu/ee4720/doc/vax.pdf

It is not surprising that this assembler is close, Atari did a lot of their arcade development on DEC VAX mainframes. This became my go-to document for writing my assembler. If there was anything that was not clear from the source, but was answered in this document, I used what was in this document. 

Addressing Modes

One of the strangest differences between this assembler and other common 6502 assemblers is the syntax to define addressing modes. All the modes can be defined with prefixes to the operand, so for example, for absolute X you would do LDA AX,$1000 instead of LDA $1000,X. There are even multiple ways to define the same mode, at it appears different programmers used different ones. Here are the prefixes for the addressing modes:

# or I, - Indirect
ZX, - Explicit zero page X
ZY, - Explicit zero page Y
Z, - Explicit Zero page   
NX, - Indirect X
NY, - Indirect Y
AX, - Absolute X
AY, - Absolute Y
A, - Absolute
X, - Absolute or Zero Page X determined by the assembler 
Y, - Absolute or Zero Page Y determined by the assembler 

There are also two suffixes that can be used, (X) and (Y). You would think that these would be for indirect modes, but they are not, they are for absolute X and Y. I also found "(X" in the code. I assume this is an anomaly of the assembler where it doesn't parse the entire addressing mode identifier. 

Radix

The Atari assembler provides two different ways of controlling the radix (base) of numbers. First, the radix can be specified using a prefix on the number ^H for Hex and ^B for Binary. There is probably a prefix for octal but the Crystal Castles code doesn't use it. The second way of specifying radix is to use the .RADIX pseudo op which specifies the default radix to use when parsing numbers. For example if this is in the source:

.RADIX 16 

it will set the default radix to hex so that if a number doesn't have an explicit radix prefix it will be interpreted as hex. To avoid confusion with symbols, a hex number must start with a number if it doesn't have a prefix, so for example A5 would have to be written as 0A5. In my version of the assembler I always treat the parameter for the radix pseudo op as a decimal.

.REPT/.ENDR

The .REPT pseudo op looks pretty straight forward but there turned out to be some tricky parts to it. This pseudo-op repeats a block of code a specified number of times during assembly. It is passed one parameter which is the number of times to repeat it. 

The first interesting thing I found about it is that the Crystal Castles sources often uses it with a repeat count of zero. The basically works like a block comment, preventing the block of code from being assembled at all. 

The other interesting thing I found in the code was the .REPT blocks were sometimes ended using .ENDM, which ends a macro definition, instead of .ENDR. My theory on this is that if a repeat block is started inside a macro definition then it would make no sense for it to extend beyond the end of the definition, so it's possible that the assembler explicitly ends open repeat blocks at the end of a macro definition. This was probably an un-intended side effect of the way the assembler was written. 

I will cover some more differences in a latter post.

Crystal Castles Source Files

In my last post I gave an overview of the files in the Historical Source Code  repository for Atari's Crystal Castles arcade game. In this post I will go into the files in detail. Here are the files in alphabetical order:

C00.DAT - C33.DAT : These contain the level data. I will go into these in more detail in a later post.

BITPAT.MAC: This files contains 8 bytes, represented as binary numbers in the file. The file is included into CEL.MAC and appears between two subroutines. It doesn't appear that this data is actually used by the game. It might be some sort of security or anti-piracy protection.

C99.MAC: Links together all the level data. This is assembled separately from the main program and becomes the second bank of ROMs.

CAL.MAC: Handles the display of the score and the high score screen.

CATOUT.MAC: Displays the Atari Easter egg message. Shown on the next level after you have jumped 128 times on the previous level.

CCN.MAC: 650X 'Universal' coin routine. This is a standard code library for handling the coin mechanism.

CCT.MAC: Draws the levels

CCUBE.MAC: Draws a cube on the screen. This is only used by the special display that happens when you score over 700,000 points.

CDB.MAC:  Routine to transfer level data from ROM to RAM 

CEE.MAC: EEROM routines 

CEEDEF.MAC: definitions for EEROM routines

CEL.MAC: Elevator handling 

CEN.MAC: Main game logic

CET.MAC: Auxiliary EEROM information, tables, output routines etc.

CG.MAC:  Global definitions and memory allocation

CGR.MAC: Global data and routines

CIN.MAC: Interrupt handlers

CLS.MAC: Sound and music data

CMAC.MAC: A couple macros to simplify common 6502 tasks

CMN.MAC: Main loop

CMR.MAC: Message display routines

CMS.MAC: Word data

CMTB.MAC: Message table

CRF.MAC: Root file

CRP.MAC: RPM (Rusty's POKEY Music) Driver

CSL.MAC: Symbol shape data

CSS.MAC: Test menu

CST.MAC: Self test

CSTART.MAC: Includes macros and zero page definitions

CWV.MAC: Level handling

HLL65F.MAC: High level language macros

M6502.MAC:  6502 general purpose macros

CJTB.MAC: This file is missing from the archive but is included in CRP.MAC. It it a patch to the POKEY music driver. I recreated this file from the original ROMs.

Crystal Castles Source File Overview

Recently Historical Source Code published the original source code for a couple Atari arcade games including Crystal Castles. In this post I will give an overview of the the files that are included in the archive. The files can be found here:

 https://github.com/historicalsource/crystal-castles

The archive contains three sets of files for Crystal Castles, the one in the root directory of the repository, which I will call the master set, and two others sets called version-2 and version-3. In this post I will focus on the master set, since the other two contain some different files. Using my assembler I was able to re-assemble the master set to produce the ROMs that match the MAME ccastles1 set. I still need to determine if the other two versions of the source match up with other MAME ROM sets. The main ROM set in MAME, ccastles, does not match any of the source in the archive. The first ROM has a copyright message in it and the MAME base set also contains the phrase "PIRATES BEWARE" which is not in any of the source. 

Here is an overview of the files in the archive:

372X1.DOC 

This appears to be some sort of standard form used by Atari to document game projects, since similar files appear in the repositories for other games. The file contains all the details of the ROMs that make up the game, a description of how to assemble the files and a signoff form at the bottom.

022X1.DAT

This contains a single line of ASCII data that provides details of the ROMs that make up the game. This file is referenced in 372X1.DOC and is called the "Verification control file". I still need to study this file some more to understand the format.

372BR.RS4

This file is referenced in 372X1.DOC and 022X1.DAT so has something to do with the verification process, but I am not sure what the data in it represents.

*.MAC

The .MAC files are the macro-assembler source files for the game. Most of the files are for the fixed ROM and the first ROM bank. C99.MAC and the .DAT files are for the second ROM bank. CRF.MAC is the root file, the other files are either included in CRF.MAC, or included into other includes. There was one file missing from the archive, CJTB.MAC, which is included into CRP.MAC. To be able to re-assemble the code I had to re-create this file from existing ROMs. I will look at these in more detail in a future post.

Cxx.DAT

These files contain the level data for the game and are included into C99.MAC. This is assembled separately and forms the second bank of ROM.

*.LDA

These are the binary output of the original assembler in a format that makes them linkable to other binaries to form the final output. I need to do some more research to figure out the format of these files. 

Crystal Castles Source Code

I recently ran across a bunch of Atari arcade source code that was added to the Historical Source Github site, including the source for one of my favorite games, Crystal Castles.

https://github.com/historicalsource/crystal-castles

I thought it would be cool to be able to re-assemble this back into the original ROMs. I started by trying to find an existing assembler that could do this, but the assembler used for this source had a lot of syntactical differences and features I couldn't find in any other 6502 assembler. I assume Atari used a VAX based assembler and I did even find documentation for a VAX assembler with similar features, but still not an exact match. 

I then thought about manually modifying the source to work with an existing assembler. I quickly realized that this wasn't feasible due to some of the odd syntax in this assembler. For example the Atari assembler has an different syntax for addressing modes. You can write Zero Page X like this: "LDA ZX,$PSTSL", you couldn't fix this with a simple search and replace. This would also have to be done for every game I wanted to re-assemble. 

So I decided the best option was to build my own assembler that could handle these files with little changes to the original source. The assembler I build is now able to reassemble the main source from the historical source repository and reproduce the MAME ccastles1 ROM set. 

I have setup a GitHub repository to hold the C# source code for my assembler as well as tool to split the output into separate ROMs and handle the checksum process. There is also a folder there with the files and instructions needed to rebuild the source. There are some small changes needed to the source which I have documented in the instructions, and there was one file missing from the Historical Source archive which I re-created from the original ROMs. 

https://github.com/danlb2000/AT6502