TED v2 Programming Notes

[elmer]

2016-11-30 Modified this message to be a "sticky" for the all sorts of PCE & PC-FX tools and information.
2016-12-23 Updated the version of HuC.
2017-05-15 Updated the version of HuC, fix links to Charles MacDonald's docs.

******************************************************************************
******************************************************************************

Here are some links to programming information for the PC Engine.

Charles MacDonald's PC Engine Hardware Notes
http://dreamjam.co.uk/emuviews/txt/pcetech.txt

Charles MacDonald's SuperGrafx Hardware Notes
http://dreamjam.co.uk/emuviews/txt/sgxtech.txt

Charles MacDonald's PC Engine Hardware Notes (original but dead link)
http://cgfm2.emuviews.com/txt/pcetech.txt

Charles MacDonald's SuperGrafx Hardware Notes (original but dead link)
http://cgfm2.emuviews.com/txt/sgxtech.txt

Tomaitheous (Bonknuts) Downloads and Blog
https://pcedev.wordpress.com/downloads-and-links/

Archaic Pixels HuC & PCE documentation
http://www.archaicpixels.com/Main_Page

The Old Rover's HuC Tutorials
http://obeybrew.com/tutorials.html

******************************************************************************
******************************************************************************

Here's my fork of Uli's new HuC, with a bunch of bug fixes and improvements.

The new fork of HuC
http://www.pcenginefx.com/forums/index.php?topic=21350.0

Latest HuC build ...
http://www.pcenginefx.com/forums/index.php?topic=21350.msg487200#msg487200

Anyone that's interested in building the tools can find the source at https://github.com/jbrandwood/huc


******************************************************************************
******************************************************************************

After some experimentation, I can't really recommend CC65 on the PCE at this time, but here's a conversation about it.

CC65 and the PCE
http://www.pcenginefx.com/forums/index.php?topic=18654.0


******************************************************************************
******************************************************************************

Here's my customized PCE/PCFX/VB version of the Mednafen emulator.

Mednafen General Documentation
http://mednafen.fobby.net/documentation/

Mednafen Debugger Documentation
http://mednafen.fobby.net/documentation/debugger.html

You may wish to edit the mednafen-09x.cfg configuration file to change the following settings ...

Code: [Select]

;Automatically go into the debugger's step mode after a game is loaded.
debugger.autostepmode 1

;Force SuperGrafx emulation.
pce.forcesgx 1

;Treat the fast-forward button as a toggle.
fftoggle 1

I've put up yet-another new Windows build of Mednafen (with my changes) for anyone that wants it ...

https://www.dropbox.com/s/6rpkviyhgihw4gt/mednafen-0.9.38.7-x86-elmer-2.zip?dl=1

Just to remind any newcomers to this thread, the modifications are in Mednafen's PCE and PC-FX debugger displays in order to make them a bit more pleasant to look at, and more readable.

This is still a 32-bit version that only supports the PCE and PC-FX.

New features are ...

    PCE now has 480KB of SCD RAM (banks $44-$7F), plus the 2MB ACD RAM (banks $40-$43).
    PC-FX now has 8MB RAM.

    The extra RAM can be useful during homebrew development as a place to store debugging-info.

    It might also be useful for someone that needs the extra memory for a translation.

    N.B. This is a 32-bit build, but 64-bit Windows builds are now working if someone wants to build it from source.

The patch files and a build script are available at ...

https://www.dropbox.com/s/i3mor256dhrddef/build-msys2-mednafen-0.9.38.7-x86-elmer-2.zip?dl=1


******************************************************************************
******************************************************************************



I've created a patch for the US Turbo Grafx Super System Card so that it will safely run on the Turbo Everdrive 2.

As a by-product, this also allows the TED2 to act as a replacement for the crazily-expensive US Super System Card.

It also gives 512KB of RAM out-of-the-box for translations/homebrew.

Well ... actually it gives 768KB if you really need it, or even a full 1MB if you want to write a program that overwrites the entire System Card image, but I believe that 512KB should be enough for most people.

The new System Card image has a header so that it can be detected, and it has backup copies of the first-and-last 16 bytes of the System Card so that they can be restored if a programmer wants to enable/use any of the other TED2 hardware that's on the card.

The Street Fighter II mapper is NOT enabled, because there are some programming "gotchas" when using it, and so it was safer to disable it "by default".

To use the patch, just apply the xdelta patch to a US Super System Card image and then copy the newly patched image to your TED2's SD card.

You should see the old System Card version number replace with "TED2" and the new patch version number.


Current Patch Version 3.01 - Initial version

Patch file for USA System Card 3.0 (in xdelta3 format) ...

https://www.dropbox.com/s/zcz384fj47xu84u/TED2%20System%20Card%203.01%20USA.xdelta?dl=1

Patch file for JPN System Card 3.0 (in xdelta3 format) ...

https://www.dropbox.com/s/nuctz90ra9aoo3k/TED2%20System%20Card%203.01%20JPN.xdelta?dl=1

An xdelta3 patching utility from romhacking.net that is know to work and be easy to use ...

http://www.romhacking.net/utilities/704/

Source code file (for pceas assembler) ...

https://www.dropbox.com/s/6ufsomh9z683xwb/syscard3-ted2.asm?dl=1

[elmer]

; ***************************************************************************
;
; Turbo Everdrive V2 Programming Notes (2015-11-26)
;
; ***************************************************************************
;
; The TED v2 contains 4MB of RAM, which it maps into the PCE's 1MB of HuCard
; address space (banks 0-127).
;
; The TED v2 maps either RAM or its FPGA into bank 0 of HuCard address space.
;
; When the TED is reset, TED_REG_CFG is set to 0 and the FPGA is mapped
; into bank 0, which the CPU reset maps into $E000-$FFFF ... and so the
; TED boots into it's firmware using the normal reset vector contained
; in the FPGA firmware ROM.
;
; In order to read/write the TED's registers you've got to map out the
; entire bank 0 of HuCard address space ... which means that you can't
; do it if your code is located in HuCard RAM bank 0, and you usually
; can't do it with interrupts enabled, either.
;
; The TED v1 only mapped 256 bytes of registers into HuCard address space,
; but the TED v2 maps the entire 8KB (you can read the TED boot code).
;
; The TED's registers are normally left "locked" to prevent problems.
;
; In order to make an changes to the registers, you must first unlock
; them by writing $A5 to TED_REG_KEY1 and $56 to TED_REG_KEY2.
;
; The registers can then be "locked" again when you're finished by
; setting a bit in the TED_REG_CFG register.
;
; It is technically possible to leave them "writable" while the RAM bank
; is selected ... but I can't think of a time that this would actually
; be useful.
;


; ***************************************************************************
;
; TED_REG_CFG Bit Settings - (N.B. The register is read-write)
;
;   Bit 0 : cfg_regs_oe_off : Bank 0 mapping (0=FPGA, 1=RAM)
;   Bit 1 : cfg_regs_we_off : FPGA Registers (0=access, 1=locked)
;   Bit 2 : cfg_usb_boot    : unknown (leave zero)
;   Bit 3 : cfg_skip_eep    : Normally set by KRIKzz : unknown (set to 1)
;   Bit 4 : cfg_ram_we_off  : RAM Read-Only? (0=writable, 1=read-only)
;   Bit 5 :                 : SF2 2MB mapper (0=disabled, 1=enabled) Only $1ff0-$1ff3.
;   Bit 6 :                 : unknown (leave zero)
;   Bit 7 :                 : unknown (leave zero)
;


; ***************************************************************************
;
; TED_REG_STATE Bit Settings - (N.B. The register is read-only)
;
;   Bit 0 : st_spi          :
;   Bit 1 :                 : unused (leave zero)
;   Bit 2 : st_usb_wr       :
;   Bit 3 : st_usb_rd       : unknown (leave zero)
;   Bit 4 :                 : unused (leave zero)
;   Bit 5 :                 : unused (leave zero)
;   Bit 6 :                 : unused (leave zero)
;   Bit 7 :                 : unused (leave zero)
;

TED_STE_SPI      =      0
TED_STE_USB_WR   =      2
TED_STE_USB_RD   =      3


; ***************************************************************************
;
; TED1_REG_SPI_CFG Bit Settings - (N.B. The register is read-write)
; TED2_REG_SPI_CFG Bit Settings - (N.B. The register is read-write)
;

TED_SPI_SS       =      0
TED_SPI_SPEED    =      1
TED_SPI_AREAD    =      2


; ***************************************************************************
;
; TED_REG_MAP Bit Settings - (N.B. The register is write-only)
;
;   Bit 0  : unknown (leave zero, else hangs)
;   Bit 1  : unknown (leave zero, else hangs)
;   Bit 2  : Map RAM (leave one,  else hangs)
;   Bit 3  : unknown (leave zero, else ignored)
;   Bit 4  : Top 512KB bank bit 0
;   Bit 5  : Top 512KB bank bit 1
;   Bit 6  : Top 512KB bank bit 2
;   Bit 7  : unknown (leave zero, else ignored)
;
;   The 4MB RAM in the TED2 is split into 8x512KB banks ...
;
;   Bank 0 : Used as Top 512KB : Used for SF2 mapper $1FF0
;   Bank 1 :                   : Used for SF2 mapper $1FF1
;   Bank 2 :                   : Used for SF2 mapper $1FF2
;   Bank 3 :                   : Used for SF2 mapper $1FF3
;   Bank 4 : Same as Low 512KB
;   Bank 5 :
;   Bank 6 :
;   Bank 7 :
;
;   !!! WARNING !!!
;
;   Writing to the SF2 mapper registers only changes the bottom 2 bits
;   of the 512KB bank number, so you should set the mapper to bank 0
;   before enabling/using the SF2 mapper, or you'll get weird results.
;

TED_MAP_BANK0    =      $04
TED_MAP_BANK1    =      $14
TED_MAP_BANK2    =      $24
TED_MAP_BANK3    =      $34
TED_MAP_BANK4    =      $44
TED_MAP_BANK5    =      $54
TED_MAP_BANK6    =      $64
TED_MAP_BANK7    =      $74


; ***************************************************************************
;
; When TED is mapped into CPU space at $e000-$ffff.

TED_BASE_ADDR   =       $E000    ; SPI registers base address

;
; TED registers that are the same for TED v1 and TED v2.
;

TED_REG_SPI      =      0
TED_REG_SPI2     =      1
TED_REG_FIFO     =      3
TED_REG_STATE    =      4
TED_REG_KEY1     =      5
TED_REG_CFG      =      6
TED_REG_MAP      =      7
TED_REG_KEY2     =      10

;
; TED v1 (From KRIKzz's edio.c sample code)
;

TED1_REG_SPI_CFG =      8
TED1_REG_VERSION =      9

;
; TED v2 (From KRIKzz's bios.s source code)
;

TED2_REG_SPI_CFG =      2
TED2_REG_VERSION =      8
TED2_REG_I2C     =      9


; ***************************************************************************
;
; Example macros in CA65 format.
;
; N.B. CA65 uses the "a:" prefix to force absolute (16-bit) addressing.
;
;      Without that, CA65 will output a zero-page instruction if we set
;      TED_BASE_ADDR to $0000.
;

        ; This works on both TED1 and TED2.
        ;
        ; N.B. The 2nd write is only needed on the TED1.

        .macro  TED_UNLOCK
                lda     #$A5
                sta     a:TED_BASE_ADDR + TED_REG_KEY1
                lda     #$56
                sta     a:TED_BASE_ADDR + TED_REG_KEY2
        .endmacro

        ; This works on both TED1 and TED2.

        .macro  TED_SET_CFG_FPGA
                TED_UNLOCK
                sei
                stz     a:TED_BASE_ADDR + TED_REG_CFG
        .endmacro

        ;
        ; TED2-only macros.
        ;

        .macro  TED2_SET_CFG_1MB_RAM
                lda     #%00001011
                sta     a:TED_BASE_ADDR + TED_REG_CFG
                cli
        .endmacro

        .macro  TED2_SET_CFG_SF2_RAM
                lda     #%00101011
                sta     a:TED_BASE_ADDR + TED_REG_CFG
                cli
        .endmacro

        .macro  TED2_SET_CFG_1MB_ROM
                lda     #%00011011
                sta     a:TED_BASE_ADDR + TED_REG_CFG
                cli
        .endmacro

        .macro  TED2_SET_CFG_SF2_ROM
                lda     #%00111011
                sta     a:TED_BASE_ADDR + TED_REG_CFG
                cli
        .endmacro

        ;
        ; These USB macros should work on both TED1 and TED2.
        ;

        .macro  TED_USB_RD_TEST
                tst     #(1 << TED_STE_USB_RD), a:TED_BASE_ADDR + TED_REG_STATE
        .endmacro

        .macro  TED_USB_WR_TEST
                tst     #(1 << TED_STE_USB_WR), a:TED_BASE_ADDR + TED_REG_STATE
        .endmacro

        .macro  TED_USB_RD_WAIT
                .local  usb_rd_wait
usb_rd_wait:    TED_USB_RD_TEST
                beq     usb_rd_wait
        .endmacro

        .macro  TED_USB_WR_WAIT
                .local  usb_wr_wait
usb_wr_wait:    TED_USB_WR_TEST
                beq     usb_wr_wait
        .endmacro

        .macro  TED_USB_RD_BYTE
                USB_RD_WAIT
                lda     a:TED_BASE_ADDR + TED_REG_FIFO
        .endmacro

        .macro  TED_USB_WR_BYTE
                USB_WR_WAIT
                sta     a:TED_BASE_ADDR + TED_REG_FIFO
        .endmacro

[elmer]

Updated the header file in the first post.

Looks like KRIKzz moved some of the registers around in the TED v2 which is a bit of a pain.

I think that the SD card registers are now correct ... it seems that I can initialize the SD card and detect my 8GB SDHC card correctly. But I could be wrong.

[elmer]

I'm double-posting this because it's pretty important!

This follows on from investigations into when & how the Duo/Duo-R/SuperCDROM unlock the built-in SCD RAM chip.

http://www.pcenginefx.com/forums/index.php?topic=20009.msg433149#msg433149

But I'd like to see if there's a way to disable the SuperCD RAM after it's been enabled.

I burned a small test program onto CD and tried a few combinations of writes to $18c0 (the SCD RAM unlock register) to see what would happen.

The program starts with SCD RAM unlocked by the System Card, and I did tests by writing to bank $7F and displaying the memory to see if the data was written OK, or even visible at all.

Write $aa $55 to register ... no effect, RAM still visible and writes enabled.
Write $00 $00 to register ... no effect, RAM still visible and writes enabled.
Write $55 $aa to register ... no effect, RAM still visible and writes enabled.
Write $a0 $50 to register ... no effect, RAM still visible and writes enabled.

So, at this point I'm reasonably confident that we're not going to be able to re-lock/hide the SCD RAM once the System Card 3 BIOS has unlocked it.

I've tested the "unlock" on the TED v2 with a System Card 3 image, followed by a "hard-reset", followed by a System Card 2 image ... and the SCD RAM is still unlocked.

So I think that it's going to require a console power-off to lock it again.

***************

I've also tested the how the TED v2 handles loading a System Card 3 image.

It switches itself into read-only mode ... but it still seems to be mapped into the entire bank $00-$7F region.

Unless it's doing some non-obvious bank mapping that I'm not aware of, this is a VERY-BAD-THING™.

!!! IMPORTANT !!!

It means that TED v2 owners really need to run a patched System Card 3 image if they're going to use it to run CD games on a Duo/Duo-R/SuperCDROM.

[elmer]

I've written a patch for the US Super System Card 3 to allow it to run safely on the TED2.

It also gives us 512KB RAM for translations/homebrew to use.

The current version of the patch is put in the 2nd message in this thread, and I'll update that message if/when there are new versions.

[ClodBuster]

Bloody good work!

512KB should be enough for most people.

This made me chuckle.

[Bonknuts]

Woot!

[elmer]

Bloody good work!

512KB should be enough for most people.

This made me chuckle.

Haha, yep, I should have said 640KB! 

Woot!

The next thing is ... "what are we going to do with the extra memory"?

I think that it might be a good idea for homebrew programmers to limit themselves to 512KB, because that would allow new homebrew to run on any of the recent cards, or TheOldMan's ROM/RAM card when they get made.

Otherwise you'd be limiting yourself to TED2 and the CD-Stupid-Card (or the 1MB-RAM card if they ever get made).

We can easily add extra utility functions (like Chris Covell's PCEmon) into the 2nd 256KB region.

I've allocated 4 bytes in the header region to use to signal the availability of any new functionality to programs ... now it just needs someone to want to actually put in that new functionality.

**************

Anyway ... if people actually try this on their consoles, could they please report the results here?

I'd like to make sure that the US Super System Card functions work properly on all the different various PCE console versions.

[elmer]

Updated the source code to work with both the Japanese and the USA System Card 3.0 images.

Added an xdelta patch for the Japanese PC Engine System Card 3.0.

Renamed the USA System Card 3.0 xdelta patch to keep the naming consistent and distinct.

Updated the 2nd post in the thread with the new files.

[Bonknuts]

The next thing is ... "what are we going to do with the extra memory"?

Hmm...

 I think the first thing I will do is put Megaman 2 on CD and hack in a CD audio play routine. I didn't have the ram for it before, but now I do.

 Though technically, I can also make a custom system card rom + game, and the gamer would only have to put in an audio CD/R for the music.


 So, there's supposedly 4megabytes of ram.. but how does one access it? If the SF2 mapper is unchanged, then only 2megabytes are addressable via bank switching (disregarding the initial lower 512k).

[elmer]

I think the first thing I will do is put Megaman 2 on CD and hack in a CD audio play routine. I didn't have the ram for it before, but now I do.

 Though technically, I can also make a custom system card rom + game, and the gamer would only have to put in an audio CD/R for the music.

That would be cool to see! 

The TED2-with-USB-option really is an absolute pleasure to work with.

KRIKzz provides a small program that you run on your PC to quickly upload/run a cartridge image. That makes testing stuff really simple.

The only "gotcha" is that your cartridge is run as RAM, wheras it will be run as ROM (write-protected) when it is booted off the TED2's SD card.

It's a good idea to leave the first 16-bytes of any cartridge reserved/blank so that you can map in the TED2 hardware without overwriting any of your code/data.

So, there's supposedly 4megabytes of ram.. but how does one access it? If the SF2 mapper is unchanged, then only 2megabytes are addressable via bank switching (disregarding the initial lower 512k).

The "SF2-enable" configuration bit that I've found only seems to enable the 2MB of bank-switched memory (by writing to $1ff0-$1ff3).

The obvious way to extend that out to the entire 4MB of TED2 memory would just be to extend that scheme out to $1ff4-$1ff6.

Unfortunately, that doesn't seem to work with the "SF2-enable" bit, or with any other bit combination that I've tried.

If you can figure out how to get access to the upper 1.5MB, that would be great!

Please note that something "weird" seems to happen when you set the "SF2-enable" bit.

It looks like writing to $7f:$1fff increments/changes which 512KB bank is mapped into the bank-switched region.

I can just-about-imagine KRIKzz putting this in the hardware to make it easier to just write the Street Fighter II HuCard image directly into the TED2's RAM without worrying about setting the bank number, but it's a bit annoying.

It's why I left the SF2 mapper disabled in the System Card patch ... because it could cause havok to a game that doesn't expect that to happen.

[ParanoiaDragon]

The next thing is ... "what are we going to do with the extra memory"?

Hmm...

 I think the first thing I will do is put Megaman 2 on CD and hack in a CD audio play routine. I didn't have the ram for it before, but now I do.

 Though technically, I can also make a custom system card rom + game, and the gamer would only have to put in an audio CD/R for the music.


 So, there's supposedly 4megabytes of ram.. but how does one access it? If the SF2 mapper is unchanged, then only 2megabytes are addressable via bank switching (disregarding the initial lower 512k).

If you do, I guess I'll have to definitely put MM2 on my list of soundtracks to work on, though, I'd still like to work on Jackal first.  For MM2, since songs seem to generally be longer then ones in MM!(unless it's my imagination), I suspect they won't require as much filler material, so it's "possible" that the songs won't take as long in general to compose.  Still, it could be a couple years before the soundtrack is done, which is fine by me, it's something I'd love to do, no matter how long it takes!

[Bonknuts]

Hmm. I guess I should add support for CD audio for both then and put them out. I think the only thing to fix in the Jackal nes2pce rom, mainly, was the last boss scroll issue (split screen). I can't remember if I added 2nd player option to the game or not. I thought I did. I'll have to recheck. Jackal on the PCE is actually harder than the NES one, simply because the slowdown is gone. I thought about adding an easy mode option, but that's off topic to this thread. All of this is.

[ParanoiaDragon]

Hmm. I guess I should add support for CD audio for both then and put them out. I think the only thing to fix in the Jackal nes2pce rom, mainly, was the last boss scroll issue (split screen). I can't remember if I added 2nd player option to the game or not. I thought I did. I'll have to recheck. Jackal on the PCE is actually harder than the NES one, simply because the slowdown is gone. I thought about adding an easy mode option, but that's off topic to this thread. All of this is.

Gah, I don't mean to derail the thread, but I totally thought that cd audio support was already in Jackal!  Ok, back to the thread, nothing to see here!

[elmer]

Updated 1st post with the latest header/macros.

KRIKzz posted the TED2 firmware bank 0 on his forum, and that's helped give clues for some of the missing information.

In particular, we can now access the full 4MB RAM on the TED2 without using the "Street Fighter 2" mapper registers.

In fact ... because of the strange behavior with writes to the banks when using the "Street Fighter 2" mapper, I'd suggest just ignoring it and using the TED_REG_MAP register instead.

I've added macros for accessing the the USB port.

The SD Card is still a PITA, and needs a lot more work before it's cracked.

There's a newly documented bit in the CFG register ... but I have no idea what it does.