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.

    guur
    Everything on this site is © The Gang 2002-2008. Valid xhtml and css
    For more info contact: