DTVBASIC v0.9 Programmers Reference

(c) 2008 Grokk/TheGang

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 $01ee000. 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 and $1e4000.
4. The ramdisk functionality is loaded into RAM memory location $1e9000.
5. The LOAD/SAVE 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 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

Start and stop addresses are now displayed during load and save.

Generic BASIC commands (run-mode and direct-mode)

COLOR <reg>,<col>

Setup color from the 256-color palette.
<reg> 0-4 for registers $d020-$d024
<col> 0-255 color from palette

CHARTAB

Displays a PETSCII table.

DIR

Lists directory of current (last used) device.

DIR 2

Lists directory of ramdisk.

DIR 1

Lists directory of flashdisk.

DIR <n>

Lists directory of device <n> ($)

DIR <n>,<i>

Changes to directory image <i> of a 1541-III unit and lists directory.
<n> Device number

DMA <nr> FROM <adr>[,<bank>[,<rom/ram>]] TO <adr>[,<bank>]

DMA transfer memory
<nr> number of bytes to transfer (maximum 65535 bytes)
<adr> adress in memory 0-65535
<bank> optional bank 0-31 (default=0)
<ram/rom> optional 0=ROM 1=RAM (default)

HELP

Displays the built-in helpfile for DTVBASIC.

LOAD"ABC",2[,1]

Loads a file from the ramdisk. Wildcards can be used in the filename.

MEMDUMP [<adr>]

Displays 64 bytes of memory as hex and as PETSCII.
<adr> is the start adress. If <adr> is omitted, the next 64 bytes of memory is displayed.

RAMDISK <startbank>[,<endbank>]

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.
<startbank> 0-127
<endbank> 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 UNIT <nr>

Will change the unit number of the ramdisk. This is useful
if your program only can save to unit 8 or 9.
To change it back, give the command RAMDISK UNIT 2

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

RENAME"NEWNAME=OLDNAME",<n>

Renames a file on device <n>. If wildcards are used, the first
matching file will be renamed.

RAMSAVE"ABC",<n>,<startadr>,<endadr>

Saves a ram area to device <n>. The command only works with
traditional ram ($0000-$FFFF).

RAMLOAD"ABC",<n>,<startadr>

Loads a file from device <n> to a specific memory adress.
The command only works with traditional ram ($0000-$FFFF).

SAVE"ABC",2

Saves a program to the ramdisk. The replace directive (@:)
can be used.

SCRATCH"ABC",<n>

Deletes a file from device <n>. Wildcards can be used
in the filename.

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.

BOOT - Execute bootstrap at $018000

MON - Start DTVMON 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 - 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.

(If you use DTVBIOS, a special bootstrap is placed
at $018000 which will take you directly to normal BASIC)

Flashdisk partitions

One big problem with my DTV is that the flash rom might only last
for about: 100 re-flashes, and that every time I flash a new directory
image to the flash, I have to re-flash position $010000 and forward.

This means that position $010000 is probably the position which will
fail first.

DTVBASIC improves the flash-disk routines to support several
flash partitions, each with its own directory starting at different
positions in the flash.

You can for example have your normal flash directory at $010000,
another one at $050000 and a third at $1B0000.

Features

Support for up to 31 partitions in steps of $10000 bytes

Fixes the load bug in flash, documented by T.L.R.

Sanity check of the partition switched to

Automatic re-coding of $010000-based flash images

Display of current partition

How to write an extended partition

Find a free area in the flash, starting on an even 0x10000 byte boundary (do not choose $0000000)

Create your filesystem with your favourite flash file system tools. I use DTVPACK by T.L.R and DTVBUILD by Hideki. You don't need to specify any offsets or any differennt load addresses, DTVBASIC takes care of that for you.

Instead of flashing the filesystem to position $010000, flash it to the free area you defined above.

How to change to another partition on the flash

The easiest way is to use the DIR command. DIR 1,5 will
change the flash routines to point to the filesystem
starting at position $0050000.
All following flash operations will be re-directed
to that partition.

It is also possible to use the LOAD command.
LOAD"$5",1 - Will change to partition 5 and load the "$" file.
LOAD"$0",1 - Display current partition
Since it is not possible to place a partition in the
low-mem area (without considerable danger), trying to
change to partition 0 will instead show the current partition.

When you make a new partition at for example $0070000, there is no need
to change the load adresses for the files. DTVBASIC will adjust the
adresses of directory and programs according to the selected partition.
Just make your file system as you would if the directory started at $010000.

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 3 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

<LB,LS> is only used in the first directory entry of a sector
and is the bank/sector of the next directory sector
<TYPE> is the type of file (PRG=0,SEQ=$10 or DEL=1).
<FB,FS> bank/sector of file data
<BLK..> size of the file in blocks
<SZ..> size of the file in bytes

Directory listing ends when <FB>=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
<FIRSTBANK> 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.

Flash-version of the DTV BASIC

DTVBASIC was originally created to be loaded from disk to DTV hi-mem.
It does so by switching in the correct hi-mem bank, load it with
data and then switch it back.

When loading from flash, the DTV uses DMA transfer.
DMA maps directly to the full 2MB range of the DTV memory, and is
un-aware of which bank is currently switched in.
However, the flash directory has 24-bit load adresses, so it is
possible to load the data directly to the hi-mem position.
This is the reason for the strange load adresses.

Here is a list of the files you need to put in your flash image,
and the load adresses they need to have.
Note that the DATA-files are loaded by the first file, so you
cannot chage their names.

DTVBASIC.BIN,DTVBASIC,2049,2070
BASDATA.BIN,$BASDATA,1998848,65532
PRGDATA.BIN,$PRGDATA,1982464,65532
EXTDATA.BIN,$EXTDATA,2001408,65532
RAMDATA.BIN,$RAMDATA,2002944,65532

Make sure that the tool you use to compile your flash image supports
the 24-bit load adress format. I use DTVBUILD by Hideki, which works fine.

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
(not used) $d2
HELP $d3
FROM $d4 (used in DMA command)
RAMDISK $d5
DIR $d6
SCRATCH $d7
RENAME $d8
RAMSAVE $d9
RAMLOAD $da
MEMDUMP $db
UNIT $dc (used in RAMDISK command)

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.