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?
- 1.2 Features
- 1.3 Context, scope and intended users
- 1.5 Outline of this document
- 1.6 Related documents
- 2 Installation/uninstall
- 3 Using Dioscuri
- 4 Disk images
- 5 Debug mode
- 6 Support
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.
- 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
- 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
- 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.
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.
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.
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:
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.
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.
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.
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.
|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.|
|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 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|
|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|
|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.|
|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|
|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|
|Size||The size of the Random Access Memory, in megabytes.||1|
|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|
|Update interval||3500 microseconds|
All configuration parameters are stored in an XML-file:
DioscuriConfig.xmlThis file is stored in the config folder. More experienced users may edit this configuration file directly instead of using the graphical configuration panel.
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.
The emulator can be put into debug mode, making it possible to step through the instructions, obtain register values, and information from components (modules).
DioscuriConfig.xmlfile, and find the following line, near the top of the file:
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.
Prints the help with an overview of the debug commands on the console.
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.
Instruction number = 1001
f000:04f7 50 52 8B PUSH_AX
Prints the current contents of all registers on the console, in hexadecimal and decimal format.
ax: 0x402 1026
cx: 0x000 0
dx: 0x543 1347
bx: 0x13d 317
sp: 0xffb0 65456
bp: 0xffb0 65456
si: 0x000 0
di: 0x500 1280
Value of [0xFE05B]: 0x31
Value of [0xFE05C]: 0xC0
Value of [0xFE05D]: 0xE6
Value of [0xFE05E]: 0x0D
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
The previous command will be repeated verbatim.
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.