---------------------------------------------------------------------- DTVBASIC v0.8 Programmers Reference (c) 2006 Grokk/TheGang ---------------------------------------------------------------------- Current status: 08 Dec. 2006: Beta version, 17 extra commands, Ramdisk SEQ-support is working 12 Nov. 2006: Beta version, 13 extra commands, New banking scheme, multipart 25 Oct. 2006: Beta version, 10 extra commands, Extended dir function+bugfixes 13 Oct. 2006: Beta version, 10 extra commands, Ramdisk load/save is working 4 Sept. 2006: Beta version, 8 extra commands, Ramdisk not working. ---------------------------------------------------------------------- Preface ---------------------------------------------------------------------- When developing using a C64, BASIC has always been a quick way to test how routines are working. So also on the DTV. However, the V2/V3/Hummer versions of the DTV has a whopping 2MB of RAM and 2MB of ROM (flash) of which BASIC knows nothing. The DTVBASIC is my way of ease the write-compile-test cycle on the DTV without the need for a PC connected. The project has developed on a by-need basis, so there is no "master plan" of the project. ---------------------------------------------------------------------- Overview ---------------------------------------------------------------------- DTVBASIC makes use of a basic bank located in the DTV:s high ram memory and mapped in as ROM to the lower memory with reg $D101. It is based on the original basic, which is carefully patched to extend its functionality. In this way, the extra BASIC does not take any extra space at $8000 or at $c000 or even in the RAM area under it. To the DTV it looks like a single bank of 8kB ROM. The following happens when DTVBASIC is installed. 1. The Kernal is copied from its original position at ROM e000 to RAM memory location 1ee000. Basic is copied from its original position at ROM a000 to RAM memory location 1ea000. 2. Extended BASIC core functionality is loaded into RAM memory location 1e8000. 3. Extended BASIC commands is loaded into RAM memory location 1ea000. 4. The ramdisk functionality is loaded into RAM memory location 1e9000. 5. Several I/O vectors in the Kernal copy is patched to allow for RAMDISK features, and the CTRL-check at boot-time is reversed. The basic is patched in several places to allow for extended commands and RAMDISK functions. (See below) 6. Control is transferred to the RAM Basic and Kernal ---------------------------------------------------------------------- Bank concepts ---------------------------------------------------------------------- There are two banking schemes used in DTVBASIC. The first sceme has 32 banks of 64kB memory, and is used by the DMA transfer routine. This is also the scheme used when talking about where the Basic and Kernal is mapped. The second scheme has 128 banks of 16kB and is used by the BANK command and the RAMDISK. To allow for troubles and confusion I call them both banks, life is not easy, has not been, will never be. ---------------------------------------------------------------------- Features ---------------------------------------------------------------------- Hexadecimal notation can be used almost anywhere in basic (except in DATA statements). You can for example POKE$d020,1 or PRINT $801 Generic BASIC commands (run-mode and direct-mode) COLOR , Setup color from the 256-color palette. 0-4 for registers $d020-$d024 0-255 color from palette DMA FROM [,[,]] TO [,] DMA transfer memory number of bytes to transfer (maximum 65535 bytes) adress in memory 0-65535 optional bank 0-31 (default=0) optional 0=ROM 1=RAM (default=1) BANK , Maps 16 kB of hi memory to adress space $4000-$7FFF. After this command is issued, the specified memory bank can be acessed at the position specified. 0-127 16kb bank to map to the area 0=ROM (flash), 1=RAM To restore the original mapping, enter BANK 1,1 NOTE! Several of the DTVBASIC commands will automatically restore the effects of this command, specifically the RAMDISK and the other extended DISK functions (like DIR). It is recommended to use this command immidiately before the read/write of memory and restore the mapping as soon as you are done. NOTE! Mapping hi-mem to positions $4000-$7FFFF will interfere with your basic program in 2 ways: 1. Long BASIC programs will use that area for storing the basic program itself, and will therefore not work. 2. BASIC programs that uses a lot of variables will use that area for storing variables. So use the BANK command only with short BASIC programs with few variables. RAMDISK [,] Creates or extends the ramdisk. The specified memory banks are formatted to be used and recognized as ramdisk. See chapter below for a detailed description of the ramdisk. 0-127 optional 0-127. If specified, all banks in the range will be used RAMDISK CLR Will remove any ramdisk in memory. No warning will be issued! RAMDISK LIST Displays the structure of the ramdisk. A list of all banks used by the ramdisk is displayed with information about: - If the bank is the first (ROOT) bank - If the bank is the last (END) bank - Which bank is the next in the linked list of banks (LINK) - How many sectors that are used/free in each bank DIR Lists directory of the current (last used) device. DIR 2 Lists directory of ramdisk. DIR 1 Lists directory of flashdisk. DIR Lists directory of device ($) DIR , Changes to directory image of a 1541-III unit and lists directory. Device number LOAD"ABC",2 Loads a file from the ramdisk to $801, Wildcards can be used in the filename. SAVE"ABC",2 Saves a program to the ramdisk. The replace directive (@:) can be used. SCRATCH"ABC", Deletes a file from device . Wildcards can be used in the filename. RENAME"NEWNAME=OLDNAME", Renames a file on device . If wildcards are used, the first matching file will be renamed. RAMSAVE"ABC",,, Saves a ram area to device . The command only works with traditional ram ($0000-$FFFF). RAMLOAD"ABC",, Loads a file from device to a specific memory adress. The command only works with traditional ram ($0000-$FFFF). MEMDUMP [] Will display 64 bytes of memory as hex and as PETSCII. is the start adress. If is omitted, the next 64 bytes of memory is displayed. Direct-mode-only commands SWEKEY - Patches Kernal to use MadModders swedish keyboard layout. TAS TMP - Start TurboMacroPro from Style. You have to have TMP loaded for this command to work. The command will search at $8000 to see if TMP is loaded there. If found it will issue a SYS8*4096 command. If not found, the command searches for a jumpback at $140. If found it will issue a SYS320 command. MON - Start DTVBOOT from T.L.R. You have to have DTVBOOT loaded at $18000 for this command to work. RESIDENT - Install DTVBASIC resident at $18000. If you issue this command, you can jump into DTVBASIC at any time by holding down the joystick button while reset:ing your DTV. Be aware that this command will overwrite any other resident program that might be installed at $18000 (for example DTVBOOT). GO64 - This will transfer control to the original KERNAL and BASIC. The command will switch in the original banks and make a reset. Since the original Kernal in the DTV will auto-boot the file "INTRO" from the flash, you might want to be quick to press the ctrl-key after answering Y to the "ARE YOU SURE?" question. ---------------------------------------------------------------------- Ramdisk ---------------------------------------------------------------------- The ramdisk replaces the old RS232 device 2. This will cause problems with software that expects that storage divices has device numbers 8-15 (most software). I will therefore provide a solution for this before the final release. The ramdisk is built of a linked list of 16kB RAM banks. The minimum size for the RAM disk is 16kb (one bank) Ramdisk banks can be placed anywhere from bank 4 and up. However, DTVBASIC uses 2 RAM banks which cannot be used: bank 122 ($7A) = $1ea000 bank 123 ($7B) = $1ee000 The maximum size of the RAM disk is therefore: 122 banks * 16kb = 1952kB Each bank is divided into 64 256-byte-sectors. The first sector in each bank is reserved and contains: - a 4 byte ramdisk identification ("RAMD") - a 4 byte linklist (FLAGS,NEXTBANK,PREVBANK,FIRSTBANK) - Empty space - a 64 byte BAM (exessive use of space) - more empty space. The first sector in the root bank also contains: - 8 bytes indicating opened files. - 8 file handles to the opened files All other sectors are (when used) composed of 2 bytes of linking data (BANK,SECT) to the next sector and a payload of 254 bytes of data. The second sector in the first bank is the directory root. The directory is a series of linked sectors. Every directory entry takes up 32 bytes of data. One directory sector can therefore contain 8 directory entries. A directory entry looks like this LB,LS,TYPE,FB,FS,16 b filename,$0d,BLKLO,BLKHI,SZLO,SZM,SZHI,5 unused bytes is only used in the first directory entry of a sector and is the bank/sector of the next directory sector is the type of file (PRG=0,SEQ=$10 or DEL=1). bank/sector of file data size of the file in blocks size of the file in bytes Directory listing ends when =0 The RAM disk does not use any zero page variables to keep track of start/stop. Instead, the ramdisk commands will scan memory until a ramdisk bank is found, and follow its link to the first bank. Limitations - The RAM disk does not support verifying, and probably never will. Maximum ramdisk free size (formatted). Banks in range 4-127 except 122 and 123 (122 banks). 63 sectors free per bank 254 bytes free per sector minus one directory sector =1951990 ~ 1906 kB, or to speak CBM: "7685 blocks free" ---------------------------------------------------------------------- Changes to the the original BASIC ---------------------------------------------------------------------- The original BASIC has been "patched" in some places to allow for extra commands. A list with the exact changes will be provided later. ---------------------------------------------------------------------- ROM-version of the DTV BASIC ---------------------------------------------------------------------- One of the goals of DTVBASIC is to make a ROM Version of it. A ROM version could be flashed to the DTV and could be invoked with a few POKE:s. When DTVBASIC is in its first release version I will provide a step-by-step guide on how to do it. ---------------------------------------------------------------------- Stand-alone-Ramdisk ---------------------------------------------------------------------- Another request is to have the ramdisk as a stand-alone program. This might be a possibility in the future, but will require some kind of interface for the extra features that the ramdisk gives. Probably solved by traditional command channel-functions ---------------------------------------------------------------------- BASIC tokens ---------------------------------------------------------------------- The extended commands use unused tokens from $d0 and up. This is the same technique that other BASIC extensions use, so programs written with DTVBASIC is not compatible with other BASIC extensions. These are the tokens used by DTVBASIC COLOR $d0 DMA $d1 BANK $d2 (reserved) $d3 FROM $d4 RAMDISK $d5 DIR $d6 SCRATCH $d7 RENAME $d8 RAMSAVE $d9 RAMLOAD $da MEMDUMP $db ---------------------------------------------------------------------- Version history ---------------------------------------------------------------------- v0.8 The ramdisk has been extensivly re-written and supports SEQ-files, which means that Kernal functions OPEN/CLOSE/CHKIN/CHKOUT/CHRIN/CHROUT is working with the ramdisk. The TAS command now works with TurboMacroPro version 1.1 and 1.2. Support for hexadecimal numbers in basic. You can now POKE $d020,$FF. SCRATCH now works with any device The BANK is reduced to only support banking into $4000-$7FFF. Banking into any of the other 3 possible areas from BASIC was not possible anyway, due to the design of the DTV. RENAME-command added RAMSAVE-command added RAMLOAD-command added MEMDUMP-command added V0.7 A completely new banking scheme is used. Instead of two scattered ROM banks, only one ROM bank is used in combination with the segment mapper which switches in functionality as RAM. The advantage is a smaller memory footprint, but the drawback might be increased instability as the code runs in RAM. The code is split up into 3 different parts. There is many reasons for this, but the main advantage is easier development since the sources becomes smaller. There is also lesser risk to accidently introduce bugs into already functional code. RESIDENT - command added MON - command added GO64 command added WARMSTART vector changed to give a message. Some small bugfixes in the ramdisk will increase stability. Directory listings of "normal" drives will have ,8,1 added after the filename. V0.4 Bugfix - files larger than 20 blocks can now be saved. Bugfix - Banks over 96 could not be formatted as a ramdisk. Now the full range between 4-127 can be used again. A warmstart vector re-sets the bank if a warmstart (runstop/restore, brk etc...) was issued when the wrong bank was swapped in. This increases stability. The DIR command is now extended to also list directories of flash disk, traditional disk units (1541,1571, 1581) and the 1541-III. ---------------------------------------------------------------------- Credits ---------------------------------------------------------------------- Thanks to: MadModder for the swedish keyboard layout. T.L.R and David Murray for all the useful technical info. gmoon for helping me during the memorybank chrisis of late October 2006.