Introduction
IMPORTANT NOTICE : All the programs presented here have been replaced by the Aufit project and therefore are not maintained anymore.
This page contains information about several programs that I have written around the images produced by the KryoFlux controller board produced by KryoFlux Products & Services Limited. My experience with the Kryoflux hardware is described in "The Kryoflux Device".
KryoFlux and Software Preservation Society (SPS) already provide all necessary information for the usage of the board with different platform (Amiga, PC, Atari, etc.). Therefore the focus of this page is to provide technical information for developers that want to write programs around the Kryoflux. Therefore you will find here several technical documentations and programs that I have written based on SPS and KryoFlux documents and sources.
This is related to the subject of Atari FD protection and to preservation. For more generic information on this subject please refer to Atari Floppy Disk Preservation page.
Results of Analysis of protected Atari Floppy Disk can be found in the Analysis of Kryoflux images page
Back to the topThe Stream Protocol / Format Documentation
The following document provides a description of the Stream Files content (as produced by firmware 2.0) produced by the DTC (Disk Tool Console) program connected to a KryoFlux Device. The document also provides assistance on Decoding or Encoding Stream Files. It is based on my understanding of the KryoFlux documentations published by Software Preservation Society and KryoFlux Product & Services Limited but it also includes information based on experimentations and programing (using sources provided by SPS). I want to thanks István Fabián from SPS who has provided to me with a lot of detailed information on how KryoFlux device operates and on the source code used to decode a Stream File.
The Stream internal content is described in the following document:
Note: Regular user of the KryoFlux device should not be concerned by the information presented in this document which is mainly of interest to programmers that want to write tools around the Stream Files.
Back to the topCreating Atari FD Images with KryoFlux
The main goal of the KryoFlux device is to create images of FD for preservation. The imaging process is done with the command line DTC software or through the DTC GUI. The DTC program come with a documentation on how to use it.
Basically if you are trying to image Atari floppy disks you should use the minimum following command:
- dtc -f<name> -i0 -i2 -i4
Where <name> is the name of the program you want to image. Basically the -i2 option is required for preservation and the -i4 option is recommended as it forces to KryoFlux device to performs retries when it has problem reading a track. In most cases this is caused by a protection mechanism but sometimes it can happen if the FD is dirty. Using this flag results in a longer imaging time, because many retries are performed, but this is a small price to pay to get more accurate images.
I have modified the original doDump.bat batch file provided by SPS. This new batch file is called AtariDump.bat and is tailored for Atari users. It fills for you many default values suitable for Atari and it uses the -i4 switch so you get perfect images of Atari FD. By default the name of the game that you enter is used to create a directory and stream files (the spaces are removed) but you can specify another name if you want. The stream files uses the following name <game_name>(current_disk-max_disk)track.head.raw and a <game_name>.txt file that contain the information you have entered is created in the same directory.
For example if you enter "Maniac Mansion" as the name of the game, and if the game has two discs, a directory called ManicMansion (note that the space is removed from the name) is created and in this directory you will find the following files:
- ManiacMansion.txt with all the information you have entered
- ManiacMansion(1-2)00.0.raw to ManiacMansion(1-2)83.1.raw for all the tracks of disk 1
- ManiacMansion(2-2)00.0.raw to ManiacMansion(2-2)83.1.raw for all the tracks of disk 2
This is also the recommanded way to create images for usage with the KFPanzer program as this program is expecting the stream file using the above naming convention.
New: The DTC program display a lot of useful information on the screen but unless you stay stuck in front of your screen all this information is lost! Therefore I have added the option to log all the messages (both stdout and stderr) to files that you can read later. These files are created in the game directory and have the format <game_name>(current_disk-max_disk).log
For example with the above example two files will be generated: ManiacMansion(1-2).log & ManiacMansion(2-2).log
Back to the topKryoFlux Programs & Programming
Here are some development that I have done around the KryoFlux board. Stay tune for more
- I have documented the KryoFlux Stream Format with lots of details for programmers
- I have developed 2 libraries and 3 programs around the KryoFlux board
:
- KFStream library decodes the content of a stream file and provide an extremely simple interface
- KFCheck checks validity of stream file and can dump the content of the file (uses KFStream libary)
- KFEmul runs on top of KFStream and interprets the Stream information (flux transitions) as a WD1772 FDC would do. It provides a simple interface to emulate the read track, read address, and read sector commands of the FDC.
- KFAnalyze interprets the content of a stream file as a WD1772 FDC would do and provides plot capabilities
- KFPanzer analyzes and lists all the protections found on an Atari FD
The provided program and libraries are for Windows only (any version of Windows should work). For the program development I recommend that you use the free Visual Studio from Microsoft for the C/C++ and the Doxygen program for documentation.
If you are not familiar with the usage of external lib in VC++ programs development you can refer to this documentation from Microsoft.
Important: Normally you should not have to install anything to use the executables. However if you are getting a message like msvcp100.dll is missing you need to install the Microsoft Visual C++ 2010 redistribuable package.
Back to the topKFStream Library
As the name indicates this library provides an easy API to access all the decoded information from a Stream file. The KFStream library is based on source code originally written by SPS that I have modified and it is released assources for Visual C++. (not released)
The KFCheck Program
This not a very useful program but I did it mainly to validate and demonstrate how easy it is to use the KFStream library.
This program uses the KFStream library to fully decode a Stream File (it supports the Stream file format produced by version 2.0 of the firmaware) and checks its content for consistency. The program will detect if something went wrong during the transfer of the data from the KryoFlux device to the connected PC and it allows to dump in ASCII the content of the stream file. This program should run on any version of Windows (tested on Windows 7 X64). At the end of the excution the program also outputs the average transfer rate over the USB link, the number of revolutions used for Imaging the track, the minimum, average, and maximum values for the Rotations Per Minute (RPM), and the number of flux transitions for one track.
You will find several test cases here + a simple test case of KryoFlux firmware v2.0 thanks István (use the -n option on this one)
Back to the topThe KFEmul Library
This library decodes the information from a Stream file using the KFStream library and provides several functions that processes the flux reversals as a Western Digital WD1772 FDC (emulation) would do. For that matter the input transitions are pipelined through a DPLL (digital phase lock loop), a shift register, and an address mark detector. The program is based on the work I did many years ago around the Discovery Cartridge (some ideas and code where done more than 20 years ago!) but has been completely rewritten in C++.
The program analyzes all the flux transitions from an input stream files and provides three main functions:
- The read_track function: In this function all the flux transitions of the Stream file are decoded as a WD1772 FD controller would do with a read track command. At the end of the analysis both the “layout” of the track as well as the content of the track buffer are available.
- The read_address function: In this function the program decodes from the stream file all the ID blocks of the track as a WD1772 FDC would do with multiple read address commands. At the end of the analysis the “layout” of the ID as well as the content of the ID buffers are available for all the IDs found.
- The read sector function: In this function the program decodes from the stream file a specific sector as a WD1772 FD controller would do with a read sector command. Each sector is in fact decoded as many times as the number of rotation analyzed by the KryoFlux DTC program. This is necessary to check if the sector contains fuzzy bytes. At the end of the analysis the “layout” of the Sector as well as the content of the Sector buffer are available for all the sectors analyzed.
The KFEmul library also provide the capability to produce "plot files" to be used with the Ploticus program as well as powerful automatic functions to find all the disk copy protection mechanisms used on the decoded track. (not released)
Back to the topThe KFAnalyze Program
This program is built on top of the FKEmul and KFStream libraries. It is provided as an executable but the sources are also provided as an example of how to use the KFEmul library.
The program analyzes a raw Stream File and "decode" the transitions in the file as a Western Digital WD1772 floppy disk controller would do.
Execution is done in three main phases:
- The read track phase: In this phase all the flux transitions of the Stream file are decoded as a WD1772 FD controller would do with a read track command. At the end of the analysis both the “layout” of the track as well as the content of the track buffer are displayed.
- The read address phase: In this phase the program decodes from the stream file all the ID blocks of the track as a WD1772 FDC would do with multiple read address commands. At the end of the analysis the “layout” of the ID as well as the content of the ID buffers are displayed for all the IDs found.
- The read sector phase: In this phase the program decodes from the stream file all the sectors found in the read address phase as a WD1772 FD controller would do with a read sector command. Each sector is in fact decoded (read) multiple times corresponding to the number of rotation analyzed by the KryoFlux DTC program. This is done to check if the sector contains fuzzy bytes. At the end of the analysis the “layout” of the Sector as well as the content of the Sector buffer are displayed for all the sectors analyzed.
The program is also capable of creating plots of the track and sectors.
- KFAnalyze program. Please report problems to DrCoolZic
- KFAnalyze user's manual
- Ploticus scripts to plot outputs produced with KFAnalyze program
- Ploticus 2.41 for Windows 32 bits (also works fine on Windows 7 X64) - or get it directly from the Web Site here
You will find in the page Analysis of Atari KryoFlux Images several examples of analysis of Atari games with the KFAnalyze program as well as several test cases.
The KFPanzer Program
This program is built on top of the FKEmul and KFStream libraries. It is provided as an executable but the sources are also provided as an example of how to use the KFEmul library.
The KFPanzer (KryoFlux Protection ANalyZER) checks and prints the floppy disk copy protection mechanisms found on an Atari Floppy Diskette. The FD first need to be imaged as a set of Stream files produced by a KryoFlux board from KryoFlux Products & Services Ltd.
A detail description of all the protections checked can be found in my document “Atari Floppy Disk Copy Protection Based on Key Disk”. However a short description of the protection detected can be found in the KFPanzer user's manual. This program is very handy to automatically check all the protections on a set of Floppy Disks that compose a game/program. It is a companion to the KFAnalyze program.
- KFPanzer program. Please report problems to DrCoolZic
- KFPanzer user's manual
- AtariDumpLog.bat script file to image all floppies of a game for use with KFPanzer