Skip to content
/ PDS-Assembly-Dox Public

Some examples of assembling with the prominent DOS cross-assembler from the 80s

0 stars 0 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

themabus/PDS-Assembly-Dox

BranchesTags

Repository files navigation

PDS-Assembly-Dox

This is a quick assembly guide for the 80s/90s source codes written using Programmers Development System (PDS)
running the cross-assembler on DOS emulator without the hardware interface board.

CAUTION!

It appears that on some occasions an error message about insufficient FILES in CONFIG.SYS may appear, when saving the files from PDS editor, resulting in the erasure of the content of those files. So please don't even think about directly feeding it your original sources from unprotected floppies or something silly like that.

Some examples, from easy to more finicky:

CPC Dizzy 3 (https://github.com/Wireframe-Magazine/Wireframe19)

  • compile for amstrad with PDSZ80f.EXE to get AA or with PDSZ80c.EXE on DOSBox-X
    to get serial output ser2.bin
  • unpack it to 0bank0.bin with pds2rom.exe aa
  • use CaPriCe Forever
  • set breakpoint: &0dfb
  • run call &0dfb to activate BP
  • memory editor/dump/import bin
  • unpause debugger and it should execute from set PC

CPC Lop Ears (https://spectrumcomputing.co.uk/forums/viewtopic.php?t=1932)

  • compile with PDSZ80f.EXE to get AA or with PDSZ80c.EXE on DOSBox-X to get serial output ser2.bin
  • unpack it to 0bank0.bin with pds2rom.exe aa
  • trim it with sfk partcopy 0bank0.bin -yes -allfrom 0x300 out.bin
  • use CaPriCe Forever
  • set breakpoint: &2328
  • run call &2328 to activate BP
  • memory editor/dump/import bin
  • set From to &300 before importing
  • unpause debugger and it should execute from set PC

ZX Street Cred Football (https://spectrumcomputing.co.uk/forums/viewtopic.php?t=1932)

  • compile with PDSZ80f.EXE to get AA or with PDSZ80c.EXE on DOSBox-X to get serial output ser2.bin
  • unpack it to 0bank0.bin with pds2rom.exe aa
  • trim it with sfk partcopy 0bank0.bin -yes -allfrom 0x4000 out.bin
  • use ZXSpin
  • Tools/Debugger set breakpoint: #9472 (as 38002 is specified in X0 comments)
  • run randomize usr 38002 to activate BP (T Ctrl+Shift L 38002)
  • File/Load Binary
  • set Start to #4000 before importing
  • unpause debugger and it should execute from set PC

C64 Altered Beast Intro (https://github.com/milkeybabes?tab=repositories)

  • compile x?.tap files with PDS6502f.EXE to get AA or with PDS6502c.EXE on DOSBox-X
    to get serial output ser2.bin
  • unpack it to 0bank0.bin with pds2rom.exe aa
  • prepend rom with 2 bytes and remove last 2: <- C64 emulator quirk
    sfk partcopy 0bank0.bin -yes -fromto 0 2 addr.bin
    copy /b addr.bin +0bank0.bin out.bin
    sfk partcopy out.bin -yes -fromto 0 0x10000 intro.prg
    (so if those 2 bytes happen to be meaningful, fill them from debugger later on)
  • use Z64K
  • Applications/Machine Monitor
    l "intro.prg" 0
    g 9837
  • close Monitor and it should run

C64 Alien 3 (https://github.com/milkeybabes?tab=repositories)

  • compile EFFECTS.PDS with PDS6502f.EXE to get AA or with PDS6502c.EXE on DOSBox-X
    to get serial output ser2.bin
  • process it as Intro above (with 2 extra zero bytes) and you should have effects.prg
  • open 0-7.PDS in PDS and set TAPE_LOADER to 0 and uncomment START_CODE at the end of 7th window
  • try to compile and get an error about a missing gfx file
  • go to SPRITES directory and copy JUMP.SPR to THROW.SPR, TUMBLE.SPR and TURN.SPR
  • copy JUMP.REV to THROW.REV, TUMBLE.REV and TURN.REV
  • now compile it and process output as Altered Beast Intro or EFFECTS.PDS into alien3.prg
  • launch Z64K and fire up Monitor
    l "alien3.prg" 0
    g f300
  • notice assembler instructions dont make sense
    this is because this memory space is mapped to Kernal so we first have to map this region to RAM
    how upsetting, lets cheer ourselves up with some wicked beats
    l "effects.prg" 0
    g 1791
  • close Monitor to launch effects sampler
  • after you've cheered up proper, open Monitor again and g f300; notice it has removed Kernal for us
  • l "alien3.prg" 0
  • execute g f300 again to refresh the instruction window and you should see the familiar loader routine
  • close Monitor and the game should run now

SMS The Fantastic Adventures of Dizzy (https://spectrumcomputing.co.uk/forums/viewtopic.php?t=1932)
this game assembles with PDS/2 for Z80 P2Z80.EXE which was kindly provided in the same archive
as the source code

  • replace all instances of C:\SEGA8BIT\BIGDIZZY\ in FANTSEGA.PRJ with nothing, to get relative paths
  • search for incbin in source files and, like above, replace all C:\SEGA8BIT\BIGDIZZY\ paths with nothing
    this should affect 2 .dat files and 15 .inc files
  • in PAGE2.ROU change D:\UTILS\FLEX\UNFLEX.Z80 -> UNFLEX.Z80
  • copy in UNFLEX.Z80 from the archive
  • comment out PATH string at the top of MACROS.ROU and chabge SEND COMPUTER1 to SEND SERIAL
  • the game should now compile, producing binary output from serial port in your DOSBox-X directory
  • close DOSBox and move this file someplace else; it should be 259842 bytes long
  • now lets create an 64k FF filled file:
    sfk make-zero-file bank 0x10000
    sfk rep bank -yes -binary /00000000/ffffffff/
  • unpack data:
    pds2rom.exe ser1.bin bank >log
  • trim garbage:
    sfk partcopy 0bank64.bin -yes -fromto 0x0000 0x4000 64.bin
    sfk partcopy 0bank65.bin -yes -fromto 0x4000 0x8000 65.bin
    sfk partcopy 0bank66.bin -yes -fromto 0x8000 0xc000 66.bin
    ...
    sfk partcopy 0bank79.bin -yes -fromto 0x8000 0xc000 79.bin
  • join all banks:
    copy /b 64.bin +65.bin +66.bin +67.bin +68.bin +69.bin +70.bin +71.bin +72.bin +73.bin +74.bin +75.bin +76.bin +77.bin +78.bin +79.bin dizzy.sms
  • and finally we shoul add a header:
    sfk -yes setbytes dizzy.sms 0x7ff0 0x544d5220534547410000000000000040
  • this ROM should now work in SMS emulators, such as Emulicious or MEKA

NES Hero Quest (http://shrigley.com/source_code_archive/)

  • compile with PDS6502f.EXE to get A? or with PDS6502c.EXE on DOSBox-X to get serial output ser2.bin
  1. if you saved data from serial port:
  • unpack it to 0bank?.bin with pds2rom.exe ser2.bin
  • trim files with sfk:
    sfk partcopy 0bank0.bin -yes -fromto 0x8000 0xc000 out0.bin
    sfk partcopy 0bank1.bin -yes -fromto 0x8000 0xc000 out1.bin
    ...
    sfk partcopy 0bank6.bin -yes -allfrom 0x8000 out6.bin
  • join all files
    copy /b out0.bin +out1.bin +out2.bin +out3.bin +out4.bin +out5.bin +out6.bin tmp.bin
  1. if you saved to file:
  • unpack and process this data like so
    pds2rom.exe aa
    move 0bank0.bin tmp0.bin
    sfk partcopy tmp0.bin -yes -fromto 0x8000 0xc000 out0.bin
    pds2rom.exe ab
    move 0bank0.bin tmp1.bin
    sfk partcopy tmp1.bin -yes -fromto 0x8000 0xc000 out1.bin
    ...
    pds2rom.exe ah
    move 0bank0.bin tmp7.bin
    sfk partcopy tmp7.bin -yes -allfrom 0xc000 out7.bin
  • join all files
    copy /b out0.bin +out1.bin +out2.bin +out3.bin +out4.bin +out5.bin +out6.bin +out7.bin tmp.bin
  1. continue here in both cases
  • prepend tmp.bin with a 16 byte header using an HEX editor or with sfk setbytes
    4E 45 53 1A 08 00 20 00-00 00 00 00 00 00 00 00
    sfk -yes make-random-file header 16
    sfk -yes setbytes header 0 0x4e45531a080020000000000000000000
    copy /b header +tmp.bin hq.nes
  • now you can open this ROM in any NES emulator

NES NES Tank Game (http://www.iancgbell.clara.net/nestank/)

UPDATE: on the 1st day of 2025 Hidden Place community shared NES PDS2 along with The Lion King source code,
so now assembling this game with it is as easy as filling the .PRJ project file with the file sequence below
and adding the 16 byte ROM header to the output TANK.ROM file
I'm keeping the old conversion guide below for the reference

this game was produced on 6502 PDS/2 and since it is currently MIA we'll have to sqeeze it into an PDS project

  • rename following files:
    move BZLINE.PDS 1.PDS
    move BZLOGS.PDS 2.PDS
    move BZMATH.PDS 3.PDS
    move BZDVLP.PDS 4.PDS
    move BZNMIR.PDS 5.PDS
    move BZNTRA.PDS 6.PDS
    move BZLAST.PDS 7.PDS
    copy BZDFNS.PDS +BZFRST.PDS +BZFRGR.PDS 0.PDS
  • now let's create a FF pattern filled 64kb overlay file
    sfk make-zero-file bank 0x10000
    sfk rep bank -yes -binary /00000000/ffffffff/
  • in 0.PDS set ROMCODE to 1, TESTSTUFF to 0 and replace SEND ROMFILE,TANK.ROM,128 with
    SEND COMPUTER1
  • in 0.PDS, where BZFRST.PDS would end (after noobj equ (*-OBJDEF)/16) add
     include BZMACR.PDS
  • compile the game and then process two output files like so
    pds2rom.exe aa bank
    move 0bank0.bin tmp0.bin
    sfk partcopy tmp0.bin -yes -fromto 0x8000 0x10000 out0.bin
    sfk partcopy tmp0.bin -yes -fromto 0 0x8000 out1.bin
    pds2rom.exe ab bank
    move 0bank0.bin tmp1.bin
    sfk -yes make-random-file header 16
    sfk -yes setbytes header 0 0x4e45531a080010000000000000000000
    copy /b header +out0.bin +out1.bin +tmp1.bin tank.nes
  • you should now have a ROM image matching to the one Ian Bell shared on his website

NES Elite (http://www.elitehomepage.org/archive/index.htm)

UPDATE: on the 1st day of 2025 Hidden Place community shared NES PDS2 along with The Lion King source code,
so now assembling this game with it is as easy as correcting paths in NELITE.PRJ, ELITEA1.PDS, NELITEJ.PDS, NELITEZ.PDS
and adding the 16 byte ROM header to the output ELTPAL52.ROM file
I'm keeping the old conversion guide below for the reference

same as with the NES Tank Game this is a PDS/2 project so we should take care to downconvert it to PDS
PDS can load up to 8 files of a limited size; loops can not be used in include files; includes can not be nested

  • first move all .PDS files from both subdirectories to the outer one, where NELITE.PRJ is
  • go through all the .PDS files and correct incbin file references to relative ones e.g.
    CFAC6OBJ.DAT should be NIEL1\CFAC6OBJ.DAT
    C:\PDS\JOEL1\NTSCTOK.dat -> JOEL1\NTSCTOK.dat
    \PDS\JOEL1\WORDSD.DAT -> JOEL1\WORDSD.DAT
    they are in 8 files in total and all the references from each file are to one of subdirectories, i.e. paths dont mix
  • examine NELITE.PRJ and note the file order, we will try to replicate it

  • rename NELITE0.PDS to 0.PDS: move NELITE0.PDS 0.PDS
  • in 0.PDS delete 200something spaces at the end of line 228 (pic2bank EQU 4+STBANK) & line 230
  • in 0.PDS change both SEND ROMFILE lines to SEND COMPUTER1
  • at the end of 0.PDS add the following includes
     include ELITE1.PDS
     include NELITE2.PDS
     include ELITE3.PDS
     include ELITEG1.PDS
     include NELITEG2.PDS

  • move ELITEA1.PDS 1.PDS

  • go to the line 2137 in NELITEA3.PDS and cut everything above it. save
  • paste your clipboard in a new file and save it as 2.PDS, so fudcl2 should be the last little block in it
  • add the following includes at the end of 2.PDS:
     include NELITEA3.PDS
     include ELITEA4.PDS
     include NELITES.PDS
    so we essentially separated NELITEA3.PDS into two parts to reduce file size and bring loops out of include

  • go to the line 1929 in NELITES2.PDS and cut everything above it. save
  • paste your clipboard in a new file and save it as 3.PDS; it should conclude with a slmess5I text block
  • add the following includes at the end of it:
     include NELITES2.PDS
     include ELITEB.PDS
     include ELITEC.PDS
     include ELITED.PDS
     include ELITEE.PDS
     include ELITEF.PDS
     include ELITEH.PDS
  • move ELITEI.PDS 4.PDS

the unfortunate thing with NELITEJ.PDS is that it exceeds the size limit and has loops throughout it
so we'll really have to carve this one up to pieces

  • create a new 5.PDS file and add in it
     include NELITEJ1.PDS
  • cut everything above the line 1188 from NELITEJ.PDS and paste it into a new NELITEJ1.PDS file
  • cut everything above the line 720 from NELITEJ.PDS and paste it into 5.PDS below include
    this block should start with traL1 and conclude with LOOP
  • at the end of 5.PDS add
     include NELITEJ2.PDS
  • cut everything starting (so going down this time) with the sequence label on the line 1226 from NELITEJ.PDS
    and paste it at the end of 5.PDS
  • rename NELITEJ.PDS to NELITEJ2.PDS; it should start with GINF TXA and conclude with RTS instruction
  • move NELITEK.PDS 6.PDS
  • add these 3 includes at the end of it:
     include NELITEL1.PDS
     include ELITEL2.PDS
     include ELITEM.PDS
  • move NELITEZ.PDS 7.PDS

    if you'd try to compile now, PDS will complain about a syntax error in NELITEL1.PDS
    we'll have to modify some macros to compensate for the missing bank reference functionality
    of the older program version we're using
  • find and replace all 6 instances of #|@1 with #@2
  • also in NELITEL1.PDS replace #|TT66 with #0 and #|LL145 with #1
  • now we should supply a 2nd parameter to every instance of 1 of 4 SMARTJMP macros we just modified
    the first one is on the line 452, add ,6 at the end of it
  • the next one is on the line 463, add ,6 at the end of it
  • add ,6 to the end of line 465 and 474
  • continue searching for SMARTJMP and adding values 5,4,4,3,6,1,3,1,6,1,1,1,3,3,4,6,6,4,6,0,0,3
    until youll come to a commented out SENDPALLETE SMARTJMP SENDPALLETEtrue line; let's ignore this one
  • continue down adding: 3,3,3,6,3,6,6,3,3,6,0,5,5 until GETPWRFACE SMARTJMP3 GETPWRFACEtrue
    which should be ignored
  • add seven more parameters 4,4,6,6,0,6,6 and ignore commented out NOISE SMARTJMP3 NOISEtrue
  • supply two more parameters 6,6 for macros and ignore BOXINPUT SMARTJMP2 BOXINPUTtrue
    excluded with IF directive
  • continue adding from GTNME 6,6,6,6,0,2,2,2,3,3,3,3,3,3,3,3,3,0,6,0,1,2,2,2,2,0,0,1,3,1,0 up until ENDTMODEsmart
    take care to add the parameter before the comment on the line 631
  • the game should now compile, producing 8 output files
  • like with NES Tank, create a FF pattern filled 64kb overlay file
    sfk make-zero-file bank 0x10000
    sfk rep bank -yes -binary /00000000/ffffffff/
  • unpack all the binaries
    pds2rom.exe aa bank
    move 0bank0.bin tmp0.bin
    ...
    pds2rom.exe ah bank
    move 0bank0.bin tmp7.bin
  • remove the garbage
    sfk partcopy tmp0.bin -yes -fromto 0x8000 0xc000 out0.bin
    sfk partcopy tmp1.bin -yes -fromto 0x8000 0xc000 out1.bin
    ...
    sfk partcopy tmp7.bin -yes -fromto 0xc000 0x10000 out7.bin
  • don't forget the header
    sfk -yes make-random-file header 16 sfk -yes setbytes header 0 0x4e45531a080012000000000000000000
  • and finally we join all the banks to produce a working ROM image
    copy /b header +out6.bin +out1.bin +out2.bin +out3.bin +out0.bin +out4.bin +out5.bin +out7.bin elite.nes
  • you can pat yourself on the back now for hacking the original NES Elite source code to a working state

Oh No! More PDS:


  • PDS6502.EXE was kindly provided by CSDb community
  • sfk is Swiss File Knife http://stahlworks.com/dev/swiss-file-knife.html
  • PDS has a built in SEND MSDOS,file.ext command for output to file
    but it has a problem with multi bank output overwriting itself
    to amend this I provided modified f exe versions
    it is better to not specify this MSDOS output with those hacked versions
    but just send to either COMPUTER1/2 or SERIAL and everything should go to file
  • older PDSZ80 projects appear to compile well with P2Z80
  • PDS2 has additional SEND ROMFILE,file.ext,128 & SEND ROM commands discussed here:
    https://worldofspectrum.org/forums/discussion/9588/
  • if you have other versions of PDS, particularly 6502 PDS v1.26, PDS/2 for Z80 v2.72 / 6502 v2.73 (or above)
    please upload them on archive.org or github or some other public place

About

Some examples of assembling with the prominent DOS cross-assembler from the 80s

Topics

amstrad-cpc nintendo nes z80 c64 zx-spectrum famicom 6502 sega-master-system 6502-assembly z80-assembly z80-asm

Resources

Readme
Activity

Stars

0 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages