Programming Plus Cartridges

[redbox]

So, what are the rules for programming cartridges?

Does the cartridge copy itself into RAM and then execute?

And how to people get DSK games onto Cartridge?  And why can't Cartridge games be copied onto a DSK (I wouldn't mind running Pang from my disk drive!)?

I want to start developing cartridge software but can't find much info... 

[arnoldemu]

So, what are the rules for programming cartridges?

Does the cartridge copy itself into RAM and then execute?

And how to people get DSK games onto Cartridge?  And why can't Cartridge games be copied onto a DSK (I wouldn't mind running Pang from my disk drive!)?

I want to start developing cartridge software but can't find much info... 

cart page 0 is mapped into ram at &0000-&3fff. when the computer is reset.
The rom is executed in place, so no copying into ram.

After this you can control where the roms are mapped using the cpc+ hardware. You can map both a rom into &0000-&3fff and &c000-&ffff AND have the asic registers mapped into &4000-&7fff at the same time. So you have quite a flexibly way to organise memory.

You can easily map the rom and copy data direct into the asic memory mapped registers, and then use the ram for storing data that must be read/write. So having 64k ram is not really so bad, when you can run most of your code direct from rom with no speed penalty.

for the dsk games into cartridge, they use a tool made by nocash which simulates a disk drive and effectively turns the whole rom into a large read-only disc.

Cartridge games can't be copied to disc (unless they are small) because they execute from rom, and page the rom in/out to do their work. So to convert them you would need to hack this, and it would be a lot of work and would probably only run if you had a load of ram to hold the effective rom contents

[Bryce]

Also, the ACID would still need to be present if the game was loaded from disk.

Bryce.

[redbox]

cart page 0 is mapped into ram at &0000-&3fff. when the computer is reset.
The rom is executed in place, so no copying into ram.
After this you can control where the roms are mapped using the cpc+ hardware. You can map both a rom into &0000-&3fff and &c000-&ffff AND have the asic registers mapped into &4000-&7fff at the same time. So you have quite a flexibly way to organise memory.

Are there any code examples of this available?  Or do I have do disassemble a CPR to find out how it's done in practice?

I would love to have some working examples of how to program a cartridge.

Cartridge games can't be copied to disc (unless they are small) because they execute from rom, and page the rom in/out to do their work. So to convert them you would need to hack this, and it would be a lot of work and would probably only run if you had a load of ram to hold the effective rom contents

I did think this...

However, it would be nice to have the ability to program custom cartridges.  An interesting example would be the BASIC/Burnin' Rubber cartridge I guess as it pages either BASIC/AMSDOS (which is 32k right?) into CPC RAM or it executes the game elsewhere.

I would like to do some of the following:

- BASIC/AMSDOS Rom with a patched BASIC so that extension roms (Maxam, Protext etc) can be loaded (i.e. it scans for ROMS 0-7 instead of 128 upwards)
- BASIC/AMSDOS with a selectable menu for games etc (probably require a 512k EPROM and has been done by Polish bootleggers, see 'Greatest Hits' cartridge)

or something along these lines.  The cartridge has loads of space and potential and would be great to develop some stuff even if it means cannibalising old carts before an ACID replacement is developed.

[arnoldemu]

Are there any code examples of this available?  Or do I have do disassemble a CPR to find out how it's done in practice?

no and yes.

I would love to have some working examples of how to program a cartridge.

Same here, maybe I need to write something.

I did think this...

However, it would be nice to have the ability to program custom cartridges.  An interesting example would be the BASIC/Burnin' Rubber cartridge I guess as it pages either BASIC/AMSDOS (which is 32k right?) into CPC RAM or it executes the game elsewhere.

I know that basic and amsdos are effectively mapped as rom number 0 and 7.
Not sure about the other pages, that would be interesting to find out.

- BASIC/AMSDOS Rom with a patched BASIC so that extension roms (Maxam, Protext etc) can be loaded (i.e. it scans for ROMS 0-7 instead of 128 upwards)
- BASIC/AMSDOS with a selectable menu for games etc (probably require a 512k EPROM and has been done by Polish bootleggers, see 'Greatest Hits' cartridge)

That would be cool to see.

or something along these lines.  The cartridge has loads of space and potential and would be great to develop some stuff even if it means cannibalising old carts before an ACID replacement is developed.

I agree.

[Bryce]

Programming a cartridge should be very similar to programming a standard ROM such as Maxam, there are many articles about programming ROMs, this would be a good place to start.

AMSDOS already scans for ROMs 15-0 on boot-up (but not the cartridge area, only the expansion port), so you don't really need to patch anything, if you put Maxam on the same ROM as AMSDOS, you would either need to have an F1/F2 option like Burning rubber has, or manually activate it, as this area isn't mapped at boot up.

Bryce.

[redbox]

no and yes.

Well I found that CPC Rulez has a good article on the layout of the BASIC/Burnin' Rubber cartridge so I will start digging there!

there are many articles about programming ROMs

Do you have any links?

AMSDOS already scans for ROMs 15-0 on boot-up (but not the cartridge area, only the expansion port), so you don't really need to patch anything, if you put Maxam on the same ROM as AMSDOS, you would either need to have an F1/F2 option like Burning rubber has, or manually activate it, as this area isn't mapped at boot up.

Yes, but it may be possible to alter AMSDOS so that it doesn't look at the expansion port but instead looks in the cartridge because then you would essentially have a ROMbox inside the cartridge.

I wouldn't want to try to put, for example, Maxam instead of AMSDOS, rather use the space between ROM 0 and ROM 7 for actual ROMS.  Then patch AMSDOS to realise this.  All theory of course, but hopefully it can be done.

[Bryce]

Here's a few that might help:

http://www.cpctech.org.uk/docs/manual/s158se09.pdf

http://www.cantrell.org.uk/david/tech/cpc/CWTA-writing-ROMs.html

http://www.binaria.co.uk/cpc_roms.html

Bryce.

[redbox]

Great stuff Bryce, thanks. 

I have started making my own cartridges out of system ROMs, will post some here when they're working. 

[arnoldemu]

Do you have any links?

There are some articles about programming roms. These refer to those that work with the firmware/os, and these have a special header.

But, programming for the cartridge is different. No header is required here..

  Yes, but it may be possible to alter AMSDOS so that it doesn't look at the expansion port but instead looks in the cartridge because then you would essentially have a ROMbox inside the cartridge.

I wouldn't want to try to put, for example, Maxam instead of AMSDOS, rather use the space between ROM 0 and ROM 7 for actual ROMS.  Then patch AMSDOS to realise this.  All theory of course, but hopefully it can be done.

You'd need to modify the OS itself. This "walks" the roms to find those installed.
It would need to add on 128 for each of the rom numbers and walk it like this I think.

There is a partially commented dissassembly of the OS here:

http://www.cpctech.org.uk/docs/os.asm

*but* I know of one game compilation for the cpc+ that is built using standard "roms" and has a menu where you can choose which you want to play.
"amstrad classics" by "dadman"

[redbox]

Well I have started to disassemble the Plus system cartridge and have had some success. 

I have located the menu choice (f1 for BASIC, f2 for Burnin' Rubber) in the AMSDOS ROM etc and then by-passed it by patching the code.  Now my cart just goes straight to BASIC and you can access Burnin' Rubber by typing |GAME (or |JEUX, |SPIELE or |JUEGO).  I have attached the new cart image to this post.

One annoyance is that the BASIC doesn't appear after the Amstrad message, but after a screen reset.  The code used to start BASIC by AMSDOS in the Plus cartridge is:

Code Select Expand


ld hl,&0000
jp &bd16             ;; MC_START_PROGRAM


If you try this on any CPC you will see this just loads BASIC and any ROMs you have installed, but it also resets the screen (unlike when a classic CPC boots up).  I have looked at Kev's OS ROM dump and AMSDOS ROM dump and can't see how the old generation CPCs didn't do this screen reset when loading  BASIC - anyone got any ideas?

Just encase anyone is interested, here is my disassembly of the menu part of the AMSDOS ROM:

Code Select Expand


;; ====================

;; print menu text on screen

cdd7 2121ce    ld      hl,0ce21h        ;; location of 'menu text'
cdda 7e        ld      a,(hl)
cddb 23        inc     hl
cddc b7        or      a
cddd 2814      jr      z,0cdf3h
cddf fe1b      cp      1bh
cde1 2805      jr      z,0cde8h
cde3 cd5abb    call    0bb5ah
cde6 18f2      jr      0cddah
cde8 3e9a      ld      a,9ah
cdea 0611      ld      b,11h
cdec cd5abb    call    0bb5ah
cdef 10fb      djnz    0cdech
cdf1 18e7      jr      0cddah

;; set the timer

cdf3 210000    ld      hl,0000h           
cdf6 54        ld      d,h
cdf7 5d        ld      e,l
cdf8 cd10bd    call    0bd10h            ;; KL_TIME_SET
                        ;; Action    Sets the elapsed time (in l¡300ths of a second)
                        ;; Entry    DEHL contains the four byte count of the time to set
                        ;; Exit        AF is corrupt, and all other registers are preserved

;; find out the time

cdfb cd0dbd    call    0bd0dh            ;; KL_TIME_PLEASE
                        ;; Action    Returns the time that has elapsed since the computer was switched on or reset (in 1/300ths of a second)
                        ;; Entry    No entry conditions
                        ;; Exit        DEHL contains the four byte count of the time elapsed, and all other registers are preserved
                        ;; Notes    D holds the most significant byte of the time elapsed, and L holds the least significant; the four byte count overflows after approximately l66 days have elapsed.


cdfe af        xor     a            ;; ?? LD A,0
cdff 11d8dc    ld      de,0dcd8h
ce02 19        add     hl,de
ce03 da5dce    jp      c,0ce5dh            ;; run Burnin' Rubber

ce06 cd1bbb    call    0bb1bh            ;; KM_READ_KEY
                        ;; Action    Tests whether a key is available from the keyboard
                        ;; Entry    No entry conditions
                        ;; Exit        If a key is available, then Carry is true, and A contains the character; otherwise Carry is false, and A is corrupt; in either case, the other registers are preserved

ce09 30f0      jr      nc,0cdfbh        ;; if no key pressed, loop back to 'find out the time'

ce0b fe81      cp      81h            ;; ?? is it f1
ce0d 280c      jr      z,0ce1bh            ;; ?? then 'execute BASIC'
ce0f ee82      xor     82h            ;; ?? is it f2
ce11 ca5dce    jp      z,0ce5dh            ;; then 'run Burnin' Rubber'

ce14 3e07      ld      a,07h
ce16 cd5abb    call    0bb5ah            ;; TXT_OUTPUT
                        ;; Action    Output a character or control code (&00 to &1F) to the screen
                        ;; Entry    A contains the character to output
                        ;; Exit        All registers are preserved
                        ;; Notes    Any control codes are obeyed and nothing is printed if the VDU is disabled; characters are printed using the TXT OUT ACTION routine; if using graphics printing mode, then control codes are printed and not obeyed

ce19 18d8      jr      0cdf3h            ;; loop back to 'set the timer'

;; ====================

;; execute BASIC

ce1b 210000    ld      hl,0000h
ce1e c316bd    jp      0bd16h            ;; MC_START_PROGRAM
                        ;; Action    Runs a foreground program
                        ;; Entry    HL contains the entry point for the program, and C contains the ROM selection number
                        ;; Exit        Control is handed over to the prograrn and so the routine is not returned from

;; menu text

ce21 1f        rra                     ;; ?? text control characters to draw box
ce22 07        rlca   
ce23 0b        dec     bc
ce24 96        sub     (hl)
ce25 1b        dec     de
ce26 9c        sbc     a,h
ce27 1f        rra     
ce28 07        rlca   
ce29 0c        inc     c

ce2a 95        sub     l            ;; text        "|f1 Amstrad BASIC |"
ce2b 66        ld      h,(hl)            ;; text
ce2c 312041    ld      sp,4120h            ;; text
ce2f 6d        ld      l,l            ;; text
ce30 73        ld      (hl),e            ;; text
ce31 74        ld      (hl),h            ;; text
ce32 72        ld      (hl),d            ;; text
ce33 61        ld      h,c            ;; text
ce34 64        ld      h,h            ;; text
ce35 2042      jr      nz,0ce79h        ;; text
ce37 41        ld      b,c            ;; text
ce38 53        ld      d,e            ;; text
ce39 49        ld      c,c            ;; text
ce3a 43        ld      b,e            ;; text
ce3b 2095      jr      nz,0cdd2h        ;; text

ce3d 1f        rra     
ce3e 07        rlca   
ce3f 0d        dec     c

ce40 95        sub     l            ;; text        "|f2 Burnin' Rubber|"
ce41 66        ld      h,(hl)            ;; text
ce42 322042    ld      (4220h),a        ;; text
ce45 75        ld      (hl),l            ;; text
ce46 72        ld      (hl),d            ;; text
ce47 6e        ld      l,(hl)            ;; text
ce48 69        ld      l,c            ;; text
ce49 6e        ld      l,(hl)            ;; text
ce4a 27        daa                     ;; text
ce4b 2052      jr      nz,0ce9fh        ;; text
ce4d 75        ld      (hl),l            ;; text
ce4e 62        ld      h,d            ;; text
ce4f 62        ld      h,d            ;; text
ce50 65        ld      h,l            ;; text
ce51 72        ld      (hl),d            ;; text
ce52 95        sub     l            ;; text

ce53 1f        rra                     ;; ?? text control characters to draw box
ce54 07        rlca   
ce55 0e93      ld      c,93h
ce57 1b        dec     de
ce58 99        sbc     a,c
ce59 0d        dec     c
ce5a 0a        ld      a,(bc)
ce5b 0a        ld      a,(bc)
ce5c 00        nop     

;; ====================


And this appears to be the code that loads and runs Burnin' Rubber:

Code Select Expand


;; run Burnin' Rubber

ce5d df        rst     18h            ;; ?? ROM call
ce5e 67        ld      h,a
ce5f cef3      adc     a,0f3h
ce61 01897f    ld      bc,7f89h
ce64 ed49      out     (c),c
ce66 c7        rst     00h
ce67 00        nop     
ce68 c0        ret     nz

ce69 84        add     a,h
ce6a cd6ece    call    0ce6eh
ce6d c9        ret     

ce6e e5        push    hl
ce6f 210600    ld      hl,0006h
ce72 39        add     hl,sp
ce73 fd7506    ld      (iy+06h),l
ce76 fd7407    ld      (iy+07h),h
ce79 e1        pop     hl
ce7a c9        ret     


Haven't got any ideas how this works though - are the RST calls loading the Burnin' Rubber ROMs (spaces 4 to 7 in the cartridge) into memory?

[redbox]

I have repeatedly gone through the Plus AMSDOS ROM and compared it to the classic AMSDOS ROM and I still for the life of me can't see how the menu selection is executed...

It's a normal ROM.  It has RSX extensions.  It has BIOS intialisations.  It has the menu selection.  The firmware doesn't call it.  BASIC doesn't call it.  The programmer used a sh*tty way of going to BASIC instead of Burnin' Rubber (as mentioned above).  IT'S DRIVING ME NUTS.  I need to lie down.

On another note, the OS contains some uber-compact code to check for ROMs on start-up (BASIC calls this as a firmware routine):

Code Select Expand


loop:    ld c,&0f           ;; 16 ROMs
         call kl_init_back  ;; initialise them
         dec c              ;; next ROM down
         jp p,loop          ;; loop if not finished
         ret                ;; else return


So no room there to edit it to check for cartridge ROMs (128 onwards) as the whole OS ROM is packed without any nice space left to patch in a custom routine.

[arnoldemu]

I also have a dissassembly of the CPC+ AMSDOS rom, but it doesn't document the exact mechanism for the menu:

http://www.cpctech.org.uk/docs/plusams.asm

[arnoldemu]

kl_init_back could be patched, so that in effect it ors &80 on?

[redbox]

I also have a dissassembly of the CPC+ AMSDOS rom, but it doesn't document the exact mechanism for the menu:
http://www.cpctech.org.uk/docs/plusams.asm

Oh, now you tell me     It's got a commented explanation of the execution of Burnin' Rubber that I can see, but I still can't quite understand how it works.  So if I want to execute the game, would I just do this (I've highlighted the code to ignore as I think it's the fail-safe if the game doesn't execute):

Code Select Expand


rst     $18 ;; firmware function: "low: far call: rst 3"
defw    &ce67 ;; address of far call datablock

;; IGNORE THIS BIT - FAILSAFE IF BURNIN' RUBBER DOESN'T EXECUTE
;;di ;; disable interrupts
;;ld      bc,$7f89 ;; enable lower rom, set mode 1
;;out     (c),c
;;rst     $00 ;; execute lower rom

;; far-call datablock
ce67:
defw &c000 ;; address to execute
defb &84 ;; rom select address (cartridge block 4)


Also, you too couldn't work out how AMSDOS automatically executes the menu code (at &cdd7)...?

kl_init_back could be patched, so that in effect it ors &80 on?

That's an interesting idea.  I will try and patch it so it does &84 to &87 (top 4 banks of 128kb cartridge) so a cart could have the system and 4 ROMs. 

I'm assuming when the BASIC ROM calls the KL ROM WALK (which searches from positions 16 to 0) it's just looking for external ROMs and not the OS/BASIC/AMSDOS again (as these have already been initialised)...?

[arnoldemu]

Oh, now you tell me     It's got a great explanation of the execution of Burnin' Rubber that I can now use, thanks.

So you too couldn't work out how AMSDOS automatically executes the menu code (at &cdd7)...? 

That's an interesting idea.  I will try and patch it so it does &89 to &9C (top 4 banks of 128kb cartridge) so a cart could have the system and 4 ROMs. 

I'm assuming when the BASIC ROM calls the KL ROM WALK (which searches from positions 16 to 0) it's just looking for external ROMs and not the OS/BASIC/AMSDOS again (as these have already been initialised)...?

I thought I had worked it out, but I don't remember.
Did you look at the os rom to see if it does the calling into the disc rom?

[redbox]

That was a quick reply...!  I have edited my previous post to ask you about the Burnin' Rubber execution... 

I thought I had worked it out, but I don't remember.
Did you look at the os rom to see if it does the calling into the disc rom?

Yes, I did look at the OS but was searching for the menu code execution (&cdd7).  Maybe it's bundled in with another routine, will take another look.

[arnoldemu]

Oh, now you tell me     It's got a commented explanation of the execution of Burnin' Rubber that I can see, but I still can't quite understand how it works.  So if I want to execute the game, would I just do this (I've highlighted the code to ignore as I think it's the fail-safe if the game doesn't execute):

Code Select Expand


rst     $18         ;; firmware function: "low: far call: rst 3"
defw    &ce67         ;; address of far call datablock

;; IGNORE THIS BIT - FAILSAFE IF BURNIN' RUBBER DOESN'T EXECUTE
;;di            ;; disable interrupts
;;ld      bc,$7f89      ;; enable lower rom, set mode 1
;;out     (c),c
;;rst     $00         ;; execute lower rom

;; far-call datablock
ce67:
defw &c000         ;; address to execute
defb &84         ;; rom select address (cartridge block 4)


Also, you too couldn't work out how AMSDOS automatically executes the menu code (at &cdd7)...?

That's an interesting idea.  I will try and patch it so it does &84 to &87 (top 4 banks of 128kb cartridge) so a cart could have the system and 4 ROMs. 

I'm assuming when the BASIC ROM calls the KL ROM WALK (which searches from positions 16 to 0) it's just looking for external ROMs and not the OS/BASIC/AMSDOS again (as these have already been initialised)...?

Your right about burning rubber.
It effectively pages in the burning rubber rom into the range &c000-&ffff (&84) and executes it.

With KL ROM WALK, OS rom will never be seen. This is always located at &0000-&3fff. The rom walk only looks for those roms in the address range &c000-&ffff.
BASIC and AMSDOS will be picked up as it processes them. BASIC will be mapped into all rom slots where there is no other rom, so it knows that it will see this if no rom is paged in.
I think your idea will work, and this *should* activate all the other pages in the rom.

[arnoldemu]

That was a quick reply...!  I have edited my previous post to ask you about the Burnin' Rubber execution... 

Yes, I did look at the OS but was searching for the menu code execution (&cdd7).  Maybe it's bundled in with another routine, will take another look.

from plus os rom:
621 is mc start program

05e5 117906    ld      de,&0679
05e8 2172c0    ld      hl,&c072
05eb 0e07      ld      c,&07
05ed 1832      jr      &0621

Now I need to go back and see if I originally documented this or not and just forgot to upload my stuff..

[redbox]

from plus os rom:
621 is mc start program

You beauty - it worked!!! 

I was making the mistake of searching for &cdd7 where as I should have also looked for &c072 (where there is simply a JP &cdd7). 

I replaced the Plus OS code with the classic OS code:

Code Select Expand


11 77 06    ld      de,&0677    ; this is executed by execution address
21 00 00    ld      hl,&0000    ; this will force MC START PROGRAM to start BASIC
00          nop                 ; no ROM number selection needed
00          nop
18 32       jr      &0621       ; mc start program (is &061f in classic 6128 OS)


Strange that they tagged this onto the end of the RSX function table, maybe the menu choice was originally going to be a RSX.  Or another thing is they might have realised that new CPC users might not know what the | key is (for |GAME) - remember all the "where is the | in |CPM stories" - so they bolted the menu choice on as a last minute thing.  It might even have been Sugar who asked for it...!

Now I will work editing the ROM walking to make use of the cart space...

[Bryce]

Just a note on the menu: If you have a ROMBoard connected with the OS in slot 0 / AMSDOS in slot 7 the menu doesn't appear, even if a cartridge is inserted. I do this most of the time, because the menu has already started getting on my nerves, especially if I forget to press F1 quick enough and Burning rubber starts automatically.

Bryce.

[redbox]

Just a note on the menu: If you have a ROMBoard connected with the OS in slot 0 / AMSDOS in slot 7 the menu doesn't appear, even if a cartridge is inserted. I do this most of the time, because the menu has already started getting on my nerves, especially if I forget to press F1 quick enough and Burning rubber starts automatically.

Yes, it's the AMSDOS ROM that has the menu selection in, but the Plus OS is patched to call this ROM & Menu.  So, if you put an alternate OS in Slot 0 or, for example, ParaDOS in Slot 7 of your ROMBoard, you won't get the menu system.

Alternatively, you could blow the attached ROM to a 27C1001 and put it into a Plus cartridge and you will have the original (v4) 6128 Plus system ROMs with no annoying menu (just type |GAME to play Burnin' Rubber) 

[Bryce]

Thanks, I've downloaded the zip, but I bet it's for a UK keyboard Plus? Mine is (still) french.

Speaking of ParaDOS, I've noticed some errors with ParaDOS on the Plus while using the HxC, I'll investigate further and report back later.

Bryce.

[redbox]

Thanks, I've downloaded the zip, but I bet it's for a UK keyboard Plus? Mine is (still) french.

I have compiled a French version (attached) just for you 

You need to blow the BIN file to the EPROM, the CPR is for testing in WinAPE etc.

[redbox]

Now I will work editing the ROM walking to make use of the cart space...

I have had some success in getting the ROM from cartridge space 4 (&84) to initialise, but of course then all of the firmware would need to be patched for it to work properly, for example KL FIND COMMAND and so on...

But there must be a better way of doing this.  For example, the ROM-RAM and SYMBiFACE II both have additional memory that can be used to map ROMs outside of the 0-15 range.  Does anyone know how they do it and still get the Amstrad OS to work with these higher ROMs?

I see that TFM recently wrote a ROM Manager for the SYMBiFACE II, maybe you know how to do what's above?