IDE64 user's guide 2004.Jun.07

The IDE64 Project

IDE64

INTERFACE CARTRIDGE

user's guide

2004.06.07. preview

The ATA(PI) controller card for Commodore 64 / 128 computers
supporting HardDisk / CDROM / CompactFlash and more

Foreword

This will be the manual for the IDE64 interface cartridge with the upcoming IDEDOS 0.9x. Incomplete but planned parts are marked ~~this way~~, inserted texts since last version are marked this way, while deleted texts are marked ~~this way~~.

1 About the IDE64 interface cartridge
2 Set up and begin using the IDE64 cartridge
3 The CMOS Setup utility
- 3.1 Standard setup
  - 3.1.1 Date, Time
  - 3.1.2 Paper, border, char color
  - 3.1.3 Start boot file
  - 3.1.4 Boot device
  - 3.1.5 1541 fastloader
  - 3.1.6 Set basic clock
  - 3.1.7 Keyboard repeat
  - 3.1.8 Lowercase chars
  - 3.1.9 Use dos wedge
  - 3.1.10 C128 keyboard
  - 3.1.11 Direct write
  - 3.1.12 Accu charging
- 3.2 Device numbers
  - 3.2.1 LCD display
  - 3.2.2 Serial device x
  - 3.2.3 HDD x
  - 3.2.4 PC-LINK
- 3.3 Advanced setup
  - 3.3.1 Power management
  - 3.3.2 Retry on error
  - 3.3.3 Write cache
  - 3.3.4 Read look-ahead
  - 3.3.5 Slow down cdrom
  - 3.3.6 Linear read max
- 3.4 Restore defaults
- 3.5 Save & exit
- 3.6 Discard & exit
4 Preparing a blank disk
- 4.1 The format utility
5 Using partitions
6 Using directorys
- 6.1 Paths
- 6.2 Wildcards
7 Using files
8 Direct access
- 8.1 BLOCK-READ
  - 8.1.1 Reading from a CHS-ATA device:
  - 8.1.2 Reading from a LBA-ATA or ATAPI device:
  - 8.1.3 Getting device identity:
- 8.2 BLOCK-WRITE
  - 8.2.1 Writing to a CHS-ATA device:
  - 8.2.2 Writing to a LBA-ATA or ATAPI device:
- 8.3 BUFFER-POINTER
  - 8.3.1 Selecting a byte:
9 The File Manager
- 9.1 Plugins
  - 9.1.1 Plugin format
- 9.2 Manager config file
- 9.3 Manager keys
10 Using the monitor
11 DOS Wedge
- 11.1 @
- 11.2 @#
- 11.3 @$
- 11.4 /
- 11.5 %
- 11.6 ´ (shift 7)
- 11.7 ^| (up arrow)
- 11.8 <— (left arrow)
- 11.9 £ (pound sign)
12 BASIC extensions
- 12.1 HDINIT
- 12.2 INIT
- 12.3 DATE
- 12.4 KILL
- 12.5 LOAD
- 12.6 SAVE
- 12.7 VERIFY
13 Programming in assembly
- 13.1 $FFB7 - READST
- 13.2 $FF90 - SETMSG
- 13.3 $FFE1 - STOP
- 13.4 $FFBA - SETLFS
- 13.5 $FFBD - SETNAM
- 13.6 $FFC0 - OPEN
- 13.7 $FFC3 - CLOSE
- 13.8 $FFC6 - CHKIN
- 13.9 $FFC9 - CHKOUT
- 13.10 $FFCF - CHRIN
- 13.11 $FFE4 - GETIN
- 13.12 $FFD2 - CHROUT
- 13.13 $FFE7 - CLALL
- 13.14 $FFCC - CLRCHN
- 13.15 $FFD5 - LOAD
- 13.16 $FFD8 - SAVE
- 13.17 $DEF1 - WRITE
- 13.18 $DEF4 - READ
14 PCLink
15 Command channel
- 15.1 File management commands
  - 15.1.1 Position
- 15.2 Filesystem management commands
  - 15.2.1 Initialize
  - 15.2.2 Scratch
- 15.3 Partition management commands
  - 15.3.1 Change partition
- 15.4 Device management commands
  - 15.4.1 Drive number change
  - 15.4.2 Identify device
  - 15.4.3 Reset device
  - 15.4.4 Power management
  - 15.4.5 Eject/Load media
  - 15.4.6 Lock/Unlock media
- 15.5 Direct access commands
  - 15.5.1 Buffer read
  - 15.5.2 Buffer position
  - 15.5.3 Buffer write
- 15.6 Directory handling commands
  - 15.6.1 Change working dir
  - 15.6.2 Make dir
16 Command channel error messages
17 Compatibility FAQ
- 17.1 Commodore serial devices
- 17.2 SuperCPU
- 17.3 RetroReplay, Action Replay, Final cartridge
- 17.4 RamLink
- 17.5 CMD HD/FD/etc. (serial)
- 17.6 C128
- 17.7 JiffyDOS
- 17.8 NTSC/PAL
- 17.9 REU
- 17.10 Second SID
- 17.11 +60K
- 17.12 IEEE-488
- 17.13 Turbo 232
- 17.14 Software
- 17.15 CHS/LBA harddisk
18 More information

1 About the IDE64 interface cartridge

The IDE64 cartridge was created to provide the fastest I/O and biggest storage capacity available for the C64/C128 computers, at cheap price. It's possible to connect and use ATA(PI) devices to a C64/C128 like harddisks, CDROMs, CompactFlash ~~readers~~cards and ZIP drives just like ordinary disk drives. The IDE64 cartridge contains a 64Kb PEROM (flash EPROM containing IDEDOS, Machine Code Monitor, File Manager and Setup), a 28kB RAM (used for internal buffers), a realtime clock chip (powered by a battery), two LEDs (to indicate the presence of cartridge and device activity), a Short-BUS for peripherals (like DUART Card) and an ispLSI chip.

2 Set up and begin using the IDE64 cartridge

Make sure that the computer is powered off. The cartridge must be plugged into the expansion so that the chips are on top as seen on the picture. The ATA(PI) devices are connected with a 40 wire IDE-cable to the port on the end of the cartridge. Make sure that the red line on the cable is at pin 1 on both ends. (pin 1 is usually near the reset button on the cartridge, and on power cord side on the devices) 2 devices can be connected on the cable, one is called master, the other slave. It's important that there's only one master and one slave on a cable, so check the jumper setting of your devices.

The external devices need external power too, so connect them to a pc power supply or something similar. AT-style power supplys will work without problems (some require a minimal load to start, so it may not work alone without any devices). ATX-style supplys require that the green wire is connected to a black one, but do this at your own risk without connecting any devices to the supply to minimalize possible damage. (if everything goes well, the cooler must spin up) First test your devices with the supply without connecting to the cartridge to see if everything is ok.

Compact Flash card plugged into the V3.4 version of the cartridge does not require any external power supply. If you want to use an ATA(PI) device and CompactFlash card at the same time, then configure the device as slave, because the CF card is allways master.

Peripherals are connected to the other port of the cartridge with a 34 wire cable similar to the floppy cable in pcs, but without wire swaping. Peripherals do not require any external power.

There's a battery holder on the back of the cartridge. It's strongly recommended to put a battery into it (3 Volt) otherwise the setup settings can't be permanently stored and the file timestamping won't work. If using accu or super cap instead of battery, then enable recharging in the CMOS Setup utility.

When everything is ready, you may turn on your equipment. It's recommended to first turn on the power supply, then the computer, however if you have devices that do not spin-up until the computer is turned on and your AT-supply does not start without load (giving an annoying noise) you must do this the other way around. If your devices are not detected on poweron, try giving HDINIT on the basic prompt. If still nothing, turn off your computer and powersupply, then check the cables and jumper settings. If you suspect that there's some software bug preventing the detection of the device (eg. it works in some other equipment) than contact us on the mailinglist.

If everything is ok the boot screen should come up first (black screen with light-blue characters) with the information on the version of IDEDOS and the connected devices. Then the standard c64 reset screen should appear in less the 30 seconds, depending on the connected devices. The boot screen only appears on poweron, so if you want to autodetect your devices to see everything is ok use HDINIT. If there's no boot screen just a standard c64 reset screen without the usual "IDE-DOS xxxxx EXPANDED" you may use the wrong version of IDEDOS. (eg. SuperCPU version on c64, c64 version on SuperCPU, config register version on old cartridge) If "30719 BASIC BYTES FREE" appears that means there's no valid IDEDOS burned into the perom of the cartridge.

To use the builtin selftest of IDEDOS hold down LEFTSHIFT while turning on the computer (or simply use SHIFTLOCK).

3 The CMOS Setup utility

The IDE64 cartridge has a battery backed up clock with some memory (DS1302) used to store the configuration settings and current time. Of course it works without a battery too using the default settings and no clock. If you do not like the defaults, you can change them here.

~~You can start the~~The CMOS Setup utility is started by pressing <— + RESTORE while in interactive mode. (like STOP + RESTORE) Moveing is done with cursor keys, RETURN selects/changes item, + and - also changes item. C= and STOP exits submenu, while C= saves setting and STOP discards them in main menu.

Setup does not touch memory range $0800-$FFFF so your work won't lost when need to change some settings.

3.1 Standard setup

General settings.

3.1.1 Date, Time

Here's possible to set the built in clock. This has affect on the DATE command, the file timestamping and on TI$ (see below). The calendar is built in and works in range 1980-2079. (Y2K compatible) The clock ticks while the computer is turned off. (but requires battery)

3.1.2 Paper, border, char color

This affect the default blue screen colors. Same paper and char color not accepted. (not readable and may be confusing)

3.1.3 Start boot file

The file called "1//:BOOT,PRG" can be autostarted from the boot drive at powerup or allways after reset. The file must be executeable with RUN. Hold C= if you want to skip autoboot, or hold STOP to skip starting of program.

3.1.4 Boot device

The default drivenumber (at $BA) after reset can be selected here. (usefull for the dos wedge, monitor and autobooting)

3.1.5 1541 fastloader

~~Fastloader for the C1541 floppy drive. (and also fast read/write in manager)~~

3.1.6 Set basic clock

Sets TI$ to the time in the built in clock.

3.1.7 Keyboard repeat

Sets keyboard repeat after reset. (at $028A)

3.1.8 Lowercase chars

Upper/lowercase chars after reset or STOP + RESTORE.

3.1.9 Use dos wedge

You may disable it, if you have JiffyDos installed. For more see below!

3.1.10 C128 keyboard

If cartridge has cartconfig register, support is compiled in, and computer is a C128, it makes use of extra keys on keyboard.

C128 extra keys
Key	Function
`ESC`	CHR$(27)
`TAB`	CHR$(9)
`ALT`	-nothing-
`HELP`	Enter monitor
`LINE FEED`	CHR$(10)
`NO SCROLL`	-nothing-
`CURSOR KEYS` and `NUM PAD`	Their usual meaning

3.1.11 Direct write

Enables/disables the use of "B=W". Cleared on reset. You may have to enable it when creating filesystem.

3.1.12 Accu charging

Selects accu charging current. Leave it on "Battery" if not using accu or super cap. Charging a battery is useless, and some low quality products may even leak if charged.

3.2 Device numbers

~~All about device numbers.~~Device number mapping to drives. -- means device is disabled.

3.2.1 LCD display

~~Device number for LCD display connected to short bus.~~

3.2.2 Serial device x

Device number mapping for serial devices. Selecting 9 for serial device 8, and 8 for serial device 9 will effectively swap them.

3.2.3 HDD x

Usefull when programs think device number 8 is the only one.

3.2.4 PC-LINK

~~Virtual drive. Needs serial/parallel cable and a server program on the PC.~~

3.3 Advanced setup

Master/Slave ATA(PI) device configuration.

3.3.1 Power management

Drive spindown time from 1 min to 2 hours in 15 steps. KILL will also spin down the drive if it's enabled. (your device must support power management!)

3.3.2 Retry on error

Tells the device to retry on error.

3.3.3 Write cache

Will speed up writes if supported by device.

3.3.4 Read look-ahead

Will speed up reads if supported by device.

3.3.5 Slow down cdrom

Selects 255 Kb/s data transfer rate on CDROMs supporting this. (deactivates the built in jet simulator on 32x or faster CDROMs if enabled) Has no effect on transfer rate, because the cartridge transfers data much slower.

3.3.6 Linear read max

Maximal sequential read/write allowed by the device. (setting it lower than 128 will degrade the performance of CFS filesystem greatly!) You should decrease it from 128 if you get ?LOAD ERROR or ?FILE DATA ERROR when loading/saving a big program. (this is very unlikely)

3.4 Restore defaults

Does restore the default settings.

3.5 Save & exit

Save changes and exit cmos setup. (same as pressing C=)

3.6 Discard & exit

Forget changes and exit setup. (same as pressing STOP)

4 Preparing a blank disk

To use a new disk with IDE64 you must first create the filesystem on it. IDEDOS has it's own filesystem called CFS. It allows to use disks up to 128 Gb, files up to 4Gb with holes and fast seeking, ~~relative files up to 16Mb~~, 16 partitions, unlimited directorys and files (only limited by the capacity of disk), customizable filetypes, and new file permissions.

To create the filesystem on a harddrive/ZIPdrive use the provided format utility. It allow's to create partitions, change partition flags and create filesystems on them. First set the "Direct write" option in the setup utility to enabled, then start the format utility. Follow the instructions. Don't forget that formatting a partition will erase all data on it permanently!

~~CDROM device do not need any special treatment, just use ISO9660/Joilet format CDs to be able to read them.~~

4.1 The format utility

The partitioner tool and the CFS filesystem creator is integrated into one executable called CFSfdisk. First it was a prototype utility running on GNU/Linux systems, then it was ported to C64 with the CC65 compiler.

Before partitioning/formatting go into setup and change 'Direct write' to enabled. Then load and start cfsfdisk.

CFSfdisk version 6
Copyright (C) 2001-2003 Kajtar Zsolt
(Soci/Singular)

CFSfdisk comes with ABSOLUTELY NO
WARRANTY; for details see LICENSE.
This is free software, and you are
welcome to redistribute it
under certain conditions; se LICENSE
for details.

Drive number (4-30):

CFSfdisk is released under the GPL2, the C source can be downloaded with the IDEDOS source. OK, first it want's to know what's the drive's number you want to format. It's usually 12 or 13, see your setup settings on device number assignment for master/slave device. Remember that there will be no changes made on disk unless you exit with command 'w'.

For LBA disks only the LBA sectors
matters, for CHS ignore LBA sectors.

Cylinders (1-65536, default 1244):
Heads (1-16, default 16):
Sectors (1-255, default 63):
LBA (256-268435456, default 1253952):

Usually the autodetected defaults are ok, so you can just press enter for these questions. If not, enter the correct values.

Did not found any CFS partition entry in
PC BIOS partition table.
I assume you want to use the whole disk.
If you want to share the disk with other
operating systems, use the fdisk
utility, and make a partition entry
with type 0xCF.

Creating new disklabel.

It's possible to share disk with other (pc) operating systems, and because there was no partition marked for IDEDOS usage, the disk will be repartitioned so that the whole disk will be used by IDEDOS. It you only want to use a part of the disk for IDEDOS first create a partition with type 0xCF. (those familiar with the util-linux fdisk utility will know what I'm talking about for sure...) Anyway if you won't ever use this disk with anything else but a c64 then ignore the crap above ;-)

Creating new partition table.

A new empty c64 partition table was created. (inside the PC BIOS partition entry with type 0xCF)

Command (m for help): m
Command action
   a   select boot partition
   d   delete a partition
   g   set global disklabel
   h   toggle hidden flag
   l   toggle lbamode
   m   print this menu
   n   add new partition
   o   create an empty partition table
   p   print the partition table
   r   toggle writeable flag
   t   change partition's type
   q   quit without saving changes
   w   write table to disk and exit

Typeing 'm' list possibilities. There are no partitions yet, so let's create one.

Command (m for help): n
Partition number (1-16): 1
Start (4-1253952, default 4):
End or +x or +xG or +xM or +xK or +x%
(10-1253952, default 1253952): +50%
Partition's name: stuff

This creates partition 1 called 'stuff' beginning on the start of the disk, and it will fill the half of the disk. (~300Mb) It's possible to give the exact start and end position or the size of the partition in sectors (eg. +2342) for power users. For everyday use +1048576K or +1024M or +1G creates an example partition with a size of 1 Gib. (metrics are powers of 1024, not 1000!) +25% means ¼ of the maximal partition size possible in this extent.

After adding some more partitions, the partition table will look like this:

Command (m for help): p

Drive 12: 1253952 sectors
Disklabel: "                "

Nr Boot Flags     Start       End
   Blocks   Id  System  Name
 1   *   --           4    626977
   313487    1  CFS     stuff
 2       --      626978    831777
   102400    1  CFS     work
 3       --      831778    864545
    16384    1  CFS     geos
 4       --      864546   1253952
   194703+   1  CFS     backup

Now let's change the global disklabel, and the default boot partition (I like to start at the work partition after boot). As you can see the listing above is not very readable as this program was designed for 80 column screen... The start and end of partition is displayed in sectors, while the partition size is displayed in Kib.

Command (m for help): g
New disklabel: soci's disk

Command (m for help): a
Partition number (1-16): 2

Command (m for help): p

Drive 12: 1253952 sectors
Disklabel: "soci's disk     "

Nr Boot Flags     Start       End   Blocks   Id  System  Name
 1       --           4    626977   313487    1  CFS     stuff
 2   *   --      626978    831777   102400    1  CFS     work
 3       --      831778    864545    16384    1  CFS     geos
 4       --      864546   1253952   194703+   1  CFS     backup

Partition 3 will be used by GEOS (I hope the correct driver for GEOS will be available someday), so I'll change the partition type for it, and add the hidden flag, because it's not readable by IDEDOS anyway.

Command (m for help): t
Hex code (type L to list codes): l

 0  Empty
 1  CFS
 2  GEOS
Hex code (type L to list codes): 2

Command (m for help): h
Partition number (1-16): 3

Command (m for help): p

Drive 12: 1253952 sectors
Disklabel: "soci's disk     "

Nr Boot Flags     Start       End   Blocks   Id  System  Name
 1       --           4    626977   313487    1  CFS     stuff
 2   *   --      626978    831777   102400    1  CFS     work
 3       H-      831778    864545    16384    2  GEOS    geos
 4       --      864546   1253952   194703+   1  CFS     backup

Now it's ready, let's format (or you can use 'q' to abort):

Command (m for help): w

Formatting partition 1...done.
Formatting partition 2...done.
Formatting partition 4...done.
Done.

After filling partition 4 with lot of important stuff, let's mark it readonly. Load the CFSfdisk utility and start it.

Command (m for help): r
Partition number (1-16): 4

Command (m for help): p

Drive 12: 1253952 sectors
Disklabel: "soci's disk     "

Nr Boot Flags     Start       End   Blocks   Id  System  Name
 1       --           4    626977   313487    1  CFS     stuff
 2   *   --      626978    831777   102400    1  CFS     work
 3       H-      831778    864545    16384    2  GEOS    geos
 4       -R      864546   1253952   194703+   1  CFS     backup

Command (m for help): w

Done.

CFSfdisk autodetects CHS/LBA disks, so you don't have to worry about this (at least on C64). But if want to change it, use 'l'. The current setting is visible in the ' Drive xx:' line, if there are numbers about cylinders, etc. then the disk is in CHS format.

If you only want to reformat a partition without deleting/readding it just change it's type to CFS even if was already in CFS format.

5 Using partitions

When using a new disk at least 1 partition must be created. Partitions provide the highest level of organizing data. Each partition has it's own filesystem, so possible disk/software errors can't destroy the whole data at once. It's also possible to select the default partition on boot, set the global disklabel, partition names and partition attributes (hidden/readonly) with the format utility. The readonly attribute is usefull to prevent accidental changes to a filesystem.

Examples:

Listing available partitions. '*' indicates default partition, '<' indicates readonly partition. Hidden partitions are not listed.

@$=P
255 "SOCI'S DISK     " IDE64
1    "STUFF"            CFS
2    "WORK"            *CFS
4    "BACKUP"           CFS<
3 PARTITIONS.
READY.

Selecting partition 4 as working partition:

@CP4
02, PARTITION SELECTED,004,000,000,000
READY.

Selecting partition 1 as working partition the other way:

OPEN 15,12,15,"C"+CHR$(208)+CHR$(1):CLOSE15
READY.

Load a file from partition 2 from the directory '/GT'. More about paths later in chapter Paths.

LOAD"2//GT/:FILE"

SEARCHING FOR 2//GT/:FILE
LOADIND $0801-$0932
READY.

6 Using directorys

A directory is a list of files. To view the directory use LOAD"$" then LIST, ~~DIR~~, or @$. Of course LOAD will erase the current program in memory, while the last 2 methods will preserve your work.

The number before the first line is the partition number, it's followed by the directory's name, finally the ID string like IDE64. The following lines provide informations about the size of each file in 256 byte blocks (so 4 blocks are 1Kb), the name of the file enclosed in quotation marks, and it's filetype at the right side. The last line shows the total block count of all files in the list.

Example:

A directory list:

LIST

2 "TEST            " IDE64
0    "PLUGINS"          DIR
40   "BOOT"             PRG
2    "CONFIG EXT"
5    "TOD"              ASM
23   "VIEWER"           PRG
70 BLOCKS USED.
READY.

Putting a few thousand files in one long directory is not an optimal way of organizing data, so IDEDOS provides 'subdirectorys'. Subdirectorys look like normal files with filetype DIR in directory listings. Directorys are organized into a tree like structure starting from the root directory. The root directory is the top level directory, it's parent directory is itself. After boot this directory is selected as the working directory. The working directory is the directory which is used when no path is given in the filename just like in LOAD"$". Managing directorys is done via channel #15 commands, but these examples will use the DOS Wedge to simplify things. (more about the channel #15 commands and the DOS Wedge later)

Examples:

Creating a subdirectory

@MD:DIRNAME

Changing the working directory

@CD:DIRNAME

@/DIRNAME

Changing the working directory to the parent directory

@CD<—

@CD:..

@/..

~~Removing empty subdirectory~~

@RD:DIRNAME

6.1 Paths

Each file in the tree structure can be reached with a 'path'. The path is composed from the name of the directorys separated by a slash character.

Here's an example directory structure:

    ROOT-DIR
    /  |  \
   /   |   \
  A    B    C
  |        / \
  |       /   \
  F      E     D

Let's say the working directory is 'C' now. To load a file from directory 'E' use the following: LOAD"/E/:FILE". This is a relative path. It's also possible to specify the location of a file from the root directory, it's called absolute path: LOAD"//C/E/:FILE". As it seems the path is enclosed between 2 slashes before a semicolon, after it is the name of file. In the last example the real path was '/C/E' where the slash before C indicates the it's an absolute path.

Now let's compose a relative path, but now our working directory is 'F': LOAD"/../../C/E/:FILE". There's no directory named '..' in the graph, as this is a special directory, and it means the parent directory. That's why 'CD:..' means change to parent directory in some previous example. There's another special directory called '.' which means the directory itself. These 2 special directorys allways exists.

To embed the partition number into the filename place it before the path, eg. '13/C/:E'.

Examples:

The directory structure above can be created by the following program:

10 OPEN 15,12,15
20 PRINT#15,"CD:/"             :REM GOTO ROOT-DIR
30 PRINT#15,"MD:A"             :REM CREATE A
40 PRINT#15,"MD/A/:F"          :REM CREATE F
50 PRINT#15,"MD:B"             :REM CREATE B
60 PRINT#15,"CD:B"             :REM ENTER B JUST FOR FUN
70 PRINT#15,"MD//:C"           :REM CREATE C
80 PRINT#15,"MD//C/:E"         :REM CREATE E
90 PRINT#15,"MD/../C/./E/../:D":REM CREATE D ;-)
100 CLOSE 15

This small program lists all files in the working directory and in it's subdirectorys (recursive directory listing). The level of a directory in the tree is illustrated by the amount of tabulation before the file listing.

10 OPEN 15,12,15
20 A=A+1:OPEN A,12,0,"$":GET#A,A$,A$
30 GET#A,A$,A$,A$,B$:A$=A$+CHR$(0):B$=B$+CHR$(0):IF ST THEN 130
40 PRINT TAB(A*2-2);ASC(A$)+ASC(B$)*256;:B=1:D$="":N$=""
50 GET#A,A$:IF A$="" THEN 110
60 PRINT A$;:IF A$=CHR$(34) THEN B=B+1:GOTO 50
70 ON B GOTO 50,80,90
80 N$=N$+A$:GOTO 50
90 IF A$<>CHR$(32) THEN D$=D$+A$
100 GOTO 50
110 PRINT:IF D$="DIR" THEN PRINT:PRINT#15,"CD:"+N$:GOTO 20
120 GOTO 30
130 CLOSE A:A=A-1:IF A THEN PRINT#15,"CD"CHR$(95):PRINT:GOTO 30
140 CLOSE 15

6.2 Wildcards

It's possible to filter directory listings to show only a subset of files in a directory by using wildcards. There are 2 different wildcards: '?' matches exactly one character, while '*' matches any number of characters. These wildcards can be used in path elements or filename too, in this case the first filename will be matched. To filter directory listing by filetype append '=TYP' to the filename.

Examples:

List files starting with 'A'.

LOAD"$A*"

SEARCHING FOR $A*
LOADING $0801-$08DF
READY.
LIST

1 "PICTURES        " IDE64
132  "ALIEN BAR BY WEC" FUN
29   "ALIEN-LIFE BY MB" SHI
132  "ALLEY BY MIKE"    FUN
132  "ANGEL BY FZ"      FUN
72   "ARNIE BY AMN"     DRL
497 BLOCKS USED.
READY.

List files ending with 'DEPACKER'.

@$*DEPACKER
1 "UTILITIES       " IDE64
9    "DMC 5.0 DEPACKER" PRG
10   "DMC 5.1 DEPACKER" PRG
19 BLOCKS USED.
READY.

List files containing 'PLAYER'.

@$*PLAYER*
1 "UTILITIES       " IDE64
0    "MUSIC PLAYER"     DIR
9    "CD PLAYER 1"      PRG
12   "CD PLAYER 3"      PRG
12   "CD PLAYER 4"      PRG
77   "CUBIC PLAYER"     PRG
110 BLOCKS USED.
READY.

List 4 character long filenames.

@$????
1 "UTILITIES       " IDE64
0    "DEMO"             DIR
0 BLOCKS USED.
READY.

List files starting with 'K' and filetype 'D64'

@$K*=D64
1 "DEMOS           " IDE64
683  "KJU"              D64
683  "KRESTAGE 2"       D64
768  "KRESTOLOGY 1"     D64
768  "KRESTOLOGY 2"     D64
683  "KRESTOOLS"        D64
3585 BLOCKS USED.
READY.

7 Using files

Will write something about this...

8 Direct access

By using direct access commands you can read/write any sector of disk. Common use of direct access commands is to access unknown filesystems, manage the partition table and to create the filesystem. It's also important in diskeditor applications.

To use direct access, you need to open 2 channels, one for commands, and one for data. The command channel can be opened with the usual OPEN <lfn>,<device>,15. The data channel is opened similar to opening normal files, except that the file name must be a hash sign. (OPEN <lfn>,<device>,<channel>,"#") The channel number must be greater than 1. This 'file' will be a circular data buffer holding 512/2048 bytes depending on the device used. The end of buffer can be found by checking the variable ST.

8.1 BLOCK-READ

The block-read command reads the specified sector into the buffer and sets the buffer pointer to the start of buffer. It can also be used to get the ATA(PI) device identity information to find out the geometry, diskname, etc. as described in ATA(PI) standards.

8.1.1 Reading from a CHS-ATA device:

PRINT#<command lfn>,"B=R"; CHR$(<data channel>); CHR$(HEAD); CHR$(CYLINDERBITS8TO15); CHR$(CYLINDERBITS0TO7); CHR$(SECTOR)

8.1.2 Reading from a LBA-ATA or ATAPI device:

PRINT#<command lfn>,"B=R"; CHR$(<data channel>); CHR$(64 OR (LBABITS24TO27)); CHR$(LBABITS16TO23); CHR$(LBABITS8TO15); CHR$(LBABITS0TO7)

8.1.3 Getting device identity:

PRINT#<command lfn>,"B=R"; CHR$(<data channel>); CHR$(0); CHR$(0); CHR$(0); CHR$(0)

8.2 BLOCK-WRITE

The block-write command writes the buffer content to the specified sector and sets the buffer pointer to the start of buffer.

8.2.1 Writing to a CHS-ATA device:

PRINT#<command lfn>,"B=W"; CHR$(<data channel>); CHR$(HEAD); CHR$(CYLINDERBITS8TO15); CHR$(CYLINDERBITS0TO7); CHR$(SECTOR)

8.2.2 Writing to a LBA-ATA or ATAPI device:

PRINT#<command lfn>,"B=W"; CHR$(<data channel>); CHR$(64 OR (LBABITS24TO27)); CHR$(LBABITS16TO23); CHR$(LBABITS8TO15); CHR$(LBABITS0TO7)

8.3 BUFFER-POINTER

The buffer pointer selects individual bytes in the buffer. Reading and writing will start on the buffer position and the buffer pointer will be incremented by the number of bytes read/written.

8.3.1 Selecting a byte:

PRINT#<command lfn>,"B=P"; CHR$(<data channel>); CHR$(POSITIONBITS0TO7); CHR$(POSITIONBITS8TO15) Examples:

This example reads in the boot sector and prints out the CFS identification string. (CHS disk, CFS filesystem). For LBA or ATAPI devices modify this line: 20 PRINT#15,"B=R"CHR$(4)CHR$(64)CHR$(0)CHR$(0)CHR$(0)

10 OPEN15,12,15:OPEN4,12,4,"#" 
20 PRINT#15,"B=R"CHR$(4)CHR$(0)CHR$(0)CHR$(0)CHR$(1)
30 PRINT#15,"B=P"CHR$(4)CHR$(8)CHR$(0)
40 FORA=0TO15:GET#4,A$:PRINTA$;:NEXT 
50 CLOSE4:CLOSE15

This example prints some information from the device using the device identity.

10 OPEN15,12,15:OPEN4,12,4,"#"
20 PRINT#15,"B=R"CHR$(4)CHR$(0)CHR$(0)CHR$(0)CHR$(0)
30 PRINT#15,"B=P"CHR$(4)CHR$(46)CHR$(0)
40 PRINT"FIRMWARE REVISION:":B=4:GOSUB90
50 PRINT"MODEL NUMBER:":B=20:GOSUB90
60 PRINT#15,"B=P"CHR$(4)CHR$(20)CHR$(0)
70 PRINT"SERIAL NUMBER:":B=10:GOSUB90
80 CLOSE4:CLOSE15:END
90 FORA=1TOB:GET#4,A$,B$:PRINTB$A$;:NEXT:PRINT:RETURN

9 The File Manager

IDE File Manager is a software for ~~copying, deleting, renaming~~, making directories, and starting programs. Working with this program is very easy. Start it from BASIC typeing command MAN. Maximal number of files is 510/panel.

9.1 Plugins

Plugins are external programs called by the file manager to extend it's functionality. Plugins show text/various graphic formats, play sid files and animations, extract archives and disk images or just fire up an assembler with the file. Plugins are started by pressing RETURN or 3 on a file. When pressing 3 the file called "1//:VIEWER" is started from the boot drive. The action taken when RETURN is pressed is determined ~~by the file called "1//ETC/:MANPLUGINS".~~

9.1.1 Plugin format

Plugins are machine code files compiled to $1000. When started at $1000 they should display some kind of prompt for getting the filename. The manager starts the plugins at $1003 with the accumulator loaded with the length of filename, the X register with the lower, the Y with the higher byte of the address to the filename. $BA contains the current device number the file is on. The filename allways includes the filetype separated by a comma on the end.

Example:

A sample plugin framework


	*= $1000

	jmp printc
	jmp start

txt	.text 13,"FILENAME:",0

printc	lda #<txt
	ldy #>txt
	jsr $ab1e       ; print prompt
	ldy #255
oqu	iny
	jsr $ffcf       ; get input
	sta $200,y
	cmp #13
	bne oqu
	tya             ; setup fake manager start
	ldx #<$200
	ldy #>$200

start	jsr $ffbd       ; setup filename ("SD,MOV")
	lda #filenumber ; file number (1-255)
	ldx $ba         ; actual device number
	ldy #secaddy    ; secondary address
	jsr $ffba
	jsr $ffc0       ; open file
        
        ...             ; play movie
        
        rts             ; done

The plugin must not destroy $0002-$0333 badly and must not modify $0800-$0FFF! Please leave the VIC/SID/CIA, etc. after exit of the plugin in a usable state...

9.2 Manager config file

Not done yet.

9.3 Manager keys

Here's the list of keys and their functions in manager:

Manager keys
Key	Function
`<—`	Exit
`CONTROL`	Change panel
`UP/DOWN`	Move cursor
`F1` or `LEFT`	Page Up
`F7` or `RIGHT`	Page Down
`1`	Refresh dir
`3`	Execute viewer plugin ~~from boot drive (`"//:VIEWER"`)~~
`5`	~~Copy file(s)~~
`6`	~~Rename file(s)~~
`7`	Create directory
`8`	~~Delete file(s)~~
`9`	Send disk command
`.`	Go into parent dir
`/`	Go into root dir
`DEL`	(Un)select file
`F2/HOME`	Go on top of listing
`F8/CLR`	Go to end of listing
`RETURN`	Enter directory or LOAD"file",x RUN or start viewer plugin
`SHIFT` + `RETURN`	LOAD"file",x,1
~~`^\|`~~	~~Eject/reload media~~
`*`	Invert file selection
`+`	Select all files
`-`	Deselect all files
`C=`	Select drive

10 Using the monitor

The monitor is designed to be fast and simple, but still usefull for debugging and fixing. It's possible to edit every single byte in memory and I/O space without conflicting with internal variables of the monitor itself. Illegal opcodes and wildcard searching is included.
The monitor is started by hitting C= + RESTORE at the same time, or by executing a BRK instruction, or pressing LEFTSHIFT + RESET.

If C128 keyboard is enabled it's possible to use HELP to start the monitor.

To recover from died monitor (not very likely) press LEFTSHIFT + RESET. Memory won't get distorted.

To rip from games/etc, press LEFTSHIFT+RESET while the program is running. A few bytes from stack, the contents of both CIAs, the memory configuration at $00/$01 and the processor registers will be lost, but the memory is not touched. (not a real freezer, but at least it's possible to rip ifli pictures...)

To use the monitor like a real freezer monitor you must make sure that the NMI and BRK vectors won't get overwritten in ram. If so, press C= + RESTORE to freeze the program. The chip states, processor registers and memory is preserved. In the C64 version it's possible to call the monitor even from configurations like 5. (I/O area must be available)

Monitor commands
Command	Function
`@command`	Disk command and status
`@$`	Directory
`A xxxx NOP`	Assemble
`B xx`	Memory configuration
`BT`	Backtrace
`C start end start2`	Compare memory
`D {start {end}}`	Disassemble
`,start xx xx xx`	Write hex data to memory and disassemble
`EC {start {end}}`	Edit char (binary)
`[start xxxxxxxx`	Write binary data to memory
`ES {start {end}}`	Edit sprite (binary)
`]start xxxxxxxx`	Write binary sprite data to memory
`F start end xx`	Fill memory with byte
`G xxxx`	Execute at address
`H start end xx ? "txt"`	Search hex/any/ascii
`I {start {end}}`	Dump memory in ascii
`'start xxxxxxx`	Write ascii data to memory
`J {start {end}}`	Dump memory in screencode
`.start xxxxxxx`	Write screencode data to memory
`K "name"`	Defreeze memory
`L "name" {start}`	Load memory
`M {start {end}}`	Dump memory in hex and ascii
`O xx`	Actual drive
`:start xx xx xx xx`	Write hex data to memory
`R`	Show registers
`;xxxx xx xx`	Change registers
`S "name"`	Freeze memory
`S "name" start end`	Save memory
`T start end start2`	Copy memory
`V "name" {start}`	Verify memory
`X`	Continue program
`Q`	Exit to BASIC warm start
`<— {address}`	(left arrow) Push address(es) to astack.
`^\|`	(up arrow) Pop address from astack.
`*`	Select RAM/ROM

Examples:

Print error channel:

@
00, OK,000,000,000,000

Send disk command:

@CD:SOURCE
00, OK,000,000,000,000

Display directory:

@$T*
2 "TEST            " IDE64
13105"TRANCEANDACID"
5    "TOD"              ASM
13110 BLOCKS USED.

Select drive 12. Drive numbers are in hexadecimal. This drive number is used in all disk access commands, the default is the same as the boot drive selected in setup.

O C

Print registers. Modify the registers and flags by overwriting the line beginning with ";". ADDR is the address where the program continues (see X!), AC XR YR SP are the accumulator, x register, y register and stack pointer, BK is the currently edited bank selector (see B!), DR is the drive number used in disk access commands (see O!), NV-BDIZC are the processor flags.

R
 ADDR AC XR YR SP BK DR NV-BDIZC
;E5D1 00 00 0A F3 07 0C 00100010

Select bank 4. Banks 0-7 have the same meaning like the first 3 bits of $01, banks 8-1E selects the drive's memory with that device number, bank 1F selects VDC memory (C128 only).

B 4

Continue program execution at PC.

IDE64 MONITOR

 ADDR AC XR YR SP BK DR NV-BDIZC
;E5D1 00 00 01 F2 07 08 00100010
X

Try to exit to basic prompt. Usefull after hitting a BRK.

BRK EXCEPTION

 ADDR AC XR YR SP BK DR NV-BDIZC
;1230 10 00 0A C6 07 0D 00110000
Q

Start program at $080D. When program terminates it trys to return to monitor with a BRK.

G 80D

Enter assembly instructions. Illegal instuctions are supported, 65816 instructions are not.

A 1000 EE 20 D0 INC $D020
A1003 4C 00 10 JMP $1000
A1006 B3 30    LAX ($30),Y
A1008 NOP

Disassembly from last address: D. Disassembly a few lines: D1234. Disassembly till end of memory: D1234-. Disassembly between addresses: D1234-5678. Pressing RETURN on modified hex bytes or on modified disassembly modifies memory. (the cursor position selects what happens) To slow down listing hold CONTROL, to stop press STOP, to pause listing press anything else.

D 1000
,1000 EE 20 D0 INC $D020
,1003 4C 00 10 JMP $1000
,1006 B3 30    LAX ($30),Y

Dump memory in hex and ascii. Press RETURN to enter the modified hex values into memory. To enter ascii text, use I! Possible parameters are the same as for D.

M E478
:E478 20 2A 2A 2A 2A 20 43 4F  **** CO
:E480 4D 4D 4F 44 4F 52 45 20 MMODORE
:E488 36 34 20 42 41 53 49 43 64 BASIC
:E490 20 56 32 20 2A 2A 2A 2A  V2 ****

Dump memory in ascii. Press RETURN to enter the modified text into memory. Some ascii values have the same screencode, so be carefull when editing mixed text mixed with code. Possible parameters are the same as for D.

i a0a0
'a0a0 DfoRnexTdatAinput~inpuTdiMreaDle
'a0c0 TgotOruNiFrestorEgosuBreturNreMs
'a0e0 toPoNwaiTloaDsavEverifYdeFpokEpr
'a100 inT~prinTconTlisTclRcmDsySopeNcl

Dump memory in screencode. Press RETURN to enter the modified text into memory. (I* is available for MK7 addicts) Possible parameters are the same as for D.

J 400
.0400     **** COMMODORE 64 BASIC V2 *
.0428 ***
.0450                  64K RAM SYSTEM
.0478  IDE-DOS BETA! EXPANDED

Dump memory in binary. Press RETURN to enter the modified bytes into memory. "." means 0, anything else (no space) 1. Possible parameters are the same as for D.

B 3
EC D008
[D008 ...##...
[D009 ..####..
[D00A .##..##.
[D00B .######.
[D00C .##..##.
[D00D .##..##.
[D00E .##..##.
[D00F ........

Dump memory as sprite. Press RETURN to enter the modified bytes into memory. "." means 0, anything else (no space) 1. Possible parameters are the same as for D.

ES A00
]0A00 ........................
]0A03 ........................
]0A06 ........................
]0A09 ........................
]0A0C ........................
]0A0F ........................
]0A12 ........................
]0A15 ........................
]0A18 ...........#######......
]0A1B .........##########.....
]0A1E .......############.....
]0A21 ......#######.....#.....
]0A24 .....########.....#.....
]0A27 ....########......#.....
]0A2A ....########..#...#.....
]0A2D ....#######...#..##.....
]0A30 .....##.......#..##.....
]0A33 ......#...........#.....
]0A36 ......#...........##....
]0A39 .......#....#......#....
]0A3C ........##...#....#.....

Copy memory from $400-$7FF to $C00-$FFF. Overlapping areas are supported.

T 400 7FF C00

Compare memory from $2000-$3FFF with $E000-$FFFF.

C 2000 3FFF E000
 3FC0 3FC1 3FC2

Fill memory $2-$FFFF with $00.

B 4
F 2 FFFF 0

Do backtrace. $1237, $1233 and $1230 are the caller JSR addresses, $30 is some pushed data.

A1230 20 33 12 JSR $1233
A1233 20 36 12 JSR $1236
A1236 08       PHP
A1237 20 3A 12 JSR $123A
A123A 00       BRK
A123B

G 1230

BRK EXCEPTION

 ADDR AC XR YR SP BK DR NV-BDIZC
;1230 10 00 0A C6 07 0D 00110000
BT
1237 30 1233 1230 7A E3 1009 050E 10

Search memory for instructions accessing $277. (? is a 1 character wildcard matching everything)

H E000 FFFF ? 77 2
 E5B4 E5BC EB3C
D E5B4
,E5B4 AC 77 02 LDY $0277
,E5B7 A2 00    LDX #$00
,E5B9 BD 78 02 LDA $0278,X

Search memory for text.

H E000 FFFF "COMM"
 E47E

Save memory to disk.

S"SPRITES" 2000 21FF
OK

Load memory to disk.

L"SPRITES"
2000-21FF OK

L"SPRITES" 2200
2200-23FF OK

Verify memory from disk.

V"SPRITES"
2000-21FF OK

V"SPRITES" 2200
 2312 2313
2200-23FF OK

Freeze (saves 64K RAM + I/O) memory to disk. VDC memory is not saved on C128.

S"MYFREEZE"
OK

Defreeze memory from disk. (loads 64K RAM + I/O)

K"MYFREEZE"
0000-FFFF OK

Look at screen. Usefull for finding the videobank after LEFTSHIFT + RESET.

Using astack. Search for something, then put a leftarrow before the address list, press RETURN (push), then list with D uparrow, or with something else (pop). The address stack is 8 deep only.

H E000 FFFF 20 BA FF
<—E1DD E1F0 E22B E23F E24E
D^|
,E24E 20 BA FF JSR $FFBA
,E251 20 06 E2 JSR $E206
,E254 20 0E E2 JSR $E20E
D^|
,E23F 20 BA FF JSR $FFBA
,E242 20 06 E2 JSR $E206
,E245 20 00 E2 JSR $E200
D^|
,E22B 20 BA FF JSR $FFBA
,E22E 20 06 E2 JSR $E206
,E231 20 00 E2 JSR $E200
D^|
,E1F0 20 BA FF JSR $FFBA
,E1F3 20 06 E2 JSR $E206
,E1F6 20 00 E2 JSR $E200
D^|
,E1DD 20 BA FF JSR $FFBA
,E1E0 20 06 E2 JSR $E206
,E1E3 20 57 E2 JSR $E257

Using print upwards/downwards. (F1, F3, F5, F7). Type D FCE2 then hold F3 till the code before $FCE2 appears. (other keys work similar)

,FCDD D0 02    BNE $FCE1
,FCDF E6 AD    INC $AD
,FCE1 60       RTS
,FCE2 A2 FF    LDX #$FF
,FCE4 78       SEI
,FCE5 9A       TXS
,FCE6 D8       CLD
,FCE7 20 02 FD JSR $FD02

Quick switch between RAM/RAM (bank 4/7)

 ADDR AC XR YR SP BK DR NV-BDIZC
;EAB4 03 03 15 EA 07 08 00100101
*
RAM
R
 ADDR AC XR YR SP BK DR NV-BDIZC
;EAB4 03 03 15 EA 04 08 00100101

11 DOS Wedge

These are one/two character long commands to speed up some frequently typed command at the basic prompt. Enable/disable this feature in the setup utility.

11.1 `@`

It sends the parameter (if any) to the last used device and then prints the command channel.

Examples:

Print error channel:

@
00, OK,000,000,000,000

READY.

Delete a file:

@S:MYFILE
01, FILES SCRATCHED,001,000,000,000

READY.

11.2 `@#`

Selects the specified device as last used device.

Example:

Select drive 8:

@#8

READY.

11.3 `@$`

Display directory without affecting memory

Example:

List PRG files beginning with "S" ending with ".DRL".

@$S*.DRL=P
1 "TEST            " IDE64
33   "SHUDDER.DRL"      PRG
33 BLOCKS USED.

READY.

11.4 `/`

Loads a basic file, like LOAD"FILE",<current device>.

Example:

To load a program from directory listing:

@$
1 "TEST            " IDE64
0    "PLUGINS"          DIR
132  "2 PLANETS BY"     FUN
45   "DRAZPAINT 2.0"    PRG
/1   "DRAZLACE V1.0"    PRG
64   "TASM"             PRG
SEARCHING FOR DRAZLACE V1.0
LOADING $0801-$3023
READY.

11.5 `%`

Loads an assembly file, like LOAD"FILE",<current device>,1.

Example:

To load a program from directory listing:

LIST

1 "TEST            " IDE64
0    "PLUGINS"          DIR
132  "2 PLANETS BY"     FUN
45   "DRAZPAINT 2.0"    PRG
41   "DRAZLACE V1.0"    PRG
%4   "TASM"             PRG
33   "SHUDDER.DRL"      PRG
SEARCHING FOR TASM
LOADING $9000-$CF00
READY.

11.6 `´` (shift 7)

Verifys an assembly file, like VERIFY"FILE",<current device>,1.

Example:

Verify Drazlace:

´DRAZLACE*

SEARCHING FOR DRAZLACE*
VERIFYING $0801-$3023
OK

READY.

11.7 `^|` (up arrow)

Loads a basic file, like /, and than starts it with RUN.

Example:

Load Drazlace and start it:

^|DRAZLACE*

SEARCHING FOR DRAZLACE*
LOADING $0801-$3023
READY.
Ru:

11.8 `<—` (left arrow)

Saves a basic file, like SAVE"FILE",<current device>.

Example:

To save a program:

<—MYFILE

SAVING MYFILE $0801-$0932
READY.

11.9 `£` (pound sign)

Loads an assembly file, like %, and than starts it with JMP at it's load address.

Example:

Load and start TASM:

£TASM

SEARCHING FOR TASM
LOADING $9000-$CF00

12 BASIC extensions

Most basic extensions slow down program execution, but this one has some optimizations to avoid the performance hit.

12.1 HDINIT

Trys to autodetect devices connected to the cartridge.

Example:

HDINIT
MASTER:
ST9385AG

READY.

12.2 INIT

Fills memory with nulls, then reset. Usefull before linking.

12.3 DATE

Prints the date and time.

Example:

DATE
THU AUG 14 11:12:26 2003

READY.

12.4 KILL

Switches cartridge off. Usefull if you suspect compatibility problems with a program.

Example:

KILL
BYE!

READY.

12.5 LOAD

Loads a program file into memory. Useing no device number selects last used device. No filename means "*".

Example:

LOAD

SEARCHING FOR *
LOADING $0801-$099E
READY.

12.6 SAVE

Saves program to disk. Useing no device number selects last used device.

Example:

SAVE"TEST"

SAVING TEST $0801-$1A43
READY.

12.7 VERIFY

Verifys that the program in memory matches the on-disk version. Useing no device number selects last used device. No filename means "*".

Example:

VERIFY"TEST"

SEARCHING FOR TEST
VERIFYING $0801-$1A43
OK

READY.

13 Programming in assembly

This part is not finished...

13.1 $FFB7 - READST

Description:	Read status word
Implementation:	Standard
Communication registers:	None
Preparatory routines:	None
Error returns:	None
Status:	None
Registers affected:	A

Example:

Check end of file while reading

	jsr chrin	; read data from file
	sta data,y
	jsr readst	; test status
	and #$40	; end of file flag
	bne endoffile

Device status ($90)
Bit	Meaning
7	Device not present
6	End of File
5	(Tape CRC error)
4	Verify/read error (Tape read error)
3	(Tape long block)
2	(Tape short block)
1	~~No more bytes~~Timeout on receive
0	Timeout on send

13.2 $FF90 - SETMSG

Description:	Control kernal message printing
Implementation:	Standard
Communication registers:	A
Preparatory routines:	None
Error returns:	None
Status:	None
Registers affected:	A

Example:

Turn off messages to prevent screen distorsion

	lda #$00
	jsr setmsg	;turn off messages

Messages ($9D)
Bit	Meaning
7	Full error messages (LOADING, etc.)
6	Kernal error messages (I/O ERROR#x)
5..0	Undefined

13.3 $FFE1 - STOP

Description:	Check if stop was pressed
Implementation:	Standard
Communication registers:	A
Preparatory routines:	None
Error returns:	None
Status:	None
Registers affected:	A, X

Example:

Check stop key while reading a file (STOP calls CLRCHN if stop was pressed)

	jsr chrin
	sta ($fb),y
	jsr stop
	beq stoped	;stop was pressed

	...

stopped	lda #filenum
	jmp close	;close file and exit

13.4 $FFBA - SETLFS

Description:	Sets Logical File Number, Device Number, and Secondary Address
Implementation:	Standard
Communication registers:	A, X, Y
Preparatory routines:	None
Error returns:	None
Status:	None
Registers affected:	None

Example:

Set the first three parameters of BASIC OPEN command. Filenumber is ignored for LOAD/SAVE.

	lda #filenumber	; file number (1-255)
	ldx $ba		; actual device number
	ldy #secaddy	; secondary address
	jsr setlfs
        
        ...

        jsr open

Device numbers ($BA)
Device number	Device
0	Keyboard
1	Datassette(TM)
2	RS-232C device
3	CRT display
4..5	Serial bus printer
6..7	Serial bus plotter
8..11	CBM serial bus disk drive
12	Primary IDE controller, Master (default)
13	Primary IDE controller, Slave (default)
14	PC-link serial/parallel (default)
15..30	Other
31..255	Illegal

Secondary addresses ($B9)
Secondary address	Open mode
0	Read access (load)
1	Write access (save)
2..14	Data channel
15	Status/command channel
16..127	Illegal
128..255	Illegal (serial bus specific)

13.5 $FFBD - SETNAM

Description:	Sets filename for OPEN/LOAD/SAVE routine
Implementation:	Standard
Communication registers:	A, X, Y
Preparatory routines:	None
Error returns:	None
Status:	None
Registers affected:	None

Example:

Set filename for OPEN/LOAD/SAVE

	lda #8		; filename length
	ldx #<name	; pointer to filename, low byte
	ldy #>name	; pointer to filename, high byte
	jsr setnam

	...

        jsr open

name	.text "filename"

13.6 $FFC0 - OPEN

Description:	Open a logical file
Implementation:	IDE Extended
Communication registers:	None
Preparatory routines:	SETLFS, SETNAM
Error returns:	1, 2, 4, 5, 6, 7, 240 (see errorcodes)
Status:	$00, $80 (see READST)
Registers affected:	A, X, Y

Example:

Open a file

	lda #filenumber	; file number (1-255)
	ldx $ba		; actual device number
	ldy #secaddy	; secondary address
	jsr setlfs
	lda #8		; filename length
	ldx #<name	; pointer to filename, low byte
	ldy #>name	; pointer to filename, high byte
	jsr setnam
        jsr open

name	.text "filename"

13.7 $FFC3 - CLOSE

Description:	Close a logical file
Implementation:	IDE Extended
Communication registers:	A
Preparatory routines:	None
Error returns:	0, 240 (see errorcodes)
Status:	$00, $03, $80 (see READST)
Registers affected:	A, X, Y

Example:

Close a file

	lda #filenumber	; opened file number
	jsr close

13.8 $FFC6 - CHKIN

Description:	Set standard input
Implementation:	IDE Extended
Communication registers:	X
Preparatory routines:	valid OPEN
Error returns:	0, 3, 5, 6 (see errorcodes)
Status:	$00, $03, $80 (see READST)
Registers affected:	A, X

Example:

Starts to read from a file

	...
        jsr open	; open file

	ldx #filenumber	; opened file number
	jsr chkin	; set input

	ldx #0
        jsr chrin	; get bytes
        sta $400,x
        ...

13.9 $FFC9 - CHKOUT

Description:	Set standard output
Implementation:	IDE Extended
Communication registers:	X
Preparatory routines:	valid OPEN
Error returns:	0, 3, 5, 7 (see errorcodes)
Status:	$00, $03, $80 (see READST)
Registers affected:	A, X

Example:

Starts to write to a file

	...
        jsr open	; open file

	ldx #filenumber	; opened file number
	jsr chkout	; set output

	ldx #0
	lda $400,x
        jsr chrout	; write out data
        ...

13.10 $FFCF - CHRIN

Description:	Get a character from standard input
Implementation:	IDE Extended
Communication registers:	None
Preparatory routines:	valid OPEN, CHKIN
Error returns:	6 (see errorcodes)
Status:	$00, $40, $42, $52, $80 (see READST)
Registers affected:	A (Y but not for file I/O)

Example:

Get in a byte from standard input

	...
        jsr chkin

	ldy #0
	jsr chrin
	sta data,y
	iny
        ...

13.11 $FFE4 - GETIN

Description:	Get a character from standard input
Implementation:	IDE Extended
Communication registers:	None
Preparatory routines:	valid OPEN, CHKIN
Error returns:	6 (see errorcodes)
Status:	$00, $40, $42, $52, $80 (see READST)
Registers affected:	A (X, Y but not for file I/O)

Example:

Get in a byte from standard input

	...
        jsr chkin

	ldy #0
	jsr getin
	sta data,y
	iny
        ...

Wait until a space is pressed

	...
	jsr clrchn	;keyboard/screen
        ...

wait	jsr getin	;get key
	beq wait	;nothing pressed?
        
        cmp #32		;space pressed?

13.12 $FFD2 - CHROUT

Description:	Output a character to standard output
Implementation:	IDE Extended
Communication registers:	A
Preparatory routines:	valid OPEN, CHKOUT
Error returns:	7 (see errorcodes)
Status:	$00, $03, $80 (see READST)
Registers affected:	None

Example:

Put in a byte to output

	...
        jsr chkout

	lda #$00
	jsr chrout	;write 0
        ...

13.13 $FFE7 - CLALL

Description:	Close all files and set standard input/output to keyboard/CRT
Implementation:	IDE Extended
Communication registers:	None
Preparatory routines:	None
Error returns:	5 (see errorcodes)
Status:	$00, $03, $80 (see READST)
Registers affected:	A, X

Example:

Make sure all files are closed before starting.

	jsr clall	; close all files, set default i/o
	jmp run		; run program

13.14 $FFCC - CLRCHN

Description:	Set standard input/output to keyboard/CRT
Implementation:	IDE Extended
Communication registers:	None
Preparatory routines:	None
Error returns:	5 (see errorcodes)
Status:	$00, $03, $80 (see READST)
Registers affected:	A, X

Example:

Set standart keyboard/screen in/output.

	...
        jsr chkin
        ...
        
	lda #1
	jsr close
	jsr clrchn	; set default i/o

13.15 $FFD5 - LOAD

Description:	Load memory from file
Implementation:	IDE Extended
Communication registers:	A, X, Y
Preparatory routines:	SETLFS, SETNAM
Error returns:	0, 4, 5, 8, 9, 16 (see errorcodes)
Status:	$00, $10, $40, $42, $50, $52, $80 (see READST)
Registers affected:	A, X, Y

Example:

Load a file. It's possible to load from $0400 to $FFFF (IDE64 switches $01 memory configuration register automatically if needed).

	lda #1		; filename length
	ldx #<dirnam
	ldy #>dirnam	; filename pointer
	jsr setnam

	lda #1		; file number
	ldx $ba		; actual device number
	ldy #0		; sec.address 0=new location, 1=original location
	jsr setlfs

	lda #$00	; load flag (1=verify)
	ldx #<dirbuff
	ldy #>dirbuff	; new start address
	jsr load
	bcc loadok
	...
	rts

loadok	stx $ae		; new end after load/verify
	sty $af
	...
	rts

dirnam	.text "$"

13.16 $FFD8 - SAVE

Description:	Save memory to file
Implementation:	IDE Extended
Communication registers:	A, X, Y
Preparatory routines:	SETLFS, SETNAM
Error returns:	0, 5, 8, 9, 24 (see errorcodes)
Status:	$00, $03, $80 (see READST)
Registers affected:	A, X, Y

Example:

Save a file. It's possible to save RAM from $0200 to $CFFF. For save ram under the BASIC rom don't forget to set $01!

databegin = $fb

	lda #1		; file number
	ldx $ba		; actual device number
	ldy #0		; sec.address
	jsr setlfs

	lda #8		; filename length
	ldx #<name
	ldy #>name	; filename pointer
	jsr setnam

	lda #<$1000
	sta databegin	; begin
	lda #>$1000
	sta databegin+1
	lda #databegin
	ldx #<$8000
	ldy #>$8000	; end
	jsr save

name	.text "filename"

13.17 $DEF1 - WRITE

Description:	Save data block to IDE device
Implementation:	IDE only
Communication registers:	A, X, Y
Preparatory routines:	valid OPEN, CHKOUT
Error returns:	5, 7, 9 (see errorcodes)
Status:	$00, $80 (see READST)
Registers affected:	A, X, Y

Note: Not possible to save under I/O. (eg. saveing from $D800 will save color ram) To access RAM under the BASIC and KERNAL ROM, set $01 correctly. Saving RAM under the KERNAL ROM is not supported on SuperCPU.

If you want your application using READ/WRITE make runnable on a not IDE64 equiped machine, check for IDE64 presence before calling these two calls, and use standard routines instead of, as described above. (Imagine what happens at JSR $DEF1 if there's open I/O space at $DE00-$DEFF...)

Example:

Detect IDE64 before write and workaround if not present.

	lda $de60	;check ide64
	cmp #$49
	bne old
	lda $de61
	cmp #$44
	bne old
	lda $de62
	cmp #$45
	bne old
	lda #zp
	jsr $def1
	bcc ok
	cmp #9		;illegal device
	beq old2	;tried to use call on non-ide64 device
ok
	...
	rts

old2	ldx #channel
	jsr chkout
old	...		;old byte by byte routine
	rts

13.18 $DEF4 - READ

Description:	Load data block from IDE device
Implementation:	IDE only
Communication registers:	A, X, Y
Preparatory routines:	valid OPEN, CHKIN
Error returns:	5, 6, 9 (see errorcodes)
Status:	$00, $40, $42, $52, $80 (see READST)
Registers affected:	A, X, Y

Note: This routine does not load under I/O. (e.g. reading to $D800 will overwrite color ram)

Example:

Copy a file with read and write

	lda #1		; source filenumber
	ldx $ba		; actual device number
	ldy #0		; secondary address for read
	jsr setlfs
	lda #outputname-inputname
	ldx #<inputname
	ldy #>inputname
	jsr setnam
	jsr open	; open input file

	lda #2		; destination filenumber
	ldx $ba		; actual device number
	ldy #1		; secondary address for write
	jsr setlfs
	lda #status-outputname
	ldx #<outputname
	ldy #>outputname
	jsr setnam
	jsr open	; open output file

	lda #<startadd
	sta $fb
	lda #>startadd	; buffer start address
	sta $fc

	ldx #1		; set input to source file
	jsr chkin

	ldx #2
	jsr chkout	; set output to destination file

loop	lda #$fb	; pointer to zeropage with start address
	ldx #<blocksize
	ldy #>blocksize	; block size
	jsr read	; read
	bit $90		; readst
	php		; status to stack

	lda #$fb
	jsr write	; write
	plp		; status
	bvc loop	; test end of file

	lda #2
	jsr close	; close output file
	lda #1
	jsr close	; close input file
	jsr clall	; set default i/o device
	rts

inputname .text "/bin/input-file"
outputname .text "/tmp/output-file"
status	.byte 0

Errors codes returned by kernal
Accu	Meaning
0	Routine terminated by the `STOP` key
1	Too many open files
2	File already open
3	File not open
4	File not found
5	Device not present
6	File is not an input file
7	File is not an output file
8	File name is missing
9	Illegal device number
16	Out of memory (load)
24	File data error (save)
240	Top-of-memory change RS-232 buffer allocation/deallocation

14 PCLink

Duart/parallel does not work yet, so can't say anymore.

15 Command channel

Will write this a bit more verbose later. Some examples use the dos wedge like "@I", of course the @ at the beginning of line is not part of the command.

15.1 File management commands

For more see chapter Using files.

15.1.1 Position

Seek to file position.

Format:

PRINT#<command lfn>,"P"; CHR$(<file channel>); CHR$(POSITIONBITS0TO7); CHR$(POSITIONBITS8TO15); CHR$(POSITIONBITS16TO23); CHR$(POSITIONBITS24TO31)

Example:

Seek in file to the 100000th byte and read it. (counting begins at 0)

10 OPEN 15,12,15:OPEN 4,12,4,"FILE"
20 PRINT#15,"P"; CHR$(4); CHR$(159); CHR$(134); CHR$(1); CHR$(0)
30 GET#4,A$:CLOSE 4:CLOSE 15

15.2 Filesystem management commands

15.2.1 Initialize

Redetect filesystem and go into root directory.

Example:

@I
00, OK,000,000,000,000

15.2.2 Scratch

Delete a file. For empty directorys use RD. File must have the DELETEABLE flag set, and must be on a writeable partition.

Example:

Delete the file called 'FILE'

@S:FILE
01, FILES SCRATCHED,001,000,000,000

15.3 Partition management commands

15.3.1 Change partition

Partition changing.

Example:

Select partition 2

@CP2
02, PARTITION SELECTED,002,000,000,000

Select partition 3 the other way

OPEN 15,12,15,"C"+CHR$(208)+CHR$(3):CLOSE 15
READY.

15.4 Device management commands

15.4.1 Drive number change

To tempolary change the device number (till next reset) send "U0>"+CHR$(new) to the device. If 'new' is 0 then the device is disabled.

Example:

Use device 12 as 8 from now on

OPEN 15,12,15,"U0>"+CHR$(8):CLOSE15
READY.

15.4.2 Identify device

Sending 'UI' or 'U9' on command channel returns the dos version of the device.

Example:

@UI
73, IDE DOS BETA! IDE64,000,000,000,000

15.4.3 Reset device

Sending 'UJ' or 'U:' on command channel resets (re-detects) the device.

Example:

@UJ
73, IDE DOS BETA! IDE64,000,000,000,000

15.4.4 Power management

It's possible to enter/exit powersaving mode if the device support it.

Examples:

Spin down drive

@U0>P0
00, OK,000,000,000,000

Spin up drive

@U0>P1
00, OK,000,000,000,000

15.4.5 Eject/Load media

More usefull on CDROM/ZIPdrive than on harddisk.

Examples:

Load media

@U0>E0
00, OK,000,000,000,000

Eject media

@U0>E1
00, OK,000,000,000,000

15.4.6 Lock/Unlock media

It's possible to prevent media removal on CDROM/ZIPdrives.

Examples:

Unlock media

@U0>L0
00, OK,000,000,000,000

Lock media

@U0>L1
00, OK,000,000,000,000

15.5 Direct access commands

For more see chapter Direct access.

15.5.1 Buffer read

Format: PRINT#<command lfn>,"B=R"; CHR$(<data channel>); CHR$(HEAD); CHR$(CYLINDERBITS8TO15); CHR$(CYLINDERBITS0TO7); CHR$(SECTOR)

15.5.2 Buffer position

Format: PRINT#<command lfn>,"B=P"; CHR$(<data channel>); CHR$(POSITIONBITS0TO7); CHR$(POSITIONBITS8TO15)

15.5.3 Buffer write

Format: PRINT#<command lfn>,"B=W"; CHR$(<data channel>); CHR$(HEAD); CHR$(CYLINDERBITS8TO15); CHR$(CYLINDERBITS0TO7); CHR$(SECTOR)

15.6 Directory handling commands

For more see chapter Using directorys.

15.6.1 Change working dir

Example:

@CD:NEWDIR
00, OK,000,000,000,000

15.6.2 Make dir

Example:

Create the directory called 'NEWDIR'

@MD:NEWDIR
00, OK,000,000,000,000

16 Command channel error messages

These are the possible returned error messages on channel #15 with their short descriptions.

00, OK,000,000,000,000: No error since last action.
01, FILES SCRATCHED,xxx,yyy,000,000: xxx+yyy*256 files where deleted.
02, PARTITION SELECTED,xxx,000,000,000: Partition number #xxx was selected.
20, READ ERROR,dp1,dp2,dp3,dp4: Unrecoverable read error. Maybe a defective disk.
dp1,dp2,dp3,dp4 is drive specific address of sector.
21, READ ERROR,dp1,dp2,dp3,dp4: Timeout during read.
22, READ ERROR,dp1,dp2,dp3,dp4: Data block not found, or unformatted media.
23, READ ERROR,dp1,dp2,dp3,dp4: Problem with data checksumm.
25, WRITE ERROR,dp1,dp2,dp3,dp4: Verify error.
26, WRITE PROTECT ON,000,000,000,000: Write protected file/dir/partition/media.
28, WRITE ERROR,dp1,dp2,dp3,dp4: Timeout during write.
29, DISK CHANGED,000,000,000,000: Disk change detected.
30, SYNTAX ERROR,000,000,000,000: Syntax error in command. (something is missing...)
31, UNKNOWN COMMAND,000,000,000,000: Unknown/unimplemented command.
32, SYNTAX ERROR,000,000,000,000: Command buffer overflow.
33, SYNTAX ERROR,000,000,000,000: Illegal character in filename.
34, SYNTAX ERROR,000,000,000,000: Missing filename.
39, PATH NOT FOUND,000,000,000,000: Path not found.
50, SEEK BEYOND END,000,000,000,000: Attempt to seek beyond end of file.
62, FILE NOT FOUND,000,000,000,000: File not found in directory.
63, FILE EXISTS,000,000,000,000: File already exists in dir.
67, ILLEGAL REQUEST,dp1,dp2,dp3,dp4: Sector's address out of range.
70, NO CHANNEL,000,000,000,000: Channel number incorrect for block commands.
71, DIR ERROR,dp1,dp2,dp3,dp4: No directory header found.
73, IDE DOS Vx.xx IDE64,000,000,000,000
73, IDE DOS Vx.xx CDROM,000,000,000,000
73, IDE DOS Vx.xx ZIP64,000,000,000,000: Dos version, and drive type.
74, DRIVE NOT READY,000,000,000,000: No disk in drive.
75, FORMAT ERROR,000,000,000,000: Disk not in known format. Use format command/utility.
77, SELECTED PARTITION ILLEGAL,xxx,000,000,000: Partition number #xxx not found/illegal.

17 Compatibility FAQ

17.1 Commodore serial devices

Of course they work. Will include 1541 fastloader later.

17.2 SuperCPU

Should work, not tested on real hardware, only on emulated. The SCPU IDEDOS expects emulation mode with directpage starting at the 0th byte of bank 0, like normal. The high byte of register A is not preserved during operation.

17.3 RetroReplay, Action Replay, Final cartridge

These hardwares use the same I/O space as the IDE64 cartridge, so they won't work.

17.4 RamLink

Should work, but needs more testing.

17.5 CMD HD/FD/etc. (serial)

As these are serial devices they should work. They are supported by the manager too.

17.6 C128

Works in C64 mode. Inits VDC, clears $D02F-$D030. The cartridge is not designed for 2MHz operation, so do not call IDE64 routines in 2MHz mode! C128 keyboard is available if cartridge has cartconfig register and support is compiled in. (Num pad, cursor keys, esc, tab, linefeed are available, help calls monitor, alt and noscroll unused)

17.7 JiffyDOS

It's detected. (tested with v6.01) @#<device> does not work with IDE64 drives without DOS Wedge enabled. (but always uses last accessed drive) With DOS Wedge features are missing ;-) JiffyDos fastload is disabled in the SCPU version (meaning 1/3 loading performance on 1541, but still 2x faster than normal)

Loading and saving is accelerated if the drive has JiffyDos, even if there's no JiffyDOS rom installed in the computer (selectable at compile time). If you get sometimes random "?LOAD ERROR"s when loading directory from a JiffyDOS drive, then that's not a bug in IDEDOS. The original JiffyDOS load routine trys to workaround this by retrying IECIN, and this causes an endless loop until STOP is pressed. I prefer getting an error over waiting forever...

17.8 NTSC/PAL

Both works.

17.9 REU

Works, not touched.

17.10 Second SID

Supported if installed at $D420. (volume 0 is set) This is changeable at compiletime.

17.11 +60K

Works, not touched.

17.12 IEEE-488

Does not work, because the IDE64 cartridge cannot manipulate the EXROM line.

17.13 Turbo 232

Works.

17.14 Software

Forget about autostarting programs...

17.15 CHS/LBA harddisk

Use LBA formatted harddisks if possible, it's much faster to scratch etc. because there's no chs→lba→chs translation, which is slow.

18 More information

The IDE64 project homepage: http://ide64.org/

The IDE64 warez site: http://singularcrew.hu/ide64warez/

Document maintained by:

Kajtár Zsolt
Szigliget
Hóvirág u.15.
8264
Hungary
mail: soci at c64.rulez.org

Foreword

Contents

1 About the IDE64 interface cartridge

2 Set up and begin using the IDE64 cartridge

3 The CMOS Setup utility

3.1 Standard setup

3.1.1 Date, Time

3.1.2 Paper, border, char color

3.1.3 Start boot file

3.1.4 Boot device

3.1.5 1541 fastloader

3.1.6 Set basic clock

3.1.7 Keyboard repeat

3.1.8 Lowercase chars

3.1.9 Use dos wedge

3.1.10 C128 keyboard

3.1.11 Direct write

3.1.12 Accu charging

3.2 Device numbers

3.2.1 LCD display

3.2.2 Serial device x

3.2.3 HDD x

3.2.4 PC-LINK

3.3 Advanced setup

3.3.1 Power management

3.3.2 Retry on error

3.3.3 Write cache

3.3.4 Read look-ahead

3.3.5 Slow down cdrom

3.3.6 Linear read max

3.4 Restore defaults

3.5 Save & exit

3.6 Discard & exit

4 Preparing a blank disk

4.1 The format utility

5 Using partitions

6 Using directorys

6.1 Paths

6.2 Wildcards

7 Using files

8 Direct access

8.1 BLOCK-READ

8.1.1 Reading from a CHS-ATA device:

8.1.2 Reading from a LBA-ATA or ATAPI device:

8.1.3 Getting device identity:

8.2 BLOCK-WRITE

8.2.1 Writing to a CHS-ATA device:

8.2.2 Writing to a LBA-ATA or ATAPI device:

8.3 BUFFER-POINTER

8.3.1 Selecting a byte:

9 The File Manager

9.1 Plugins

9.1.1 Plugin format

9.2 Manager config file

9.3 Manager keys

10 Using the monitor

11 DOS Wedge

11.1 @

11.2 @#

11.3 @$

11.4 /

11.5 %

11.6 ´ (shift 7)

11.7 ^| (up arrow)

11.8 <— (left arrow)

11.9 £ (pound sign)

12 BASIC extensions

12.1 HDINIT

12.2 INIT

12.3 DATE

12.4 KILL

12.5 LOAD

12.6 SAVE

12.7 VERIFY

13 Programming in assembly

13.1 $FFB7 - READST

13.2 $FF90 - SETMSG

13.3 $FFE1 - STOP

13.4 $FFBA - SETLFS

13.5 $FFBD - SETNAM

11.1 `@`

11.2 `@#`

11.3 `@$`

11.4 `/`

11.5 `%`

11.6 `´` (shift 7)

11.7 `^|` (up arrow)

11.8 `<—` (left arrow)

11.9 `£` (pound sign)