--------------------------------------------------------------------------------
IBM PC Emulator
Copyright (C) 1998-2020 Kris Bleakley
email: kindred@crazysmart.net.au
--------------------------------------------------------------------------------

Last updated 28th December 2020

Table of Contents

i.  Disclaimer
1.  Introduction
2.  System Requirements
3.  Getting Started
4.  Configuration (config.ini)
    4.1  System BIOS
    4.2  AT Real Time Clock
    4.3  AT Keyboard Controller
    4.4  Adding a Floppy Drive
    4.5  Adding an IDE Hard Drive
    4.6  XTIDE
    4.7  Configuring RAM
    4.8  Video Display Adapter
         4.8.1  Monochrome Display Adapter
         4.8.2  Color Graphics Adapter
         4.8.3  Enhanced Graphics Adapter
         4.8.4  Video Graphics Array
    4.9  Sound Blaster 2.0 DSP
    4.10 Sample listing
5.  Known Issues
6.  Missing Features
7.  Hardware bugs
8.  Software bugs


/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\


i. Disclaimer (Please read before operating software)

This product is provided free of charge and therefore on an "AS IS" basis,
without warranty of any kind, express or implied, including without limitation
the warranties that it is free of defects, virus free, able to operate on an
uninterrupted basis, merchantable, fit for a particular purpose or
non-infringing. This Disclaimer of warranty constitutes an essential part of
this agreement. No use of the product is authorised hereunder except under this
disclaimer. This product is for non-commercial use only and shall not be
packaged with any commercially licensed software.


/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\

1. Introduction

The IBM PC emulation core was introduced in September 2016. Thus far it is the
most complex system emulated by kindred.

Emulation is still in its infancy and I have not yet began to optimize the code.
If emulation seems a little slow, it could be that the scheduler is handling
more than 36,000,000 task switches per second.

It is interesting to note that initial hardware testing of an 8088 has already
revealed differences between offical documentation and the hardware under test.
I shall endeavour to list differences at the end of this document once testing
is complete.


/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\

2. System Requirements

Requirements may differ depending on the configuration of the emulated system
(i.e, a system emulating a VGA display card will run hotter than a system
emulating a CGA display card).

It is recommended that you limit the number of programs running in the background
as this software uses a lot of CPU time while running. 

Minimum System Required

* Intel Quad Core 2.4GHz or equivalent processor
* 256MB Available System Memory
* 1GB Available HDD space
* Microsoft Compatible Mouse and Keyboard
* Microsoft Windows 7
* Microsoft Direct-X 8


/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\

3. Getting Started

Before you start emulating your desired flavour of PC, you will need two BIOS
files. These two files are required to emulate the system.

What is a BIOS file?

BIOS is an acronym for Basic Input/Output System. This is a piece of software
(written by the manufacturer of the computer) stored in Read Only Memory (ROM).
The purpose of the BIOS is to initialize (test) the hardware and ready the
computer for transfer to a Disk Operating System (DOS).

The two BIOS files required are the system BIOS (located on the main board)
and the video BIOS (located on a video card attached to the main board).

During the lifetime of the IBM PC XT/AT a number of video standards were
devised and implemented. These video standards include but are not limited to
the Monochrome Display Adapter (MDA), the Color Graphics Adapter (CGA), the
Enhanced Graphics Adapter (EGA) and the Video Graphics Array (VGA).

Note: Due to copyright these files are not provided with this software.
      A suitable BIOS may be located with the help of an internet search engine.

Note: Make sure the video BIOS matches the specified video standard.
      An incorrect video BIOS will produce undesired results and may cause the
      emulated system to stall or report Power On Self Test (POST) errors.

Two classes of IBM PC are currently supported, XT class and AT class. The IBM
PC/XT had three system BIOS revisions while the IBM PC/AT had two system BIOS
revisions. BIOS revisions developed by third parties may also work.

Emulation is started by selecting "start" from the system menu, followed by the
desired class.


/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\

4. Configuration (config.ini)

The "system" section should contain the two variables "xt_class" and "at_class".
These two variables are used to specify which section will be used to configure
each class of IBM PC.

Example:

[system]
xt_class=IBM5160
at_class=ATCLONE

Note: While an infinite number of configurations may be defined in config.ini,
      only one per class is selectable for use (at this time).

4.1 System BIOS (ROM required)

As mentioned in "Getting Started", the system will not function without a BIOS.
The "bios_rom" variable is used to specify the location of the BIOS file.

Example:

[IBM5160]
bios_rom=ibm\xtbios3.bin

4.2 AT Real Time Clock

The IBM AT added the Real Time Clock (RTC) to the system board. The RTC has
additional RAM which is battery backed and used by the BIOS to store parameters.
The "rtc" variable is used to specify the location of the backup RAM.

Example:

[ATCLONE]
rtc=ibm\atclone.rtc

Note: This file will be created if it does not exist. The BIOS will report a
      checksum error the first time it is run and on consecutive resets until
      valid parameter data is detected.

4.3 AT Keyboard Controller (ROM required)

The IBM AT introduced the keyboard controller (Intel 8042) to the system board.
This allowed the system to send commands to and from the enhanced keyboard of
the IBM AT. The keyboard controller also provided additional functionality such
as enabling/disabling the A20 gate and hard resetting the CPU.

As well as supporting the original specification, some manufacturers extended
the functionality of the keyboard controller. The "kbdc_rom" variable is used to
specify the location of the keyboard controller ROM file.

Example:

[ATCLONE]
kbdc_rom=ibm\kbdc.bin

4.4 Adding a Floppy Drive

Two floppy disk drives are currently supported. 'fdd0' is used to specify the
first drive (drive A) and 'fdd1' is used to specify the second drive (drive B).
The following options are available for use:

0   no floppy drive
1   low density (5.25")
2   high density (5.25")
3   low density (3.5")
4   high density (3.5")
5   extra high density (3.5")

Example:

[IBM5160]
fdd0=4
fdd1=0

Floppy disk images can be mounted from the "system" menu.

Note: The BIOS must support the drive configured otherwise disk errors may be
      encountered. Attempts to mount a 3.5" disk in a 5.25" drive or vice versa
      will result in general failure disk errors.

4.5 Adding an IDE Hard Drive

The IDE specification includes an identify command used to request information
about a hard drive. This information can be stored in a file and its location
used to configure each hard drive. "ide0" is used to specify the first hard
drive (drive C) and "ide1" is used to specify the second hard drive (drive D).

Example:

[IBM5160]
ide0=ibm\xtide0.dat

Note: A number of IDE data files are included in the "ide" directory. It will
      be dependant on the BIOS and operating system as to which hard drive
      specification can be used.

A virtual hard drive image will be created to match the name of data file with
a '.vhd' extension. All the necessary steps should be taken when adding a hard
drive to the system (BIOS, partitions, format, etc).

When the disk image is created only sectors containing data will be written.
The formatting tool may or may not write data to the disk image. To expand the
disk image, run a disk tool such as SCANDISK.EXE. A full surface scan will
expand the disk image to its capacity. Once the image is expanded it can be
loaded into a disk editing tool such as winimage.

4.6 XTIDE (ROM required)

An XTIDE interface is emulated in the case of an XT class system. The interface
requires an adapter ROM to allow IDE drives to function on an XT class system.
The "rom" variable under the "XTIDE" section is used to specify the location of
the adapter ROM.

Example:

[XTIDE]
rom=ibm\xtide.bin

The XTIDE Univeral BIOS is free software released under the terms of the GNU
General Public License. See http://www.xtideuniversalbios.org/ for more
detailed information and downloads.

4.7 Configuring RAM

"ram_size" shall be used to configure the total amount of system ram. The value
assigned should be a factor of 64. Each class has an upper limit, "xt_class" is
limited to 640K, "at_class" is limited to 5120K.

Example:

[ATCLONE]
ram_size=1024

4.8 Video Display Adapter

"slot0" is used to configure the video card. "IBM_MDA", "IBM_CGA", "IBM_EGA"
and "IBM_VGA" are recognised values. Each value has a designated section to
configure the video adapter. More options will be available when more chipsets
are added.

Example:

[IBM5160]
slot0=IBM_CGA

4.8.1 Monochrome Display Adapter (ROM required)

The IBM Monochrome Display Adapter (MDA) was the first video adapter developed
for the IBM PC. The adapter was only capable of displaying text. Characters were
generated from ROM which stored an 8x8 and 8x16 character set.

The "rom" variable under the "IBM_MDA" section is used to specify the location
of the character ROM.

Example:

[IBM_MDA]
rom=ibm\char.bin

4.8.2 Color Graphics Adapter (ROM required)

The IBM Color Graphics Adapter (CGA) was the first colour adapter developed for
the IBM PC and the first to display bitmap graphics. The Color Adapter used the
same character ROM used for the IBM Monochrome Display Adapter. The adapter
also produced a composite video signal.

The "rom" variable under the "IBM_CGA" section is used to specify the location
of the character ROM.

Example:

[IBM_CGA]
rom=ibm\char.bin

4.8.3 Enhanced Graphics Adapter (ROM required)

The IBM Enhanced Graphics Adapter (EGA) was the first colour graphics adapter
to display graphics in 16 colours. It came standard with 64K of RAM, upgradable
to 192K with an optional memory expansion daughter board. The enhanced adapter
could be configured to work with a CGA or EGA monitor by dip switches at the
rear of the card. The adapter was the first IBM PC video adapter to have a BIOS
stored in ROM.

The "rom" variable under the "IBM_EGA" section is used to specify the location
of the video BIOS.

Example:

[IBM_EGA]
rom=ibm\video\ibm_ega.bin

4.8.4 Video Graphics Array (ROM required)

The IBM Video Graphics Array (VGA) was the first colour graphics adapter to use
a video DAC capable of displaying 256/256K colours. The adapter was fitted with
256K of video RAM and also had a video BIOS stored in ROM.

The "rom" variable under the "IBM_VGA" section is used to specify the location
of the video BIOS.

Example:

[IBM_VGA]
rom=ibm\video\ibm_vga.bin

4.9 Sound Blaster 2.0 DSP (ROM required)

The Sound Blaster 2.0 used an Intel 8051 or equivalent as its command processor.
A ROM is required to decode/process DSP commands. The variable "dsp_rom"
defined under the "CT1350" section is used to specify the location of the ROM.
"base", "irq" and "volume" are also defined to configure the DSP.

Note: The Sound Blaster DSP will be disabled if the ROM can not be located.

Example:

[CT1350]
dsp_rom=ibm\audio\sb.bin
base=$220
irq=5
volume=15

Values for "base" are $220 (default) or $240.
Values for "irq" are 2,3,5 (default) or 7.
Values for "volume" are 0 through 15 (default).

The ROM from an original SB2 card has not yet found its way on to the internet.
The ROM from a clone sound card can be found at the following address:
https://github.com/schlae/snark-barker/tree/master/firmware

Note: The hex file located at the above address needs to be converted to binary.

4.10 Sample listing

[system]
xt_class=IBM5160
at_class=ATCLONE

[IBM5160]
ram_size=640
bios_rom=ibm\xtbios3.bin
slot0=IBM_CGA
fdd0=1
fdd1=1
ide0=ibm\xtide0.dat
ide1=

[ATCLONE]
ram_size=2048
rtc=ibm\atclone.rtc
bios_rom=ibm\atclone.bin
kbdc_rom=ibm\kbdc.bin
slot0=IBM_EGA
fdd0=2
fdd1=4
ide0=ibm\atide0.dat
ide1=

[IBM_CGA]
rom=ibm\char.bin

[IBM_EGA]
rom=ibm\video\ega.bin

[XTIDE]
rom=ibm\xtide.bin

[CT1350]
dsp_rom=ibm\audio\sb.bin
base=$220
irq=5
volume=15

xtide0.dat and atide0.dat are default values.

Note: The above information is a work in progress and is subject to change in
      future releases as more options are made available.


/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\

5. Known Issues

The IBM AT BIOS does not support IDE hard drives.
The IBM AT BIOS revision 2 will not work due to a CPU speed limitation.
The IBM AT BIOS will only support high-density floppy diskettes if and only if
a combined Fixed Disk Floppy Diskette controller card is found.

NOTE: There are plenty of AT clone BIOS's that will work with IDE hard drives.

PC-DOCTOR DOS (2004) will lock-up or reset a 80286 CPU on loading.


/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\

6. Missing Features

Here is a list of some the features that are not yet implemented in this version
but I will endevour to add them some time in the not so distant future. This
list will most likely become larger over time.

* Numeric Processor
* BCD Mode (PIT)
* RTC DS/BCD/12hr mode, Periodic Interrupt, Alarm Interrupt (IBM AT)
* Accurate CPU timing (IBM XT/AT)
* IBM XT Keyboard Reset (disabled due to inaccurate CPU timing)
* 101 Enhanced Keyboard
* Protected Mode Exceptions (IBM AT)
* CGA Emulation (EGA/VGA)
* Horizontal Panning (EGA/VGA)
* 512 Character Mode (EGA/VGA)
* Video Mode Q (EGA/VGA)
* Wrong Cylinder Flag (FDD)
* Adlib Sound Card
* Sound Blaster (FM operator)
* CD-ROM drive support


/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\

7. Hardware Bugs

Here are some of the hardware bugs I have uncovered so far.

* NEC 8253: Output not set high in mode 2.  If the counter is equal to 1 and gate
  transitioned from 0 to 1 during the previous cycle, output is not adjusted.
  Mode 6 does not have the bug. (D8253-2, D8253-5)

* Yamaha YM3812: Feedback is glitched when the value is greater than 4.
  I have only tested one chip, it may be a fault in the chip I am testing.
  The chip under test is from a Sound Blaster 2.0.


/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\

8. Software Bugs

Here are some of the software bugs I have uncovered so far.

* TEST-SBP.EXE: (Version 1.80) If the FM driver fails the keyboard interrupt is 
  not restored when the driver is unloaded.

* Some early BIOS's write user hard drive parameters to the interrupt table which 
  can cause problems for some diagnostic programs such as Microsoft Diagnostics.


