MyIDE Tool V0.30

(c) 2006-2007 by Matthias Reichl <hias@horus.com>

This program is proteced under the terms of the GNU General Public
License, version 2. Please read LICENSE for further details.


1. What is MyIDE Tool

MyIDE Tool is a program that provides direct access to harddrives
in MyIDE format on your Linux/Windows PC. It will work with IDE
harddrives, with Compactflash cards attached to either a CF-IDE
adapter or to an (USB) cardreader and with images.

MyIDE Tool is still beta, so please report success and/or
failures to me!

For direct harddrive access you need admin privileges, so either
run this program as root (in Linux) or logon as Administrator (Windows).

PLEASE BE EXTREMELY CAREFUL WHEN RUNING MYIDE TOOL, YOU CAN EASILY
TRASH YOUR HARDDRIVE IF YOU WRITE DATA TO THE WRONG DISK DRIVE!

Note: In Windows 95/98/ME direct harddrive access is NOT available,
you have to use a disk imager to dump the whole harddrive to an
image file, then use MyIDE Tool to modify the image, and then
dump the image back to the harddrive.


2. System requirements

First of all, it is absolutely necessary that you have set up your
MyIDE harddrive correctly. If you specified a wrong number of
sectors or heads when partitioning your MyIDE harddrive on the
Atari, MyIDE tool won't work correctly!

Here's an easy way to check if the setup was correct:
On your Atari, copy some disks to image space and assign names
to the images. Then use MyIDE tool to print the list of the images
(see section 4.1). If the list is correct, the setup is most
certainly right.

Another possibility is to backup the partitions to ATR files
and then use an emulator to verify if the ATR files are correct.
Again, if the ATR files work, the setup is most certainly right.

Note: You need at least MyIDE OS version 3.5F or 4.2I/E installed
on your Atari! I haven't tested MyIDE Tool with older OS versions!


3. Installing MyIDE Tool

Windows: just use the precompiled myidetool.exe.

Linux: use the supplied Makefile and just do a
"make dep && make clean && make".


4. Using MyIDE Tool

MyIDE Tool is completely command-line driven. The first parameter
is the path to your MyIDE harddrive or image.

If you start MyIDE Tool without any parameters, a short help
screen will be displayed.

4.1 Finding out which device to use

In Linux lookup dmesg (or /var/log/syslog) to get the name of the device.
For IDE harddrives it will be something like /dev/hdc, USB cardreaders
will show up as SCSI drives (eg /dev/sda).

In Windows, first start MyIDE Tool with the option '--list' to get
a list of all harddrives known to Windows. This list will usually
look like this:

\\.\PhysicalDrive0: 2434/255/63 C/H/S, 19092MB
\\.\PhysicalDrive1: 62/255/63 C/H/S, 486MB

Now you have to find out which of these drive is actually your
MyIDE harddrive. You can either run MyIDE Tool first without your
MyIDE harddrive connected and then a second time with your harddrive
connected and compare the output. Another way is to just try to
read the MyIDE partition table and check if it's correct. As long
as you don't write anything to a drive nothing bad will happen.

In this case, \\.\PhysicalDrive1 is the 512MB Sandisk CF card that
I use for MyIDE.

Note: The C/H/S settings reported by the (USB) cardreader are in
general different from the real C/H/S settings, so don't rely
on this output.

4.2 Listing the partition table and getting a list of the images

Using the command line option '-l' prints the partition table of
the MyIDE harddrive, option '-L' lists all names and densities
of the active image slots. Empty slots (without a name) won't
be printed.

Note: MyIDE Tool reads the command line options one after the
other, it is possible (and usually also convenient) to execute
more that one function when invoking MyIDE Tool.

This example will print the partition table and a list of all
active image slots:

(Linux) myidetool /dev/sda -l -L
(Windows) myidetool \\.\PhysicalDrive1 -l -L

4.3 Working with MyIDE images and partitions

MyIDE Tool supports both partitions and images and offers (almost)
identical functionality for both of them. At first, you have
to specify if you want to access partition space or image space,
then you may select the function (backup data to ATR file(s) or
write ATR file(s) to the MyIDE harddrive).

To select a partition, use the option '-p <number>', where <number>
is a value from 1 to 8.

To select an image slot, use '-i <number>'. The first image slot
number is 1, the last slot number depends on the size of your image
space.

Once you have selected the partition/image number, you may select
the operation:

'-B' backs up all partitions/images starting from the first selected
image/partition number to ATR files. Partitions are copied to
partitionN.atr (where N is the physical partition number). When
backing up images, the name is extracted from image space and
the file is autmatically named <imagename>.atr.

'-b file...' backs up one or more partitions/images to ATR file(s).
If you specify more then one filename, the image/partition number
will be automatically incremented. For example:

myidetool /dev/sda -i 2 -b games.atr tools.atr

will back up image slot 2 to "games.atr" and image slot 3 to "tools.atr".

'-w file...' copies ATR files from the PC to the MyIDE harddrive.
To copy a bunch of ATR images directly to image space, you may
use something like this:

myidetool /dev/sda -i 20 -w *.atr -L

This will copy all ATR files from the current directory to image slots
20, 21, ... and then print a list of all images.

When writing ATR files to image space, the image name will be automatically
set from the name of the ATR file, and the density (SD/ED/DD) is also
set.

Whenever you write an ATR file to your MyIDE harddrive MyIDE tool
performs some sanity checks: In partition mode it checks if the
density of the ATR file matches the density of the partition
(SD/DD) and if the number of sectors is less than or equal to
the maximum partition size. In image mode the ATR file must be
either in single density (720 SD sectors), enhanced density
(1040 SD sectors) or double density (720 DD sectors). Other ATR
files are rejected.

Note: you can force myidetool to ignore the image size check
(for example if you want to write a 800 sectors DD image to an
image slot) by using the "-fi" option. MyIDE will most likely be
able to read this image fine, but you won't be able to read such
an image back with myidetool or any other software. So, use this
option at your own risk!

If you back up a partition, the resulting ATR file may be larger than
what you would expect. This is not a bug in MyIDE Tool but has to do
with the way MyIDE sets up partition information:

When you create a new partition, the actual partition size will be
rounded up so that the partition ends on a cylinder boundary.
If you only use partitions with 65535 sectors, you won't notice
anything in MyIDE tool (the maximum image size is always limited
to 65535 sectors). But if you created a partition with less than
65535 sectors, you'll see the actualy partition size in the MyIDE
Tool partition listing. For example, I created a 50000 sectors
partition with the MyIDE fdisk. On my CF card this is partition
uses 50 cylinders, which results in a maximum total of 50400 sectors.

So, when I back up this partition, MyIDE Tool will create a 50400
sectors ATR file.

If you don't like this behaviour, you may specify the maximum
sector number using the '-s <number>' command line option
(number is a value from 0 to 65535).

Note: this option is used for all subsequent image backup
operations (including the '-B'/"backup all" operation), use a
value of 0 to disable the maximum sector number setting.

With '-e number' (or '-e start-end') you can erase the image description
of image slots. It doesn't touch the actual image data, just the additional
information (name and density setting).

4.4 MyIDE Image Manager support

Note: you need to use MyIDE Image Manager version 4.1 or newer, older
versions store the data in an unsupported format (and also at some
other locations).

Starting with version 4.1 the image manager stores all it's data in
the very last image slot in standard double density format. This means
you can easily back it up (and restore it) with MyIDE tool.

Just use the '-l' option to list the partition table and then note
the number after "total slots: ". If you list the image slots with '-L'
you'll also notice that this slot is named "MyIDE Imager Manager Config".
You can also remove the image manager data by overwriting the last slot
with an empty double density ATR image.

Use the option '-IL' to list the contents of the image manager table.
If no table is present on your drive, you'll get an error message.
Each line starts with the image category (in brackets), follwed by
the image status: at first the density (S/E/D), then a 'B' if basic
is enabled and, optionally, an 'X' if the image is marked as deleted.

If you already stored some images on the drive, use the "-Ii" option
to create an empty table and import all image descriptions into
the table. MyIDE tool scans the image information and stops at the
first unused slot. All images will then be assigned to the first
available category.

With '-II' you can create a completely empty table (for example if
you want to start over again from scratch).

Note: Both the '-Ii' and '-II' options wipe out all previous image
manager configuration and reset the category names to their defaults,
so use them with care!

The '-IC' option prints a list of all currently defined categories,
including the number (1-20) and the name. You'll need this number for
the '-Ic' option.

If you write new images to your drive, they are put into the first
category. With '-Ic number' you can select another category. The
category number has to be 1..20, use '-IC' to get a list of all
categories.

Use the '-Ib' option to set the "enable basic flag" when writing
images to your drive. The default is basic disabled. You can also
clear this flag by using '-IB', for example if you want to write
some images that require basic and then write images that don't
require basic, in a single run.

When image manager support is enabled (by using any of the '-I...'
options), the next image slot that is not used by the image manager
will automatically be selected. You don't have to set the slot number
manually with the '-i number' option if you just want to add images
to your drive. Of course, you may use the '-i number' option to
overwrite any previously stored images that are already under image
manager control. In this case the existing category information will
be preserved for this slot, unless you use the '-Ic number' option.

Note: The image manager requires that all slots are used consecutively.
You'll get an error if you enabled image manager support and specify
an illegal slot number. For example: if you have currently 10 images
in the image manager table you may write to slots 1-10 (to overwrite
an image) and to slot 11 (to add a new image to the image manager).
Of course you are still able to write to any arbitrary image slot
number if you don't enable image manager support.

With the '-Is...' options you can sort the image manager table.
'-Is' and '-Isn' sort by name, '-IsN' sorts reverse by name,
'-Isc' by category number, '-IsC' reverse by category number and
'-Iss' by slot number. These options just sort the table entries,
all images will stay at their original slot numbers, like the
sort function in the image manager, just a lot quicker :-)

Now for some examples: To copy a bunch of images to your drive,
assign them to category 2, and then sort all images by name,
use something like this:

myidetool /dev/sda -Ic 2 -w *.atr -Is

4.5 Writing movies to a MyIDE drive

Using the option "-m" you can easily write a video file (*.mov)
and an audio file (*.raw) to a MyIDE drive and then use Mr. Atari's
video player to play it. Writing a movie now is only a matter of
a few seconds instead of hours compared to Mr. Atari's video
write tools.

The '-m' options requires 3 additional parameters. The first
parameter is the starting cylinder, the second parameter the
movie file (*.mov) and the third parameter is the audio file
(*.raw). For example:

myidetool \\.\PhysicalDrive1 -m 800 atari_matrix_64x216.mov atari_matrix.raw

This writes the 'Matrix' movie to starting cylinder 800.

If you are using a compact flash card (or a device supporting the
compact flash commands), you can also write the movie in a special
mode that uses 512 bytes per sector instead of 256 bytes per sector.
This means, the full capacity of the compact flash card can be used
and the movie occupies only half of the sectors compared to normal
mode!

To write a movie in this mode, use the option '-mc' instead of '-m'.
For example:

myidetool \\.\PhysicalDrive1 -mc 800 atari_matrix_64x216.mov atari_matrix.raw

Note: To play movies written in this mode you need a special movie
player. The default movie player by Mr.Atari doesn't support compact
movies! A player is included in the src directory, named 'gray.src'.

You need ATasm to assemble the movie player on the PC. Look at
the very beginning of the file for configuration setting. You
may either edit the file directly or add command line options
to ATasm to assemble multiple, different movie players (eg
one for each movie stored on your harddrive/CF-card. For example:

atasm -DWIDE=1 -DCFMODE=1 -DSTARTCYL=1500 -DFRAMES=623 -otroncf.com gray.src

This will assemble a movie-player for the "tron" movie, enable wide
screen on startup and enable compact flash mode. The starting cylinder
is 1500 and after 623 frames the movie will restart automatically.

You can also write movies in non-standard formats (different resolutions,
no audio etc) by manually setting the number of (256 byte) audio and
video sectors per frame. The standard movie format uses 3 audio sectors
and 27 video sectors per frame. To change this, use the '-ma num' and
'-mv num' switches to set the audio and video sectors, respectively.
Note: you have to specify the format _before_ the '-m' (or '-mc')
option.

For example, if you want to write a movie with 4 audio sectors and
16 video sectors per frame use the following command line:

mydetool \\.\PhysicalDrive1 -ma 4 -mv 16 -mc 800 movie.mov audio.raw

Note: you may also write silent movies (without audio) or audio
only (without a video stream) if you set either '-ma 0' or '-mv 0'.
In this case you don't need to specify an audio/video file.
For example:

mydetool \\.\PhysicalDrive1 -ma 0 -mv 24 -mc 800 movie.mov

You can also "abuse" the movie writer to write arbitrary raw data
to your MyIDE drive. Just set '-ma 0 -mv 1' (in standard mode)
or '-ma 0 -mv 2' (in compact flash mode) and use '-m' / '-mc'
with your raw data file.

4.5 Overcoming command line limitations

On all systems there's a limitation to the maximum length of a command
line. If you specify more options/filenames/... than this limit
you'll either get an error ('too many arguments' or similar) or the
command line will be truncated (some time ago I got this behaviour
in Windows, without an error message - quite annoying...).

Usually you run into this limit if you use wildcards (eg *.atr).

To overcome this limit, MyIDE Tool supports reading command line
parameters (options and filenames) from a file. Just put all
options and/or filenames in a plain text file and then use
this file with '@filename'. Note: each line of this file must
contain exactly one option or filename - using multiple options
in a single line doesn't work! Empty lines are ignored.

For example: create a text-file 'mybackup' with the following contents:
-p 1
-B
-i 1
-B

and then use MyIDE Tool like this:
myidetool \\.\PhysicalDrive1 @mybackup

To copy a large set of images to your MyIDE harddrive, do this:
dir /b *.atr | sort > imagelist
myidetool \\.\PhysicalDrive1 -i 1 -w @imagelist

Note: I don't recommend putting the harddrive device into the
list, it may change if you alter your system and then you
would (accidentally) overwrite the wrong harddrive...

