Part 1 - CDFJ Overview

[+SpiceWare]

Let's start out with an overview of CDFJ. Part 2 will go into more detail.

 

The Harmony/Melody contains 32K of ROM and 8K of RAM.  Breakdown of its usage for CDFJ is:

 

 

 

CDFJ Driver

 

The CDFJ¹ Driver is the ARM code that the Harmony/Melody runs in order to emulate a CDFJ coprocessor.
 
The 6507 in the Atari has no access to the driver. Likewise the ARM has no access to the internals of the Atari.

 
While the driver is located in ROM, it is copied into RAM when the Harmony/Melody first powers up. This is because the code runs faster when located in RAM and the extra speed is required in order for the coprocessor emulation to keep up with the Atari.

 

 

C code & data

 

Unlike DPC+, CDFJ has a dedicated section in the ROM for the compiled C code and its data.  

 

It's only 2K though, so you will most likely use Banks 0+ for your C code. Typical usage for CDFJ projects so far has been:

 

• Banks 0-5 for C code
• Bank 6 for 6507 code

 

- OR - 

 

• Banks 0-4 for C code
• Banks 5-6 for 6507 code

 

 

Bank 0

 

If compiled C code is greater than 2K, it will expand into bank 0. If this occurs it is not recommended to also use bank 0 for 6507 code.  Same recommendation goes for the following banks.

 
The 6507 can select bank 0 by accessing memory location $FFF5².

 

 

Bank 1

 

If custom ARM code is greater than 6K, it will expand into bank 1.
 
The 6507 can select bank 1 by accessing memory location $FFF6².

 

 

Bank 2

 

If custom ARM code is greater than 10K, it will expand into bank 2.
 
The 6507 can select bank 2 by accessing memory location $FFF7².

 

 

Bank 3

 

If custom ARM code is greater than 14K, it will expand into bank 3.
 
The 6507 can select bank 3 by accessing memory location $FFF8².

 

 

Bank 4

 

If custom ARM code is greater than 18K, it will expand into bank 4.
 
The 6507 can select bank 4 by accessing memory location $FFF9².

 

 

Bank 5

 

If custom ARM code is greater than 22K, it will expand into bank 5.

If your 6507 code is greater than 4K you should use banks 5 & 6 for 6507 code. So far all of my CDFJ games have only had 4K of 6507 code, though I know John's Wizard of Wor has 8K.

 
The 6507 can select bank 5 by accessing memory location $FFFA².

 

 

Bank 6

 

Bank 6 is used for 6507 code. When a CDFJ cartridge is powered up bank 6 will already be selected. If you've selected another bank then access $FFFB² to reselect bank 6.

 

 

Display Data

 

When the Harmony/Melody is first powered on the 4K of RAM holding Display Data is not initialized, so it's up to your code to do so.  This was done to keep the CDFJ driver 2K in size.

 
While the Atari cannot "bank in" the Display Data, it can read its contents using Data Streams³. This is how the custom C code will pass information to the 6507.
 
The Atari can also write to Display Data by using a Data Stream. This is how the 6507 code will pass information, such as the current state of the joysticks and console switches, to the custom C code.
 
 

C Variables & Stack

 

2K of RAM is dedicated for use by C variables and its Stack.  Depending upon your project this may not be enough, so we will go over how to allocate part of Display Data into the C Variables and Stack.

 

 

ARM

 

The ARM CPU used in the Harmony/Melody is the ARM7TDMI-S LPC2103. It's specs are:

• 32 bit CPU
• 70 MHz
• 32 KB Flash (the "ROM")
• 8 KB SRAM (the "RAM")

 

 

Further Reading

 

cd-w posted a few blog entries back in 2009 and 2010:
 
Perfect Harmony
 
Harmony Memory
 
More Harmony
 
They go over how the Harmony/Melody emulate a cartridge (including bankswitching support), the speed differences between SRAM vs Flash, and many other interesting bits of information. Go check them out, you'll be glad you did!

 

 

 

¹ CDFJ stands for Chris (@cd-w) Darrell (@SpiceWare) Fred (@batari) and John (@johnnywc), who were involved in its creation.

 

² due to the 6507's 8K addressing space, these locations are mirrored multiple times in memory. The mirrors are $1FFx, $3FFx, $5FFx, $7FFx, $9FFx, $BFFx and $DFFx. Any of the mirror addresses may be used. I think of them being located at $FFF5-FFFB due them being right before the RESET and IRQ vectors. The 6507 is a reduced package version of the 6502, which I first learned to program in the early 80s on my Vic 20. On a 6502 these vectors are, by definition, located at addresses $FFFC-FFFD and $FFFE-FFFF.

 

³ Data Streams will be covered in Part 2

[cd-w]

Nice work - I have been meaning to write this down for a long time, but never have time!

 

Once minor point to note is that the stack grows down from the top of the memory area, and the variables grow up from the bottom and will be corrupted if they meet the stack.

Edited October 29, 2019 by cd-w

[+SpiceWare]

Yep, just like the 2600's RAM and stack.  I plan to cover that in more detail when I cover how to allocate part of Display Data to the C Variables and Stack space.

[Dionoid]

Hi Darrell, thanks for starting this overview on CDFJ!

 

After finishing my current game (Tower of Rubble), my next game will be using ARM, so the timing of your posts on CDFJ is perfect! ?

Two questions:

• I assume that second 2K (for C code and data) goes from $0800 - $0FFF, not $0800 - $1FFF. A typo, right?
• The difference with DPC+ seems to be the smaller ARM driver, leaving more ROM for your game, right?
  Are all the blogposts on DPC+ still valid, or is CDFJ different on essential parts?
• The CDFJ acronym is really hard to remember; too many consonants. Maybe call it DPC-2 ? ?

Edited October 31, 2019 by Dionoid

[Dionoid]

4 hours ago, Dionoid said:

Hi Darrell, thanks for starting this overview on CDFJ!

 

After finishing my current game (Tower of Rubble), my next game will be using ARM, so the timing of your posts on CDFJ is perfect! ?

Two questions:

• I assume that second 2K (for C code and data) goes from $0800 - $0FFF, not $0800 - $1FFF. A typo, right?
• The difference with DPC+ seems to be the smaller ARM driver, leaving more ROM for your game, right?
  Are all the blogposts on DPC+ still valid, or is CDFJ different on essential parts?
• The CDFJ acronym is really hard to remember; too many consonants. Maybe call it DPC-2 ? ?

Never mind my question on differences between DPC+ and CDFJ; I think this post by Darrell explains it all.

And there is a wealth of posts by Darrell on DPC+ARM, which I just discovered and will read into the coming days. Great stuff!

Edited October 31, 2019 by Dionoid

[+SpiceWare]

Awesome, can't wait to see what you do with it!

 

Yep - that's a typo, looks like it's been around for quite some time.

 

Main difference is DPC+ was designed to work with 6507 code, just like DPC as used in Pitfall 2.  Running ARM code was added as an afterthought, so it's a bit rough around the edges and some things are very inefficient such as the datastreams are only configured via 6507 code, which takes scanlines worth of processing time. CDFJ was designed from the ground up to run ARM code.

DPC+ blog posts are still valid, though they were never finished.  Also with the forum update the blog entries were messed up a bit (check the code blocks in part 8)and it's difficult to find them all, though it looks like you took care of that - thanks!  For the Collect tutorial I have an index and went thru and fixed every entry. I'd started to fix the DPC+ tutorial (the code blocks are OK in part 7) but haven't finished because I decided to redo them for the Harmony/Melody club instead.

 

It used to be CDF, J was added when John put in an enhancement request for one of his games. The letters are in alphabetical order to help remember them.

[Dionoid]

On 10/31/2019 at 9:46 PM, SpiceWare said:

Awesome, can't wait to see what you do with it!

...

Below is a Stella screenshot of the CDFJ-game I'll be working on after I finish Tower of Rubble.

The working title is "Fool's Gold", and it's a port of one of my favorite games on the Commodore 64. I wanted to make this port for the '2600 some time ago, but until now I didn't manage to cram it into a 76-cycle kernel and 128 bytes RAM (or even a Superchip with an additional 128 bytes).

 

It's only a proof-of-concept for now, just to see if I can have the ARM create data streams for an asymmetric playfield. Apparently it works ? 

 

About the "J" in CDFJ: I met John Champeau at PRGE 2019 just a couple of weeks ago, and he got me interested in CDFJ by giving me a 10 minute crash course. After that he provided me with a small CDFJ test solution, which basically shows the famous '2600 rainbow screen and a sprite that can move up and down.

 

Edited November 8, 2019 by Dionoid

[+SpiceWare]

Looks good!

 

Long time ago @EricBall was working on a port called Leprechaun. It was written for the Arcadia Supercharger.  Based on this post of mine, there should be a ROM in this blog entry but it's missing.  After the forum upgrade I noticed missing attachments with a number of my blog posts as well; the attachments are still there, just not visible.  A simple edit of the blog entry brings them back, but it's time consuming so I've only fixed some of mine.

 

[Dionoid]

44 minutes ago, SpiceWare said:

Looks good!

 

Long time ago @EricBall was working on a port called Leprechaun. It was written for the Arcadia Supercharger.  

...

Yes, I came across his port in the AtariAge forum. Impressive work, as the Arcadia Supercharger is not easy to program.

However the tiles are using a single PF-pixel, and player graphics are only 4/5 pixels wide, which IMO doesn't look great on screen.

 

Anyway, let's see how my version turn outs. At the moment it's nothing more than a rom showing a static screen, so I guess I have put my money where my mouth is ?

Edited November 8, 2019 by Dionoid

[+SpiceWare]

Made some progress for Part 3.  It's Part 7 of the DPC+ tutorial converted to CDFJ. I've also updated it to be built with a make file that automatically transfers variable values from the 6507 code to the C code.

 

 

Also have a very rough draft for Part 2.  I suspect I'll post it unfinished so I can get Part 3 posted, then make revisions to Part 2 as I work on Parts 4+.