User manual Dioscuri

Date: 18 March 2010
Emulator version: 0.5.0
Manual version: 1.5
Organisations: Koninklijke Bibliotheek, Nationaal Archief of the Netherlands
Written by: Bram Lohman, Jeffrey van der Hoeven, Bart Kiers

Table of contents



1 Introduction

1.1 What is Dioscuri?

Dioscuri is an X86 computer hardware emulator written in Java. It is designed by the digital preservation community to make sure that documents and programs from the past can still be experienced in the future. To do so, this emulator has two key features above any other emulator: it is durable and flexible. Durable because it can be ported to any other computer platform which has a Java Virtual Machine (JVM) without any extra effort. This reduces the risk that the emulator fails to work on one computer system in the future, because it will continue to work on another.
Dioscuri is also flexible because it is completed component-based, just like a real computer. Each hardware component is emulated by a software surrogate called a module. Combining all modules allows the user to configure any computer system (if compatible). Add a new module or upgrade another one and the emulator is capable of running it.

1.2 Features

Dioscuri version 0.3.0 offers a wide range of emulated computer components. The complete list is shown below:
  • 16 and 32-bit X86-based CPU (real-address and protected mode)
  • 1 MB RAM (expandable)
  • Storage devices: floppy, HDD
  • Input devices: XT/AT/PS2 compatible keyboard, serial mouse
  • Output devices: virtual screen
  • VGA video graphics adapter
  • DMA-support
  • IRQ-handling based on a Intel 8259 PIC
  • Timing mechanism based on an Intel 82C54 PIT and Crystal Clock
  • Real-time clock with integrated CMOS
  • RS232 Serial port based on UART 16550A
  • System BIOS using Plex86/Bochs BIOS
  • Video BIOS using VGA LGPl’ed BIOS

1.3 Context, scope and intended users

Dioscuri is developed by the digital preservation community to ensure that documents, games and other applications will remain accessible, not only now but also for the long term. As Dioscuri is open source and free to use, distribute and modify anybody can use this application for their own benefit. Currently, Dioscuri is focused on retaining access to older computer environments, like MS DOS or earlier versions of Linux.

1.4 License (terms of use)

Dioscuri is released under the GNU GPL version 2.0. This means that you can use, distribute and modify the application for your own benefit. Changes made to the applications should be open source as well under the same conditions as this application. The copyrights of Dioscuri belong to the Koninklijke Bibliotheek (National Library of the Netherlands) and Nationaal Archief (Nationaal Archief of the Netherlands).

1.5 Outline of this document

This document describes the system requirements, installation, and main functionality of the emulator Dioscuri. It includes a walkthrough of a simple example describing some commonly used aspects of the system. This document does not cover the software design or user requirement specifications. References to this information can be found under the section "Related documents" in this file.

1.6 Related documents

The following related documents can be found on the "Documents" section on the Dioscuri website:
  • The System Maintenance Guide, describes how to maintain the system.
  • Architectural Design Document, describes the design of the software.
  • Object Design Document, describes the design in more detail.
  • The Software Requirements Document, specifies the behaviour of the software system.


2 Installation/uninstall

2.1 System requirements

Dioscuri is a cross-platform application and therefore requires the Java Platform SE (Standard Edition) Runtime Environment be installed, version 1.6 or higher.
The Java Runtime Environment (JRE) can be downloaded from the Sun Microsystems website, www.sun.com. Installation instructions for the JRE can also be found on the website. Other producers of JREs exist as well and can be used, but may result in different program behaviour.
Furthermore, Dioscuri requires several Megabytes of free hard disk space and a variable amount of RAM (depending on the configuration settings you define). More hard disk space may be required depending on the volume of disk images that are used.

2.2 Requiring the software

Dioscuri can be required by downloading the software package from the website http://dioscuri.sourceforge.net

2.3 Install

Download the latest version from the website and extract this package into a new folder on your computer. Dioscuri does not require any further installation and is now ready for use.

2.4 Uninstall

Uninstalling Diosuri can be done by simply removing the folder in which the application resides.
Note: beware that disk images and configuration file stored within this folder will be lost as well! Move them to another folder to save them.


3 Using Dioscuri

3.1 Quick start guide

To start the application, type the following command at the command line:

java -jar dioscuri.jar
If .jar-files are associated with your Java Runtime Environment, double clicking on the file .jar-file may work as well.
Windows users can also start the emulator by clicking on dioscuri.bat

Set at least the following parameters from the "Configure->Edit Config" menu:

BIOS
The System BIOS file and Video BIOS file need to be set for the emulator to boot properly. Distributed with the system are two open source BIOSes, the Bochs System BIOS (BIOS-Bochs-latest) and the LGPL'd VGABios, VGABIOS-lgpl-latest. These files are located in the images/bios folder and should be sufficient to boot the system.
The BIOS start locations should be left at the default values, 983040 and 786432 respectively.

Boot
The boot menu indicates which device will be used to boot an operating system after the BIOS has finished booting, and can be either floppy or hard disk. A bootable disk will need to be provided in either the floppy or hard disk menu for this to be successful.

ATA/FDC
A boot disk needs to be provided for either the hard disk or floppy disk, to successfully boot once the BIOS has finished. The image file can be selected by choosing either ATA or FDC (Floppy Disk Controller) and clicking ‘Image File’, and then selecting the appropriate disk image. The geometry for the disk image must be selected as well; in case of floppy this is the disk size, and for ATA this needs to be specified in cylinders/heads/sectors per track.

Start the emulator via Emulator -> "Start process". The system and Video BIOS will boot, followed by the boot device set in the configuration file.

3.2 Start guide

To start the application, type the following command at the command line:

java -jar dioscuri.jar
If .jar-files are associated with your Java Runtime Environment, double clicking on the .jar-file may work as well.
Windows users can also start the emulator by clicking on dioscuri.bat

This will open a new window with the Graphical User Interface (GUI). The command line will display various messages, such as the version info, module information, status information, etc. If any errors occur during the running of the emulation process, they will be displayed on this screen. The output of the systems run in the emulator will be displayed on the GUI window; this is also where all the parameters can be set.

To run the emulator successfully, the configuration parameters must be set up properly. These parameters are covered in detail in section "Configuring Dioscuri".

Note: the parameters can only be changed if the emulator is not running. Select "Emulator->Stop process (shutdown)" to stop the emulator, if necessary.

Start new emulation process
Once the configuration is set up properly, the emulator can be run by selecting Emulator -> Start process, after which the system and Video BIOS will boot. Once these BIOSes have finished executing, they will pass control over to the selected boot device set in the configuration; this is either the floppy or the hard disk.

Changing floppy disks
During the emulation process it is possible to change the floppy disk. To do this, select "Media->Eject Floppy A:", at which point the image reference to the floppy in drive A: is removed. Another floppy disk can then be attached by selecting "Media->Insert Floppy A:". From the dialog, a new image file can be selected that will be ‘inserted’ into drive A:.

Note: the new floppy disks must be compatible with the drive type selected in the configuration at start.

Reset emulation process
The emulator can be reset during operation by selecting "Emulator->Reset process (warm reset)". This reset is similar to a software (Ctrl-Alt-Del) reset, in that not all parameters of the emulated components will be erased.
Only completely stopping and restarting the emulator ("Emulator->Stop process (shutdown)", "Emulator->Start process (power on)") will reset all emulated hardware completely.

Stop emulation process
The application can be stopped by selecting the Emulator->Quit option from the menu. This will shut down the emulator immediately; data written to floppy disks during the emulation process this will not be saved to the disk image! This does not hold for hard disk images. Writing to hard disk images will directly effect the image.

Note: to save changes on virtual floppy disks before shutting the emulator down, select "Emulator->Stop process (shutdown)", which will write any outstanding data to the attached floppy image files before stopping the emulator.

3.3 Configuring Dioscuri

The configuration for the emulator allows various settings for the different components to be changed. For each component, several parameters can be set. The table below provides a description for each of these parameters.

ATA/IDE
Parameter Description Default
Update interval The interval, in microseconds, indicating how often the device will be polled for new data. The update interval is a function of the CPU speed, as this is used to calculate the number of instructions that will elapse during each interval. 100.000 microseconds
Enabled Enables/disables the hard disk availability to the emulator. Essentially ‘disconnecting’ the hard disk from the emulator. Enabled
Channel index The ATA channel on which the hard disk will be connected; this can be any value from 0 – 3. 0
Master Selects if the current hard disk will be master or slave. Master
Auto detect Enables/disables auto-detecting the number of cylinders in the geometry of the hard disk from the image file size. Enabled
Cylinders The number of cylinders in the hard disk geometry. If auto-detect is enabled, this value will be ignored.
Heads The number of heads in the hard disk geometry.
Sectors The number of sectors per track in the hard disk geometry.
Image file The location of the image file to be used as hard disk.

BIOS
Parameter Description Default
System bios file The location of the image file to be used as system BIOS. images/bios/BIOS-bochs-latest
Video bios The location of the image file to be used as Video BIOS. Images/bios/VGABIOS-lgpl-latest
System BIOS start The location in memory (in decimal) at which the system BIOS will be loaded. F000:0000, which is 983040 decimal
Video BIOS start The location in memory (in decimal) at which the VGA BIOS will be loaded. C000:0000, which is 786432 decimal

Boot
Parameter Description Default
Boot device 1 Determines which device will be used as a first boot device when the BIOS has finished executing. Harddisk
Boot device 2 Determines which device will be used as a second boot device when the BIOS has finished executing and no proper first boot device can be found. None
Boot device 3 Determines which device will be used as a second boot device when the BIOS has finished executing and no proper first and second boot devices can be found. None
Floppy check disabled Enables/disables the floppy boot signature check (0xAA55) done by the BIOS for bootable floppy disks. Enabled

CPU
Parameter Description Default
16/32 bit Defines if the CPU should run in 16-bit or 32-bit mode. 32-bit
Speed A measure (in MHz) of the number of instructions per second the cpu will execute. This value influences the update intervals of the hard disk, floppy disk, keyboard and video card. 5

FDC (floppy
Parameter Description Default
Update interval The interval, in microseconds, indicating how often the device will be polled for new data. The update interval is a function of the CPU speed, as this is used to calculate the number of instructions that will elapse during each interval. 250 microseconds
Enabled Enables/disables the floppy drive availability to the emulator. Essentially ‘disconnecting’ the floppy drive from the emulator. Enabled
Inserted Enables/disables the insertion of a floppy disk into the floppy drive. Inserted
Drive letter Sets the drive letter for the floppy drive. A
Disk format Selects the type of disk that will be inserted into the floppy drive. 1.44
Write protected Enables/disables the write protect function of the floppy disk. Setting this disable any writing to the inserted floppy disk. Disabled
Image file The location of the image file to be used as floppy disk.

Keyboard
Parameter Description Default
Update interval The interval, in microseconds, indicating how often the device will be polled for new data. The update interval is a function of the CPU speed, as this is used to calculate the number of instructions that will elapse during each interval. 200 microseconds

Mouse
Parameter Description Default
Enabled Defines if the mouse is enabled or disabled under emulation. disabled
Type Defines the type of mouse: serial or PS/2. Currently, only serial mouse is supported (experimental) serial

Memory
Parameter Description Default
Size The size of the Random Access Memory, in megabytes. 1

PIT
Parameter Description Default
Clock rate The time, in milliseconds, indicating how the interval between two clock pulses is. This rate is independent of any other interval or timer. 1 millisecond

Video
Parameter Description Default
Update interval The interval, in microseconds, indicating how often the device will be polled for new data. The update interval is a function of the CPU speed, as this is used to calculate the number of instructions that will elapse during each interval. 3500 microseconds

All configuration parameters are stored in an XML-file:
DioscuriConfig.xml
 This file is stored in the config folder. More experienced users may edit this configuration file directly instead of using the graphical configuration panel.


4 Disk images

Dioscuri only supports virtual media, which means it does not give access to physical storage devices. Instead, a disk image has to be created from the original physical carrier (floppy or hard disk). This can be done using image creation tools, like WinImage.
Dioscuri currently supports two types of virtual carriers: floppy disks and hard disks.

4.1 Floppy disk

A floppy disk image should be an uncompressed linear binary file (flat file) and should not be larger than 1.44 Megabytes.

4.2 Hard disk

Harddisks can be of any size (although the file system will limit the amount of available space). Just like floppy images, hard disk images have to be uncompressed linear binary files (flat files).


5 Debug mode

The emulator can be put into debug mode, making it possible to step through the instructions, obtain register values, and information from components (modules).

5.1 Enable debug mode

To enable debug mode, open the DioscuriConfig.xml file, and find the following line, near the top of the file:
<emulator xmlns:xsi="..." debug="false" xsi:...>

Change the value of ‘debug=false’ to ‘debug=true’ and start the emulator as usual. Once the emulator has been started via "Emulator->Start process (power on)", the console will display the first instruction to be executed and wait for user input.

5.2 Debugging commands

The table below describes the commands that can be used while in debug mode. For each command, values in square brackets (‘[ ]’) is optional, while a value in chevrons (‘< >’) is mandatory.


h
Prints the help with an overview of the debug commands on the console.

s [number]
Step through the instructions.
If no argument is provided, one instruction will be executed. With an argument, the number provided will be the number of instructions executed. When finished, the total number of instructions, as well as the current location in memory (in hexadecimal), as well as the next three bytes and the next instruction to be executed will be printed on the screen.
Example:
Instruction number = 1001
f000:04f7 50 52 8B PUSH_AX

r
Prints the current contents of all registers on the console, in hexadecimal and decimal format.
Example:
ax: 0x402 1026
cx: 0x000 0
dx: 0x543 1347
bx: 0x13d 317
sp: 0xffb0 65456
bp: 0xffb0 65456
si: 0x000 0
di: 0x500 1280
ip: 0x4f7
flags 0x46
cs: 0xf000
ss: 0x000
ds: 0x000
es: 0x000

m <address> [bytes] Displays the contents of the memory at specified address and [bytes] long. If no bytes argument is provided, two bytes will be shown. Example:
Value of [0xFE05B]: 0x31
Value of [0xFE05C]: 0xC0
Value of [0xFE05D]: 0xE6
Value of [0xFE05E]: 0x0D

d <module type> Dumps the status of a component (module) onto the console. Valid components types are: ata, bios, clock, cpu, dma, fdc, keyboard, memory, motherboard, parallelport, pic, pit, screen, serialport, video
Example:
Clock dump:
Timer 0: ata, updateInterval=500000, countdown=500000
Timer 1: fdc, updateInterval=1250, countdown=1250
Timer 2: keyboard, updateInterval=10000, countdown=9800
Timer 3: vga, updateInterval=17500, countdown=17300

[Enter]
The previous command will be repeated verbatim.


6 Support

If you have still questions after reading this user manual, please take a look at the Dioscuri website under "Support". A FAQ and forum is available. If this does not answer your question you can contact the Dioscuri development team via the website.


screenshort Dioscuri
Dioscuri
Downloads
Documentation
Support
Development
Contact