Patching DOSBox by a Beginner for Beginners

In order to apply a patch to DOSBox, you must first be able to compile DOSBox from its source.  Start with this tutorial :

http://www.dosbox.com/wiki/Building_DOSBox_with_Visual_C_2008_Express

The link for Visual C++ 2008 Express given in that tutorial is out of date, you can obtain the downloader from here :

http://go.microsoft.com/?linkid=7729279

When you can compile a binary using the current SVN, then you are ready to begin patching DOSBox.

Patching DOSBox means you are making changes in the existing source code and recompiling DOSBox with those changes into a new binary.  First you need a copy of the source code you are modifying.  DOSBox is written in C++ and the source code is in almost plain text.  You can find the latest source here : http://source.dosbox.com/dosboxsvn.tgz.  Decompress it with a program like 7zip (it is doubly compressed), and look at the files.  The .cpp files contain most of the code you may be modifying.  

Next you need a good text editor, preferably one that supports line numbers.  Notepad just does not support enough of the formatting these files need.  Wordpad does, but you would do better with an editor like EditPad Lite 7, which supports line numbering.  Line numbering is very useful to determine which lines of code you need to modify.  

Finally, you need a patch file.  Patch files often use the .diff extension because they show the differences between two files or two sets of files.  If the patch is just code posted in a forum, you should copy and paste it into a new file opened in Wordpad or EditPad or something similar.  Maintaining the spacing in these files is important.  

Here is a sample patch file against the current DOSBox SVN (r3858) :  

--- adlib.cpp.old   2013-01-15 12:10:04 +0000

+++ adlib.cpp   2014-01-19 19:54:06 +0000

@@ -227,10 +227,10 @@

       Bitu i, val;

       /* Check the registers to add */

       for (i=0;i<256 font="" i="">

-         //Skip the note on entries

-         if (i>=0xb0 && i<=0xb8) 

-            continue;

          val = (*cache)[ i ];

+         //Silence the note on entries

+         if (i>=0xb0 && i<=0xb8) 

+            val &= ~0x20;

          if (val) {

             AddWrite( i, val );

          }

The first two lines identify the source file that was modified, in this case adlib.cpp.  Find and open adlib.cpp using your text editor in the DOSBox source directory.  It can be found in \dosbox\src\hardware.  This is what the existing source code looks like :

Bitu i, val;

/* Check the registers to add */

for (i=0;i<256 font="" i="">

//Skip the note on entries

if (i>=0xb0 && i<=0xb8) 

continue;

val = (*cache)[ i ];

if (val) {

AddWrite( i, val );

}

The next line in the patch file, @@ -227,10 +227,10 @@ pinpoints the lines in adlib.cpp that were modified.  Look for line 227 in the source code file or search   Sometimes, depending on the patcher's working source, the line number may not line up exactly with the DOSBox source, but it should be very close to the line.  Sometimes code looks similar, if you are unsure whether you have the right code, then copy as much of the code from the patch file as you can into a find box and search the source code file until you are sure you have the right lines.  

The lines with blank space in front of them show the existing code that will not be modified.  This is important to know where you will begin to modify and where you will end.  Lines beginning a - indicate that that line was deleted by the patch.  Conversely, lines beginning with a + indicate that that line was added by the patch.  From our example above, these lines were deleted : 

-         //Skip the note on entries

-         if (i>=0xb0 && i<=0xb8) 

-            continue;

In the original source file, highlight and delete them.  Remove the lines entirely so the code looks like this :

       Bitu i, val;

       /* Check the registers to add */

       for (i=0;i<256 font="" i="">

          val = (*cache)[ i ];

Now add these lines after val = (*cache)[ i ]; :

          //Silence the note on entries

          if (i>=0xb0 && i<=0xb8) 

             val &= ~0x20;

Copying and pasting usually gives better results than retyping.  Make sure the code fits where it is indicated and does not overwrite any lines without a - in front of them.  Also make sure, since your text editor must be using a fixed-width font, that the lines line up vertically as shown in the patch.  Do not forget the { and }.  The + characters also should be removed, and add an extra space to the line to preserve the code's position on the line.  Here is the code as it should look in the patched adlib.cpp file :

       Bitu i, val;

       /* Check the registers to add */

       for (i=0;i<256 font="" i="">

          val = (*cache)[ i ];

          //Silence the note on entries

          if (i>=0xb0 && i<=0xb8) 

             val &= ~0x20;

          if (val) {

             AddWrite( i, val );

          }

Once you are done, save the modified .cpp file.  There may be more than one place in the .cpp file to patch, so go to the next line indicator, which looks like @@ -227,10 +227,10 @@ and continue patching. .diff files can include more than one source code file to patch, so make sure you patch all source code files indicated by the .diff.  

Go back into Visual C++ 2008 Express Edition, open the DOSBox solution, and build a new binary.  If you have previously built a binary, then it will not take long as only the changes made by the patch need to be recompiled.  

While there are utilities that can do this for you, I have never gotten one to work properly and sometimes the line numbers do not match and you need to manually patch the code.  

More complex patches may require substantial modifications to the code, or may also require adding completely new code files.  They may also require new libraries and includes files, which are beyond the scope of this tutorial.  

Influences of the PCjr. - the IBM PC Convertible

The IBM PC Convertible, Model 5140, was IBM's first attempt at a battery-powered laptop.  Of course, it was thick, had a small screen, and expansions made it longer.  However, it does share more than a few similarities with an earlier of the PC family, the IBM PCjr.  While it took ideas from the PCjr. and improved on them in many respects, the system was not a great success due to its own issues, namely its high price and less-than impressive specifications compared with competitor's products of the time. The introduction of the 3.5" disk drive on this system, when all software had previously been released on 5.25" disks, meant that it took time for the market to release PC compatible software for the machine.  Also, if the chicklet keyboard was the Achilles Heel of the PCjr, the Convertible's initial low-contrast LCD gave it a bad reputation.  Later machines used a super twist LCD and a backlit LCD, both offering much improved readability, but like the PCjr., it was too little, too late.

Keyboard - The original IBM PC Keyboard used 83 keys.  The PCjr. Cordless Keyboards use 62 keys and the PC Convertible uses 78 keys (U.S. style).  The fewer keys make handling these keyboards with low-level routines quite different from the IBM PC keyboard.  Both the PC Convertible and the PCjr. use the Non-Maskable Interrupt to generate IBM PC Keyboard compatible scan codes.

In an IBM PC, serial data from the keyboard is sent to the system unit, deserialized by a shift register and then placed in I/O port 60, the 8255 PPI Port A0.  IRQ1 is used to signal the CPU that there is a key to be read.  A program can read the raw scancode directly or execute INT 09H/INT16H to obtain an extended ASCII scancode.

In the IBM PCjr., serial data sent from the keyboard is sent to bit 6 of I/O Port 62, 8255 PPI Port C0.   The NMI is generated to alter the CPU that there is a key to be serviced and the CPU deserializes the data stream, then INT 48H is executed to translate the raw scancode into codes compatible with INT 09H/INT16H.  IRQ1 is never used, but the translated scancodes appear at I/O port 60.

In the PC Convertible, the raw scancode is placed in I/O Port 07D.  An NMI is generated and the NMI handler will translate the raw scancode into a compatible scancode and stores the result in I/O Port 60 and generates IRQ1 and the key can be read with INT 09H/INT16H.  While obviously derived from the PCjr., this is an obvious improvement over the PCjr.'s slow routine and should be much more compatible with programs expecting PC keyboard handling.

Memory Expansion - Neither the PC Convertible nor the PCjr. were intended by IBM to reach 640KB, both were intended to max out with 512KB.  Memory expansions for both machines came in 128KB.  IBM officially only supported the Memory Expansions for the PCjr. (128KB in system unit + 3 x 128KB expansions), but the fourth expansion was easy enough to add.  IBM only physically supported four memory modules in the PC Convertible, each with 128KB, and the system always came with two installed from the factory.  Third party expansions were required for the PC Convertible to reach 640KB and recommended for the PCjr. to reach 640KB.

Feature Expansion - Both machines were expanded by hardware attachments, the PCjr. via sidecars that fit onto a connector on the right side of the machine, the PC Convertible by slices that attached to a connector on the rear of the machine. These attachments had a port of the opposite gender to allow the next device to be attached after it. IBM released five PCjr. attachment options, parallel, power, memory, speech and cluster, and four for the PC Convertible, serial/parallel, CRT display, speech and portable printer.  If customers did not particularly care for adding onto the length of the PCjr. they must have positively detested the added weight and length that the add-ons for the Convertible added.

Modem - IBM included a modem slot in the PCjr.  It sold a modem based on the Novation Smart 103 modem for the PCjr, which could run at 110 or 300 baud.  It did not sell well because it was not Hayes compatible.  IBM also included an internal modem socket in the PC Convertible.  Apparently ignoring the market again, IBM used the same style of modem for the PC Convertible internal modem upgrade.  This time the modem could also support 1200 baud.

The COM ports were similarly assigned on both systems.  The PCjr. had a serial port built in and it was assigned to COM1, but the resources were at 278/03.  Once the modem was installed, the serial port became COM2 and the modem COM1 at 3F8/04.  The PC Convertible Internal Modem always used 3F8/04 and would be assigned to COM1 when it was installed.  This time, IBM knew enough that not everyone would install the internal modem, so the PC Convertible had a serial adapter that could be set to COM1 3F8/04 if no internal modem was installed or COM2 2F8/03 if it was

CGA Support - The PCjr. had only basic, BIOS CGA support since it did not implement the crucial Color Select and Mode Control registers.  Although the PC Convertible uses a CGA-friendly 640x200 LCD resolution, the built in video is not particularly CGA compatible either.  Color text-mode attributes were not supported on the monochromeLCD, it was either normal video, reverse video or no display.  320x200 graphics would display three shades of gray plus black, but the graphics take up the whole screen, meaning they are twice as wide as they should be.   The built in LCD does not distinguish between 640x200 and 320x200 in this instance.  The MC6845 was only emulated enough for the basic modes, the color select register is not present and the mode control register has missing bits compared to real CGA.

The built-in display adapter can also be configured to emulate a MDA card.  When the CRT Display adapter is attached to the PC Convertible, it will function like an MDA card and the CRT Display adapter should provide 100% CGA compatibility.  The Display adapter has three video output ports, a Direct Drive port using an 18-pin BERG connector with pinouts identical to the PCjr's Direct Drive video port (except no audio).  The adapter can connect directly to the PCjr. Color Display, Model 4863 or the PC Convertible Color Display, Model 5145.  It can connect to an IBM PC Color Display, Model 5153 or IBM PC Enhanced Color Display, Model 5154 or any other compatible display via the PCjr. 18-BERG to 9-pin DE-9 adapter.  It also has a composite video output like the PCjr. and a 6-pin BERG connector for an RF adapter.  The BERG connector has a compatible pinout with the PCjr. RF switch.

Printer - Both systems had a printer designed specifically for it, the IBM PC Compact Printer for the PCjr. and the IBM Portable Printer for the PC Convertible.  Both are unidirectional thermal serial printers operating at a maximum of 1200 baud and have a 2K buffer.  Both use a transmission format of 1 start bit, 8 data bits and 2 stop bits.  The Convertible's character set includes text-drawing characters at ASCII 176-223 which the Compact Printer does not.  The PC Compact Printer can print in standard, condensed, double-wide and underline styles and 480-bit graphics, while the Portable Printer adds emphasized, superscript and subscript styles and 960 and 1920 bit graphic modes.  The Portable Printer supports virtually all the control codes of the Compact Printer plus some more for its enhanced features.

Speech Attachment - The Convertible's Speech Attachment is supposed to be functionally identical to the PCjr's.

Introduction to the PCjr., or How NOT to Destroy It!

IBM PCjr. Startup Screen - Maximum RAM Count (but you can have more)

Congratulations!  You have just won a PCjr off ebay, scored one off craigslist, took one from the recycling center or was given one by Uncle and Aunt Lots-o'-Stuff in the Attic.  Its just arrived, you open the box, unwrap all the pieces, now what do you do with it?

First Things First : To use a PCjr., you need, at a minimum the system unit, the keyboard and the power cable.  If you are missing any one of these three, the PCjr. is useless.  I am going to go through each in terms of simple to complex :

The External Power Adapter: This is a large black power converter.  It has wires on either end.  One the end of one wire is a three-pronged plug.  On the other end is a rectangular three pin connector that connects to the back of the system unit.  The port is in between the A and the C ports.  On early bricks, the cable with the three-pronged plug is detachable from the large brick.  A standard three-pronged computer power cable should fit into the brick.  The brick only supports 120v/60Hz AC power, so in Europe you will need a step-down converter.  It outputs AC power, the AC to DC conversion is done inside the system unit.  The power cable can fit into the system either way (polarity is irrelevant for AC).

The Cordless Keyboard : The original Cordless Keyboard, later known by everybody, even IBM as the "chicklet" keyboard is the less common of the two IBM PCjr. Cordless Keyboards, especially after IBM offered a free trade in to the non-chicklet keyboard.  IBM called the replacement keyboard the "Freeboard", presumably because it offered some freedom from the frustration of the chicklet and was a free replacement for PCjr. owners who hated the chicklet keyboard.  Internally, they function identically.

The PCjr. Cordless Keyboards use rubber-dome technology and can feel stiff yet squishy.  The keyboard communicates with the system via an infrared sensor or via an optional keyboard cable.  It takes 4 x AA batteries, and you should check the battery compartment to see if there are old corroded batteries.  If there are, you should clean the contacts with cotton swabs or Q-tips with apple cider vinegar or lemon juice and follow it up with baking soda.  You may need to unscrew the board to inspect for leakage on the PCB.  The infrared can work up to twenty feet away according to IBM, but line of sight must be maintained and the sensor on the keyboard should be as perpendicular as possible to the sensor on the computer.  Rechargeable batteries may or may not provide reliable power for the keyboard.

The System Unit : The computer is inside on a large system board.  Most PCjr's you will find these days are the Enhanced Model, which come with a 5.25" diskette (floppy disk) drive and a 64KB memory expansion.  These have 128KB of RAM total, not counting any extra memory added via sidecar.  The Basic Model did not come with a diskette drive or the 64KB memory expansion.  If you are getting a boxed unit, it should come with all the above and two books, the first being the PCjr. Guide to Operations and the second being the "Hands On BASIC for the IBM PCjr."  A complete unit should also come with a plastic plate to cover the sidecar expansion and a Basic Model also comes with a plastic cutout to cover the floppy bay hole.

Checking for damage : The expansion ports on the rear of the PCjr. use BERG-style connectors, which little more than pins bent at right angles sticking out from the system board.  These are more prone to damage than connectors set in a D-shell, but it was cheaper for IBM to implement them in this way.  Check for any bent, broken or pushed in pins.  Most of the connectors have a missing "key pin", so check below to discover pins that are supposed to be missing.  Gently straighten or pull out any pins with a small pair of pliers or tweezers.  Expansion cables are held in the port by friction alone, so do not try yanking cables out. Similarly, the sidecar expansion port also uses pins, but at least these are cased in a plastic connector like an IDE port.

Opening the case : The case top is held down by friction and tabs, there are no screws to deal with.  Using a small screwdriver, insert it into each of the three indentations at top rear edge and gently pop that portion of the case off.

Inside the case : There are up to four internal expansion boards.  Fortunately each can only fit one way.  There are no jumpers or dipswitches inside or on the internal expansion board.  IBM did not use jumpers (officially) on its sidecar expansion board either.  Everything is configured in software, which was rather progressive for the time and technology.  If you want a true definition of plug and play, here it is!

On the left side of the unit (with the cartridge ports facing you), is the power board, which is always present.  The power board comes in either a 33W short card or a 45W long card.  If the power card is about 2/3rds the length of the case, it is the short card.  If it extends nearly to the front of the case, it is the long card.  There is a 2-pin staking connector which the power board must be inserted into when it is put back in its slot.  There are grooves in the case to stabilize the card, make sure the card fits into them.

The second board is the 64KB Memory and Display Option.  As its name suggests, this adds 64KB to the 64KB on the motherboard for a total of 128KB inside the System Unit.  Early memory boards are covered in a metal shield, later boards are just a bare PCB.  If this board is not present, you will only have 64KB of RAM in the system and a big hole if any sidecar memory expansions exist.

The third board is the PCjr. Internal Modem Option, and as it was always an optional upgrade, it probably won't be present in your average PCjr. System Unit.  IBM's modem was not very popular since it only communicated at 300 baud and did not use the industry standard Hayes command set.  Third party Hayes-compatible modems were also made to fit in this slot.  Like the power board, this card connects to a 2-pin staking connector and grooves in addition to its slot.  This is the only internal upgrade not to come automatically bundled with the PCjr. System Unit.

The fourth board is the PCjr. Diskette Adapter.  This connects to the Diskette Drive via a 34-pin ribbon cable with a pin header on one end and a card edge connector on the other.  It only supports the one internal drive.  Note the side of the cable with the colored wire, that side must correspond to pin 1 on the board if the diskette drive is going to work properly.  Pin 5 is missing on the adapter pin header as a key pin to prevent wrongful insertion.

The diskette drive is mounted on a unique plastic drive support.  It is connected to the board by two standoffs that push through the bottom of the case.  To remove the drive support mechanism (and the drive itself), first unplug the cables for the diskette drive power connector and the fan power connector from the power board.  Next, disconnect the drive data cable.  Next, with a pair of pliers, squeeze the tabs in and push upwards on the standoffs until the constrict and pop up from the bottom of the case.  These are not screws, so do not twist a screwdriver in them.  Finally, pull up on the back of the diskette drive and it should be able to be lifted out of the system with no further difficulty.

If you have removed all the internal boards and the diskette drive support, you will have complete access to the interior of the PCjr.  Check for any signs of damage and be prepared to dust.  There is a raised metal box on a small PCB, that is the Infrared Receiver.  Make sure it is firmly seated on its slot.  The receiver is connected to the System Unit by its connector and two plastic standoffs, so you won't be able to remove it without removing the System Unit itself.  The System Unit can be removed from the case by unscrewing four screws at the rear of the system, at least one screw holding down the cartridge ports and removing whatever sidecars are attached.

Rear Expansion Ports :

Except for the RCA ports for video and audio and the modem port (if one is installed), there is nothing standard about the PCjr.'s expansion ports.  However, the hardware that the PCjr. is designed to connect to is standard with one exception.  Looking at the rear of the machine, the ports are lettered as follows :

J   J   L   K   LP    T             V      M   D         S        C      P    A

J = Joystick - There are two joystick ports in the PCjr., with the first port,  sometimes called the right joystick being closest to the edge of the System Unit.  The inner port is sometimes called the left joystick.  These connect to the PCjr. Joystick, which functions just like a standard PC joystick.  The PCjr. joystick just uses a different connector.  River Raid, Demon Attack and Microsurgeon will not work without a joystick connected.  8-pins, with Pin 1 missing as the key pin.

L = Spare - These pins are not connected to anything on the system board. 6-pins, with pin 4 missing as the key pin.

K = Keyboard - For the optional Keyboard Connector.  The keyboard connector has a phone jack on one end and a large RFI ferrite choke.  It plugs into the PCjr. keyboard and allows you to use the keyboard without IR and batteries.  Third party keyboard replacements also plug into this port, but must be specifically designed for the PCjr.  If there is anything plugged into this port, then the system unit will not receive the input from the IR receiver, even if its just an unconnected wire.  6-pins, with pin 1 missing as the key pin.

LP =  Light Pen - IBM never marketed a light pen with a PCjr. style connector, but PC Enterprises did.  6-pins with pin 6 missing as the key pin.

T = Television - For the TV Connector, an RF switchbox to connect to an antenna screw terminal on a TV.  You may need a 300 to 75 Ohm balun connector.  External Audio can be heard from this connector. 6-pins, with pin 2 missing as the key pin.

M = Modem - A standard RJ-11 phone jack connector will be found here if you have an internal modem installed, otherwise it is just a hole.

V = Video - RCA Composite Video jack, better than RF, but not as sharp as :

D = Direct Drive Video - This connector supplies a CGA-compatible video signal and a mono audio signal.  The standard IBM PC Color Display Model 5153 or IBM Enhanced Color Display Model 5154 or compatible monitors can connect to it via a 9-pin adapter.  IBM released one because its PCjr. Color Display was not available at launch.  The IBM PCjr. Color Display Model 4863 has a connector that plugs directly into this port.  The IBM PCjr. Color Display has a built-in speaker with a volume control wheel for the external audio output.  The IBM PC Convertible Color Display Model 5145 also uses the same connector as the PCjr. Color display, but may or may not have a speaker for the external audio.  18-pins.  An adapter exists to allow the PCjr. and Convertible displays to work with a 9-pin D-shell port.

S = Serial - Any serial device can use this port with a proper adapter, such as from IBM.  The only device I know of that has the connector for this port is the IBM PC Compact Printer.  An adapter exists to allow the Compact Printer to be used with a standard serial port.  16-pins.

C = Cassette - IBM made a cable to interface with cassette drives and cassettes for data storage and retrieval.  It has two mini-jacks and one micro-jack.  The cassette interface is functionally identical to the interface in the IBM PC Model 5150.  8-pins, with pin 5 missing as the key pin.

P = Power Connector - See above

A = Audio - RCA Mono Audio Jack, necessary to hear sounds from the external audio unless you are using the TV Connector or the 4863 PCjr. Color Display.

Cartridge Ports :

On the front of the machine, there are two cartridge slots.  These slots are functionally identical.  Like any cartridge slot, they can accumulate dust and should be cleaned with a Q-tip and 99% Isophropyl Alcohol.  The most common cartridge that can be found is the BASIC cartridge (IBM Cartridge BASIC).  This cartridge is intended to supplement the Cassette BASIC already in the system ROM and add support for the advanced sound and video capabilities of the PCjr. and diskette drive support.  Game cartridges are generally rare, especially the good ones from Activision and Imagic.  Lotus 1-2-3 is a rare example of a cartridge program with a cartridge for both slots.

Sidecar Port :

On the side of the PCjr., there is the expansion port of the system, the sidecar port.  If there are no sidecars installed, there may be a plastic faceplate, which snaps into two holes and can be easily pried off with a screw driver or fingers.  Sidecars are pushed onto the pins, then screwed into system unit or the next sidecar with a flat head screwdriver.  You can extend the length of your system quite considerably with expansion sidecars.

Most PCjr.s have at least an IBM Parallel Printer sidecar attached, as the PCjr. did not provide a parallel port in the system unit.  The Printer sidecar provides one unidirectional parallel port using the standard DB-25 connector.

Many PCjr.s also have a Memory Expansion Attachment sidecar, from IBM or a third party company.  These sidecars add at least 128KB of RAM to the system.  Few self-booting programs will recognize more than 128KB of RAM in a PCjr.  The memory expansion's device driver must be loaded in DOS for DOS to report more than 128KB available to programs.    A device driver called JRCONFIG will work with any memory expansion.

If you have a 33W power board in the system unit and use more than two sidecars, you will need the IBM PCjr. Power Attachment sidecar, which provides more power for sidecars.  This sidecar must be inserted before any sidecars it needs to power (closer to the system unit) and has a separate power supply identical to the PCjr. system unit power supply.  They use the same connector.  With a 45W power board, you can use three sidecars comfortably.

Turning the System On :

When you turn on the screen, you will immediately see, if the system is working at all, the IBM logo and the fifteen RGBI colors that a CGA monitor can display in addition to black.  The memory will be counted and tested.  Once the memory has been counted, the screen will change to a blinking cursor, the diskette drive will seek and try to boot a disk in the drive.  Any expansions with a bootable ROM, like a hard drive or SCSI expansion interface, will attempt to boot at this time.  If neither the diskette drive nor any bootable interface is available or functioning properly, then the PCjr. will boot a cartridge, and if no cartridge is inserted, then Cassette BASIC.

Fan and Heat :

The fan inside the system blows cool air on the floppy drive and diskette.  IBM felt this was necessary to prevent a disk from melting inside the drive after heavy usage.  The fan is not intended to cool the system, that is what all the vents are for.  You can disconnect the fan without immediate apparent issue if you do not often use the disk drive, but the fan improves airflow inside the case.  This should help the Power Module (the hottest element in the system by far) and the chips underneath the floppy drive (including the CPU).  Although you may be tempted by the prospect of silent operation, leave the fan on.

Keyboard Adventure and System Diagnostics :

The PCjr. has a built-in program called Keyboard Adventure.  This can be loaded by pressing the Esc key just after Cartridge or Cassette BASIC has loaded.  You cannot have pressed any other key before pressing the Esc key.  This program was made to help introduce first-time computer users to the keyboard, and can be used to test the keyboard.  A full description of the program can be found in the PCjr. Guide to Operations manual, which came with every system.  Press Ctrl + Alt + Del to exit and reboot the system.

To start system diagnostics, any time after the PC has booted, whether to BASIC or to a disk, press Ctrl + Alt + Ins.  This will appear to reboot the system, but the memory will be counted and you will be shown a screen with several ASCII graphics and numbers underneath them.   The tests are rather cryptic and are fully explained in the Guide to Operations with the exception of  Test Tags H, I, L, M, N, O & P.  Here are a list of the Test Tags and what they test :

Test Tag 1 - Diskette Drive (requires spare floppy disk)

Test Tag 4 - 40-Column Display modes and 16KB graphics modes

Test Tag 8 - 80-Column Display modes and 32KB graphics modes (requires IBM PCjr. 64KB Memory and Display Expansion Option)

Test Tag 5 - Light Pen

Test Tag 6 - Joysticks

Test Tag 9 - internal PC Speaker and 3-voice sound (external speaker, TV Connector or PCjr. Color Monitor required)

Test Tag J & K - Cordless Keyboard  (Test Tag J treats the keyboard as a 62-key keyboard, Test Tag K treats the keyboard as if it were an IBM PC 83-key keyboard and allows you to use key combinations for the missing keys)

Test Tag G - IBM PCjr. Internal Modem

Test Tag H - IBM PC Compact Printer

Test Tag I - RS-232 (with loopback Plug)

Test Tag L & M - IBM PCjr. Cluster Adapter Attachment

Test Tag N, O & P - IBM PCjr. Speech Adapter Attachment

To escape from any test, press Fn + Break.  Press Ctrl + Alt + Del to exit and reboot the system.

Error Messages :

If you are unfortunate, you may encounter an error message.  Error messages are assigned a letter, here are a list of error messages and possible solutions :

Error A - Memory Problem, remove memory expansion sidecars and internal memory option to try to isolate which one is causing the program.  Will cause the system to hang.

Error B - Keyboard Problem, move the keyboard away from any extremely bright light source, replace the batteries, move the keyboard closer to the system if using IR and do not press any keys during the bootup process.  May cause system to hang.

Error C - Cassette Problem, press Enter to continue booting without using the cassette.  Usually caused when the cassette motor relay goes bad.

Error D - Serial Port Problem, may hang system.  Unplug any device from the serial port.

Error E - Modem Problem, press enter to continue booting without using the Modem.  Make sure the modem is properly inserted.

Error G - Cartridge Problem, may hang system if cartridge is inserted, remove cartridge.

Error H - Diskette Problem, press enter to continue booting without using the Diskette Drive.  Make sure the diskette drive adapter card is properly plugged into the system, the diskette drive is properly connected via the cable to the diskette drive adapter, the diskette drive is plugged into the power connector.

Error X - Unknown, may hang system.  May not actually exist.

Video and Audio Connections :

The PCjr. is very video friendly in that it has a composite video output jack that can connect to almost any modern TV.  You do not need a hard to find CGA compatible monitor to get video output.  The colors may not be as pure, the pixels may not be as distinct, but graphics should be visible.  If you boot to DOS and you see 80-column color fringed text, use the DOS command MODE BW80 to switch the text to black and white.  If you want more legible text, then use MODE BW40 to use a 40-column text mode.

If you find that your PCjr.'s display is off center or partially cut off, press Alt Left Arrow  to shift the visible display to the left and Alt Right Arrow to shift the visible display to the right.  You can also enable or disable the keyboard audio click by pressing Ctrl + Alt + Caps Lock

The internal beeper inside the PCjr system unit will only generate PC Speaker sounds.  If you want to hear sounds from the 3-voice chip, the PCjr. Speech Adapter or from the Cassette Port, you will need to connect the PCjr. to an amplified speaker via the RCA audio output jack, to a TV using the TV Connector switchbox, or to a 4863 PCjr. Color Display.

COM and LPT assignment.

The built in serial port is assigned to COM1 and LPT1 in the BIOS if there is no Internal Modem or Parallel Printer Attachment installed.  However, the resources used by the serial port are I/O 278H and IRQ3, which are generally assigned to COM2.  The Internal Modem uses I/O 3F8 and IRQ4, the BIOS assigns the Modem to COM1 if it is installed and the serial port becomes COM2.  If the Parallel Printer Attachment is installed, it becomes LPT1 and you may need to redirect LPT1 to COM1 or COM2 to print to the serial-based Compact Printer.

Recommended Programs :

Most DOS programs will require a 256KB PCjr., so if you don't have one you are probably going to be limited to self-booting (PC Booter) programs.  King's Quest I & II, The Black Cauldron and Below the Root are excellent adventure games that take advantage of the enhanced graphics and sound features of the PCjr.  Super Boulderdash and Jumpman are solid ports of these classic games with PCjr. features.  Microsoft Flight Simulator 2.0 looks best on the PCjr. and can take advantage of a 256KB PCjr.

The Device Driver JRCONFIG is a must if you are running a 256KB or more PCjr. in DOS.  The PCjr. was released with PC-DOS 2.1, and was officially last supported in PC-DOS 4.0.  DOS 5.0 and above require patching via DEBUG to run on the PCjr.  While DOS 3.3 and below can run in a 128KB PCjr., DOS 4.0 and above are not likely to leave much memory left for programs unless 256KB or more is in the system.

PCjr. Post-Cancellation, or the Afterlife of a Flop

November 1, 1983 - IBM announced the PCjr. to great fanfare.  Commentators predicted and expected that IBM's new system would bring order and compatibility to the fractured home computer market just as it had the business market with the PC and XT.  Magazines are published geared to the new system and software is updated to support the new features and otherwise run on the PCjr.

March 18, 1985 - IBM announced that it was discontinuing manufacturing the PCjr. system in April, intending to sell the remaining stock at a discount and not release any further peripherals or upgrades for the system.  It would continue to service the machines within their warranty period.

The reasons for the PCjr.'s failure have been well-documented elsewhere.  Had it not been discontinued, it would have probably have been sold until April 1, 1987, when the rest of the PC family was retired to make way for the PS/2 machines.  However, the public apathy for the machine a result of the machine's high price, competition from other home computers, miserable chicklet keyboard, incompatibilities with PC software and the high cost of the upgrades meant that despite IBM's weight in the industry, it had to be withdrawn as it was never going to the all-conquering success IBM intended it to be.

What happens when a buyer, believing in the solid name of IBM, buys a computer whose lifespan had just been reduced from years to months or even days?  Most PCjr.s had been sold during the 1984 Christmas season.  IBM not only abandoned the PCjr, but also soon abandoned its family and entertainment software products.  With one exception, the last games IBM marketed for the PC or PCjr. were released in 1985.  While it tried to put on a brave face by announcing a new and improved successor to the Jr., nothing came of it in the United States.  The closest thing to a PCjr. replacement was the PC JX, essentially the next generation of PCjr. released only in Japan, Australia and New Zealand.  It sold very poorly.  IBM never sold the PCjr. or JX in Europe and Tandy struggled to make an impact there as well.  IBM would not return to the market with a home-friendly machine until the PS/1 in 1990.

When IBM announced the PCjr. was being discontinued, software developers were the first to jump ship.  Microsoft, which had heavily supported the Jr. with the Microsoft Booster sidecar and an updated Flight Simulator 2.0 which took advantage of the Jr.'s capabilities, eliminated its PCjr. development almost overnight.  Spinnaker Software tried to burn its PCjrs in a great bonfire, only to find out that they wouldn't burn!.  Sierra On-line quickly focused its efforts to the PC and the Tandy platform, and many other game companies did the same.  Any software companies who had not yet jumped on the PCjr. bandwagon certainly were not about to start supporting the machine once its discontinuance had been announced.

All PCjr. magazines had already folded by December, 1984, in response to the weak market for the PCjr. before the 1984 Christmas season.  Peter Norton had written a trilogy of how-to books for the PCjr., Discovering the PCjr, Exploring the PCjr and Mastering the PCjr, but the third book was never released due to the discontinuing of the PCjr.

Every game that had support for the PCjr.'s graphics and sound, as identified in an earlier post on this blog, were all self-booting games released in 1984 or 1985.  In 1986, games were more and more beginning to run in DOS and very few advertised PCjr. support.  If a program had a sticker that said something like "IBM PC, XT, AT, Tandy 1000 and 100% Compatibles" that pretty much meant the PCjr. was unsupported and if the game worked it was more by chance than design.  Any DOS games from 1986 or later that did run on the PCjr., with expanded memory, tended to treat it just like an IBM PC with CGA. Sierra Online was the main exception, because its AGI engine had been originally built on the PCjr. and thus it was no great effort to make sure its games continued to run on it.  All Sierra AGI DOS games thus will work on the PCjr., but versions that work are a bit picky, the first versions of Space Quest, Police Quest, and King's Quest IV will not.  So will Thexder, 3-D Helicopter Simulator, later versions of Silpheed but later Game Arts/Falcom ports will not.  Early versions of King's Quest IV, Leisure Suit Larry II and perhaps Police Quest II specifically did not run on the PCjr., but later versions of these SCI engine games and other 16-color SCI0 engine games would run on a PCjr.

For the home user that had almost certainly dropped over $1,000 on the PCjr., it was not so easy to discard the computer like a bad memory as the mainstream industry had done.  Some undoubtedly felt that their purchase was now useless and soon consigned it to the attic or the basement.  Others probably only used it until they could afford something better.  But for some of the owners of the approximately 500,000 PCjrs IBM shipped out of its factories, they were not going to just let the machine gather dust and mildew.

Those who decided to stick with it and make a go with the Jr. were not completely left out in the cold, hardware wise.  The hardware expansion market for the PCjr. had dwindled considerably, but there were companies still trying to fulfill the need for upgrades.  Comapnies like Racore, Legacy and eventually PC Enterprises stepped up to offer an assortment of sidecars, cartridges, peripherals and expansion chassis to expand the capabilities of the comparatively crippled PCjr.  You could obtain a second floppy drive, a hard drive, 640KB of RAM, a clock/calendar chip, replacement keyboards, CPU accelerator boards, a coprocessor upgrade, Hayes compatible modems, and eventually SCSI adapters, VGA and Sound Blaster clones.  They sold compatibility cartridges that would fool software programs into thinking they were running on a PC.  In short, you could upgrade your Peanut almost as much as you could a PC or XT, but you had to do your research and purchase via mail order.  However, these expansions were sold to a limited market and pricey, often pricier than comparative PC expansions.  Also, with the monitor,  sidecars, expansion chassis and many adapters and cables to connect to standard PC peripherals, the PCjr. would eventually begin to look like a big "L" shaped spider.  PC Enterprises was in business the longest, finally closing its doors around the turn of the century.

For software, after 1985 things became really iffy for PCjr. owners.  Most PC game software (except Sierra), either only supported PC CGA, Hercules or EGA graphics and PC Speaker sound, and most of it required 256KB or more.  That software was indifferent to the PCjr. but if DOS-based, often would run if the PCjr had sufficient memory.  All IBM PCs and most clones by 1985 came with 256KB. While the Tandy 1000 also only came with 128KB, it was designed for 640KB, the PCjr. was designed for 128KB. While Tandy's memory expansions were pricey at first, they also added DMA, a widely appreciated feature which was difficult to implement on the PCjr.

For software now supporting Tandy graphics and sound, often the extra effort at trying to support a "dead" computer meant that developers did not bother, even though IBM made half a million PCjr.s and sold 400,000 of them.  Many developers did not have a PCjr. to test with.  Even though the IBM PCjr. and the Tandy 1000 operate almost identically, there are enough differences that making sure that software ran reliably on both was a real headache for a programmer unfamiliar with both systems.  Besides, with DMA, a relocatable video buffer, no extra latency between video and RAM access in the first 128KB, PC compatible floppy I/O addresses, two floppy drive support, easier hard disk support, better keyboard, more standard peripheral ports and faster Tandys, what time-pressed programmer wanted even to test their code on a PCjr.?

Here are some of the issues facing the programmer who wanted to make his software, designed on a Tandy 1000, work on a PCjr. :

Memory Issues - In the IBM PCjr., the first 128KB of memory is governed by the video controller.  This was done to simplify the design, eliminate the need for a DMA controller or separate circuitry to refresh the DRAM.  The video controller would read all the RAM sixty times a second.  However, this came at the expense of performance, as the video circuitry and the CPU had to contend with each other's access to RAM.  Any RAM added via sidecar above 128KB had its own refresh controller and thus accesses to and from this RAM was as fast as a PC.  So in the PCjr. there was a combination of "slow" RAM and "fast" RAM.  Tandy implemented this same feature in its machine, but unlike the PCjr, Tandy made sure that there was no adverse impact on performance.  So there is no "slow" and "fast" distinction in a Tandy, and any programmer desiring a consistent speed for their operations would have this headache.

The addition of memory above 128KB on a PCjr. does not give you as much memory as you would think. Adding more memory requires a DOS memory driver to configure the system to use the memory. Otherwise programs will not recognize or use it (with the rare exception of the Flight Simulator II booter.)  The memory driver will set the free RAM from 128KB upward and leave the slow first 128KB to the Video, BIOS, DOS and may configure the rest as a RAM disk.  A Tandy does not require this and can have more free RAM available to programs because its DOS does not need memory drivers or treat the first 128KB as non-user memory.  Generally speaking, a Tandy without the 768 RAM upgrade will report a maximum of 624KB available to DOS programs while a PCjr. will report 608KB.

Video Issues - Both the Tandy 1000 and IBM PCjr. have a video memory window at B8000 to maintain CGA compatibility.  Until the (upgraded) Tandy 1000 TX, there would be no actual memory in this area, it would redirect to the designated address of the main memory where the video buffer was located. However, IBM only provided a 16KB window at B8000-BBFFF while Tandy allowed access to a 32KB window at B8000-BFFFF.  For the 160x200x16 mode or any of the CGA modes, this made no difference because one screen's worth of these graphics modes use 16KB.  The 320x200x16 and 640x200x4 modes require a 32KB buffer.  On any Tandy 1000, the programmer could use the B8000 window and not have to bother about figuring out where the video buffer really began.  If the programmer made no changes to his code for the PCjr., only every other line would be visible.  This gave rise to the "Tandy-mod" for the PCjr., where a chip would be soldered into the PCjr. to show all the lines.  To support the PCjr., the programmer would have to write directly to the portion of memory which the video circuitry was using when using a 32KB mode.

The IBM PCjr. had a chip called the Video Gate Array (VGA) that controlled the graphics modes in conjunction with the MC6845.  Tandy implemented this VGA, but its implementation was a little different.  The PCjr.'s VGA had an address and data write register at port 3DA, with the write mode switched by a read to port 3DA.  Tandy must have decided this was inefficient, so address writes in its VGA went to port 3DA and data writes to port 3DD.  Any program that writes to the VGA must be aware of this difference.

Moreover, the actual registers that controlled the modes were implemented differently in the Tandy and PCjr.  In the Tandy, to restore compatibility with the PC CGA, Tandy's VGA supports I/O ports 3D8 (Mode Control) and 3D9 (Color Select).  The PCjr. does not implement these ports, and handles all of the Mode Control functions in the VGA internal ports, most important is port 00.  Tandy's VGA does not implement port 00 in its VGA, instead relying mainly on 3D9.  The differences in the VGA ports (and there are others) is another headache for the programmer who wants to directly program the graphics registers.

Floppy Drive Issues - Tandy followed the IBM PC and used addresses 3F0-3F7 to communicate with the Floppy Disk Controller.  The IBM PCjr. uses addresses F0-F7.  While software using DOS or BIOS routines should not care, since using DOS or BIOS takes care of disk transfers, programs accessing the disk controller directly would need to be modified for the PCjr.  Booter programs and copy protection routines, important in the 1980s, frequently accessed the hardware directly to obfuscate the code or to improve performance.  Moreover, the PCjr. had no provision for DMA while every Tandy 1000 had it or could be upgraded to it.  DMA made for faster disk transfers, and timing critical disk functions would be affected by this.

Keyboard Issues - Tandy uses a 90-key keyboard, and its raw scan codes are identical or similar to the 83-key IBM PC keyboard, except for those keys unique to the Tandy keyboard.  The 62-key PCjr. keyboard with its different arrangement uses different scancodes for the keys that exist on the 83-key PC keyboard.  This is typically with the Fn key, and the scancode pair is then translated by the BIOS for the PC scancode. Tandy's keyboard uses IRQ1, like the PC's, while the PCjr's keyboard uses NMI.  All these make for issues with low level keyboard reading routines.

Even with these issues, there was considerable life left in the old Peanut.  It was quite possible to purchase a PCjr. in 1987, often at a heavily discounted price.  IBM provided some support for the Jr. until that time at least.

In the 1980s, there were often users groups created in a geographical area dedicated to a particular home computer.  Perhaps spurred in part by the abandonment of the platform, PCjr. users groups were formed in several parts of the country and operated for many years, some well into the 1990s.  The most famous ones were the Eugene, Oregon PCjr. Users Group and the Metro PCjr. Users Group in the metro-Washington D.C. area.  These groups provided advice, support and meetings where PCjr. owners could trade the latest news and gossip, review hardware and software and try to solve problems.  The groups also had their own Bulletin Board Services (BBSs), where people could post on message boards and download patches and programs.  Newsletters in print and on disk were also a feature of these clubs.

Many issues of one particular newsletter, the jr Newsletter, are available online.  The jr Newsletter ran from June 1986 to at least October 1993.  This newsletter provided tips, fixes and advertising for PCjr. specific peripherals.  IBM's BBS also had PCjr. specific files for a long time.  Some games, sometimes unintentionally, still supported PCjr. graphics and sound or were hacked to do so.  Electronic Arts, for example, included a PCjr. patch for Starflight made by a PCjr. owner who submitted it to the company.

The PCjr.'s life was not totally brought to an abrupt end in March 1985, despite the views of many at the time and since.  Extending the lifespan of the machine required the user to become intimately familiar with this machine's hardware and the software available for it.  It is an important example of how ordinary people, despite mainstream indifference (and often contempt) and market forces which should have condemned the machine into a nearly-forgotten footnote of computing history, allowed a unique computer to achieve some measure of the hoped-for potential intended for the machine in 1983.

Meet another Video Card - The Prolink Systems, Inc. MVGA-AVGA4VL VLB Card

Recently, I found a card nearly identical to this one from http://www.vgamuseum.info/ in an old system and decided to try it out :

I have tried it out and have come to like it more than my S3-805 based Diamond Stealth VLB card.  Its slightly faster, more compatible, supports more RAM and video modes.  I have no complaints about the DOS video quality.  It uses the Cirrus Logic CL-GD5429, which supports true color modes and Windows acceleration.  It uses memory-mapped I/O for increased speed.  It comes with 1MB of RAM and can be upgraded to 2MB with two 256x16-70ns Fast Page Mode SOJ chips.

The card has two jumpers, JP1 when closed allows for IRQ2/9 usage, and JP2 when closed allows for operation when the bus speed is greater than 33MHz.  The data sheet for the family of VGA controllers, for which this is perhaps its most advanced member, is readily available.  It reports that the card's BIOS supports the following SVGA/VESA modes :

14h - 132x25T
54h/10Ah - 132x43T
55h/109h - 132x25T
5Eh/100h - 640x400x256
5Fh/101h - 640x480x256
58h,6Ah/102h - 800x600x16
5Ch/103h - 800x600x256
5Dh/104h - 1024x768x16i/p
60h/105h - 1024x768x256i/p
6Ch/106h - 1280x1024x16i 
6Dh/107h - 1280x1024x256i*
66h/110h - 640x480x32K
64h/111h - 640x480x64K
71h/112h - 640x480x16M
67h/113h - 800x600x32K
65h/114h - 800x600x64K
68h/116h - 1024x768x32Ki
74h/117h - 1024x768x64Ki

* - Requires 2MB of video RAM.
i - Interlaced Mode
T - Text Mode

This card has better compatibility that the S3 card.  EGA compatibility is very good.  Commander Keen 4, 5 and 6 and Dangerous Dave do not need the SVGA compatibility switch, Keen 1-3 and Keen Dreams do not have scrolling problems, SimCity's text fonts look correct in the EGA high resolution mode and there are almost no flickering lines in the Silpheed intro.

VGA and SVGA compatibility is outstanding.  System Shock CD allows the 640x400 mode to be used, although the speed on my 486DX2/66 is not the speed at which I would like to play the game.  It has no problem with games with unusual Mode-X VGA modes like 320x240 (Epic Pinball), 320x400 (System Shock CD), 320x199 (Jazz Jackrabbit), 360x350 (Pinball Illusions), 312x200 (Prehistorik 2), 320x184 (Jurassic Park) and 320x350 (Pinball Fantasies).  It supports SVGA 640x480 and 800x600 resolution modes in Pinball Illusions perfectly.  It works with Prehistorik 1 & 2, Duff and Lollypop, both of which use a tweaked 320x200 mode.  It is among the supported 640x400 SVGA modes of Microsoft Flight Simulator 5.x.  It can even support the old Paradise SVGA 800x600 mode that Wonderland uses.  DOOM and DOOM II run just as fast on this card as the S3 card.

The DOS refresh utility is called CLMODE and there are Windows 3.1 drivers for the chipset.  The BIOS revision on my card is 1.00A.

Prompted by a friend of mine, I decided to perform a more demanding test, namely testing this card's support with UniVBE 5.3 and 6.53.  UniVBE 6.53 reports that Linear Frame Buffer will not work reliably with CL 542x chips with more than 14MB of RAM.  Support for LFB was thus dsiabled in my system, but 16MB of system RAM is more useful in a 486 than 12MB of system RAM and LFB.  With 8MB of RAM, UniVBE will install LFB at 14MB.  UniVBE also reports that Multi Buffering and Virtual Scrolling are also available, but 8-bit DACs are not present.

The card supports lots and lots of modes with UniVBE loaded, so I didn't test each and every resolution at each and every frame rate.  With UniVBE 5.3 all the modes I tested worked.  There are more modes supported with UniVBE than with the card's BIOS, and UniVBE offers superior compatibility with some modes than the BIOS alone.  UniVBE requires 13KB of RAM and it may not be possible to load it into upper memory, so it should only be used when necessary.  Here are the list of modes the card supports with UniVBE loaded :

4-bit Banked Only
640x480
800x600
1024x768

8-bit Banked and Linear
320x200
320x240
400x300
320x400
320x480
512x384
640x350
640x400
640x480
800x600
1024x768
1152x864

15-bit Banked and Linear
320x200
320x240
400x300
320x400
320x480
512x384
640x350
640x400
640x480
800x600

16-bit Banked and Linear
320x200
320x240
400x300
320x400
320x480
512x384
640x350
640x400
640x480
800x600

24-bit Banked and Linear
320x200
320x240
400x300
320x400
320x480
512x384
640x350
640x400
640x480

32-bit Modes
None

SimCity for DOS - The Swiss Army Knife of Video Mode Support

The original version of SimCity for DOS, 1.02, supported a variety of video modes.  Here is a screenshot of the title screen and an in-game screenshot of the Detroit scenario with a maxed out main window for each mode:

CGA Graphics Mode 06H 640x200 Monochrome :

Hercules Graphics Mode 720x348 Monochrome :

Tandy Graphics Adapter Graphics Mode 09H 320x200x16 / EGA Graphics Mode 0DH 320x200x16 :
(note : screenshots are 200% of original)

EGA Graphics Mode 0FH 640x350 Monochrome :

EGA Graphics Mode 10H 640x350x16 :

Version 1.07 of SimCity added the following :

MCGA/VGA Graphics Mode 11H 640x480 Monochrome :

SimCity Classic for DOS dropped the CGA and Tandy/EGA 320x200 support, but added the following :

MCGA/VGA Graphics Mode 12H 640x480x16 :

MCGA/VGA Graphics Mode 13H 320x200x256 :
(note : screenshots are 200% of original)

The modes common to SimCity and SimCity Classic look virtually identical in-game, but the title screens are different.  Here they are :

Hercules Graphics Mode 720x348 Monochrome

EGA Mode 0FH 640x350 Monochrome

EGA Mode 10H 640x350x16

MCGA/VGA Mode 11H 640x480 Monochrome :

Finally SimCity Enhanced CD-ROM for DOS only supported the following :

SVGA/VESA Graphics Mode 101H 640x480x256 :

Note : Title Screen uses MCGA/VGA Graphics Mode 13H 320x200x256 (screenshot is 200% of original size)

Between the various incarnations of the same basic SimCity game for DOS, the game supported every major DOS video standard and an unusually wide variety of Graphics Modes.  Sound support was also very broad.  The original SimCity only supported sound effects, and supported the only available digitized sound hardware available in 1989 that would output digital samples without seriously compromising performance, the Tandy DAC and the Covox Sound Master.  Unfortunately, not until SimCity Classic did the game support Sound Blaster cards.

A Tale of Two Configs

In an MS-DOS system with a 386 or better processor, when it comes to configuring the OS, typically the issue is whether to load or not to load EMM386.EXE.  Loading EMM386.EXE puts the machine into Virtual 8086 mode, and using EMM386 to make expanded memory available substantially decreases the amount of upper memory available to load drivers.  Fortunately, you need not make expanded memory available unless a program requires it.  EMM386 is used to make upper memory available for loading device drivers, and without it, those drivers must be loaded in conventional memory.  If those drivers cause the amount of free memory to be lower than the amount a program requires, the program will not load.  Use of EMM386.EXE is utterly incompatible certain programs like Ultima VII Parts I & II.  On the other hand, many other contemporary games require expanded memory to support sound.  Other games don't care either way.

HIMEM.SYS, which provides access to all the memory above 640KB, is essential to load and should always be loaded .  EMM386.EXE requires HIMEM.SYS to be loaded first.  HIMEM.SYS provides access to the high memory area and allows DOS to load most of itself there, significantly cutting down on the conventional memory DOS would otherwise take up.  For programs that require or can use it, it also makes extended memory available.

For MS-DOS 6.22, a typical 486 computer setup with a mouse, CD-ROM drive and a Sound Blaster 16   may have a CONFIG.SYS like this :

DEVICE=C:\DOS\HIMEM.SYS /TESTMEM:OFF
DEVICE=C:\DOS\EMM386.EXE I=B000-B7FF FRAME=E000
DOS=HIGH,UMB
FILES=40
BUFFERS=30
DEVICEHIGH=C:\DRIVERS\VIDE-CDD.SYS /D:MSCD001

and a typical AUTOEXEC.BAT file may look like this :

@ECHO OFF
PROMPT $P$G
PATH=C:\;C:\DOS;C:\SB16
SET BLASTER=A220 I7 D1 H5 P330 T6
SET SOUND=C:\SB16
SET MIDI=SYNTH:1 MAP:E
C:\SB16\DIAGNOSE /S
C:\SB16\MIXERSET /P /Q
LH C:\DOS\MSCDEX.EXE /D:MSCD001
LH CTMOUSE.EXE

My 486 uses roughly these lines in its AUTOEXEC.BAT and CONFIG.SYS.  Lets describe what each line does, starting with the first line of CONFIG.SYS :

1.  DEVICE=C:\DOS\HIMEM.SYS /TESTMEM:OFF

HIMEM.SYS is a Device Driver that must be loaded in CONFIG.SYS on startup.  The config.sys command to load a device driver is DEVICE=.  The full path where a device driver can be found must be included.  HIMEM.SYS is primarily used to allow DOS to access the High Memory Area, but it also functions as an eXtended Memory Manager (XMM), giving your programs access to eXtended Memory Specification (XMS) memory.  The /TESTMEM:OFF parameter bypasses a memory test that adds to the boot time on DOS 6.x.  It is only useful on 286 or above systems.

2.  DEVICE=C:\DOS\EMM386.EXE I=B000-B7FF FRAME=E000

EMM386.EXE can be used as a command or as a device driver.  It's primary function is to act as an Expanded Memory Manager (EMM), giving your programs access to Expanded Memory Specification (EMS) memory.  It also allows the creation of Upper Memory Blocks (UMB) in the Upper Memory Area (UMA).  It is only useful on 386 or above systems.  This device driver switches DOS from using real mode into Virtual 8086 mode, and some programs and games refuse to run in this mode.  By removing the EMM386.EXE line, those programs that complained about EMM386.EXE and Virtual 8086 mode and refuse to load now will load.

As the command is given, EMM386 will emulate Expanded Memory. If you do not wish to emulate Expanded Memory, then use NOEMS. I=B000-B7FF tells the system to add a 32K Upper Memory Block in the area of video memory reserved for MDA cards. As you are likely using EMM386 with a VGA card, this area should be used. FRAME=E000 sets the EMS page frame to E000-EFFF, which permits UMBs at C000-C7FF and D000-DFFF. If the E000 segment gives you trouble, then you'll have to use the D000 segment. The line as given gives you 96K of UMBs to load your device drivers, which should be more than sufficient even for the relatively bloated CD-ROM and Mouse drivers of the day.

3.  DOS=HIGH,UMB

This line instructs DOS to load itself high, saving about 55K of Conventional Memory.  It also instructs DOS to create UMBs.  By loading drivers within UMBs, you can save Conventional Memory from being used.  You must load HIMEM.SYS to use the HIGH parameter and EMM386.SYS to use the UMB parameter.  

4.  FILES=40

DOS's default maximum number of files being open at one time is 15, but some games require more.  40 is sufficient for just about any program.  

5.  BUFFERS=30

DOS's default maximum number of disk buffers to allocate is 8, but some games require more.  30 is sufficient for just about any program.  

6.  DEVICEHIGH=C:\DRIVERS\VIDE-CDD.SYS /D:MSCD001

DEVICEHIGH tells DOS to load a device driver into an UMB.  It does not work with HIMEM.SYS or EMM386.EXE and will not work until both have been loaded.  

VIDE-CDD.SYS is a generic IDE CD-ROM device driver that works with pretty much everything and only takes up 5KB of RAM.  This device driver acts as an interpreter between DOS calls and the low level hardware.  If the CD-ROM drive used a SCSI or proprietary interface, you would load another kind of driver here.  You cannot actually use a CD-ROM as a drive until you load MSCDEX.EXE in AUTOEXEC.BAT  The /D:MSCD001 is the name given to the CD-ROM and must be used with MSCDEX.EXE.  

Alternatives to EMM386.EXE for UMBs

EMM386.EXE generally causes slightly decreased performance compared with an environment when it is not loaded.  If you want to create UMBs without it, you will have to try to find a program that will work with your chipset.  The program UMBPCI.SYS works with chipsets that provide a properly-functional PCI implementation.  Pentium/586 and later systems are the mostly likely systems to work with UMBPCI.SYS. Programs that can work with 386 and 486 computers include HiRAM, URAM, DOSMAX and RDOSUMB.  These programs only support specific motherboard chipsets, whereas EMM386.EXE is universally supported on PC compatible motherboard chipsets.  I have a 486 SiS 85C471 chipset and URAM supports it, so I use that program.  My CONFIG.SYS looks like this :

DEVICE=C:\DRIVERS\URAM.COM R=..........7777777777.... I Q
DEVICE=C:\DRIVERS\UMB.SYS C800-EFFF
DEVICEHIGH=C:\DOS\HIMEM.SYS /TESTMEM:OFF
DOS=HIGH,UMB
FILES=40
DEVICEHIGH=C:\DRIVERS\VIDE-CDD.SYS /D:MSCD001

My AUTOEXEC.BAT stays the same.

DOS 6.0 and above allows you to select your configuration properties via a boot-up menu system.  The Help in DOS 6.0 and above gives examples on how to set up a menu so that one selection will give load EMM386 and a second selection will load URAM.

SID and DOS - Unlikely but True Bedfellows

The Commodore MOS 6581 Sound Interface Device, the SID, is one of the most famous synthesizer chips of all time.  Its inclusion in the Commodore 64 and 128 computers helped to popularize computer music, mostly in Europe.  Like virtually every other popular synthesizer chip of the time, it made its way to the PC in some form.  Commodore had no problem in selling its chips to outside and technically rival companies. During its market life, the SID appeared in two different but related PC sound cards.

I.  The Entertainer

In 1987, Microprose was looking for a way to enhance the sound of some of its DOS games.  These games had access to superior audio hardware on the Commodore 64, Amiga and Atari ST, but the U.S. market was increasingly turning to the PCs.  Unless a PC owner had a Tandy 1000 with its 3-voice chip, he had to settle for the PC speaker, as there was no popular and cheap sound expansion hardware available at the time.  Since Microprose was still developing games for the Commodore 64, it seemed a natural idea to interface its SID chip with the PC.  They advertised a PC sound board called The Entertainer, which included a 6581 and a joystick port on an ISA card.  The only place this advertisement has ever been known to be seen is in an introduction screen and the readme to Gunship v429.04.  The readme discusses the card with the following text :

Support has been added for the MicroProse Sound Board - "The Entertainer".
Presence of the board is detected by the program and enhanced sound is
automatically generated.  Two additional control keys have been added to
control the volume.  Ctrl-V turns the sound down one notch.  Alt-V turns
it up.  Just pressing "V" alone still toggles the sound on & off.

Microprose, according to the ad, sold the card directly and it was available through "your local retailer". Two high-level Microprose employees have been contacted and have no memory of selling the card at that time, so it probably was not actually sold and if it was sold, it did not sell well.  The Entertainer card, if it was actually released by Microprose, was not supported by Microprose except in Gunship, v429.04 & 429.05 and Sid Meier's Pirates!, v432.1, 432.2 and 432.3.  It may also be supported in 432.4, which was a DOS conversion of the floppy PC booter from a Best of Microprose CD.  It was not known to have been intentionally supported in any other company's games.  The in-game ad and the text quoted above was removed for Gunship v429.05, so it is very possible that this was an idea that Microprose considered but which it did not follow through to market.

II.  The Innovation Sound Standard SSI-2001

Not too long after the Adlib Music Synthesizer Card began to be adopted by Sierra and other companies, and the idea (and more, as we will see) of a SID-on-a-chip card was resurrected by a company called Innovation.  It released a card around April, 1989 called the Innovation Sound Standard SSI-2001, which is a 6581 plus a speed-adjustable gameport.  It cost $129.00, but with discounts and coupons you could have purchased one for $69.00.  It may have only been available directly through Innovation.  Support was poor, the following games are the only ones known to support it :

Airball - SFX only, slow PC req'd
Bad Blood - Music only
Battle Chess II - SFX only
BattleTech: The Crescent Hawks' Revenge
F-19 Stealth Fighter
Falcon A.T.
Harpoon
Joe Montana Football - SFX only
Lord of the Rings Volume 1 - Floppy version only, SFX only
Red Storm Rising
Super Jeopardy
Ultima VI - Music only
Windwalker

I have verified that all the above games work with the Innovation emulation in DOSBox except for Super Jeopardy.  While Mobygames claims that Lexi-Cross and Castles and its expansion Castles : The Northern Campaign support Innovation, I have personally verified that these programs do not have install options for Innovation, despite what the system requirements labels on their boxes may indicate.  Asterix: Operation Getafix is also listed by Mobygames as supporting the Innovation, but it actually supports the InterSound MDO, a Covox Speech Thing-like device released by the French gaming company Coktel Vision.

The best informational article describing the card can be found in Computer Gaming World, Number 63, September 1989.  It mentions that only Origin and possibly Mindscape were planning to support the card.  Interplay and Microprose eventually did with more than one title.  Although Commodore made PC clones, it never put its sound chips in them.  The SSI-2001 is the only non-Commodore product I am aware of that used the SID chip prior to Commodore's failure in 1994.  

Technical details about the Innovation card and its SID implementation are as follows.  The card puts the SID chip and its 29 registers directly on the ISA bus.  It can use ports starting at 280, 2A0, 2C0 or 2E0.  280 is the default, and it takes up 32 consecutive I/O ports (3 presumably mirrored or unused).  The SID is clocked using the 14.318180 MHz clock from the ISA bus.  This clock signal is divided by the counter and flip flops on the board by 16 to produce a base frequency of .89488625 MHz.  By contrast, the base frequency of the SID in an NTSC C64 is 1.02272714 MHz and a PAL C64 is .98524851 MHz.  

The filter capacitors on the Innovation board use a value of 1nF.  This was proper according to the datasheet of the 6581, but in practice in the Commodore 64, different values were used.  By comparison, the 6581 SID in a C64 uses 470pF capacitors and an 8580 in a C64C or C128D use 22nF capacitors (1nF = 1000pF).  If Innovation had used the later 8580 chips in their card, the datasheet for the 8580 specifies 6n8/6.8nF/6800pF capacitors.  The POTX and POTY pins are not connected on the Innovation board, so the two registers which correspond to the functionality provided by these pins are useless.

The gameport is addressable at the standard port 201, supports 4 axes and 4 buttons, can be disabled with a jumper and supports three levels of "sensitivity", also selectable by jumper.  The Innovation card is the first sound card known to incorporate a standard gameport, a feature popularized by the Sound Blaster in 1990 and then ubiquitous on sound cards for the rest of the decade.

By using the joystick enable jumper and the four port range selections, one can install four boards and hence four SID chips in one computer, if you had the slots to spare.  Two boards would provide fully-independent stereo channels, but no software was known to take advantage of this capability.  

I know of exactly two Innovation boards known to be in existence, and each has minor layout differences compared with the other.  Both boards clearly show the use of 6581 chips, not the later 6582/8580 chips.  Here are images of both boards known to be in existence :

Earlier Board :

Later Board :

No one I know has ever seen a "The Entertainer" branded card.  It works just like the Innovation board hard coded at port 280, but it also has autodetection port functionality at port 200.  Gunship and Pirates! will only produce SID sound if they read a value of 45h from this port. The code string BA 00 02 EC in Gunship 429.05 executables EGAME.EXE/CGAME.EXE/TGAME.EXE and TITLE.EXE (the only version that uses unencrypted executables) must be replaced with B8 A5 00 90.  Ditto for the disk images of Pirates! Once the code is bypassed and an Innovation card is in the system or the emulation is enabled in DOSBox, you will hear SID sound.  Unfortunately, DOSBox uses the 1.02MHz frequency and 470pF Caps for the SID, so it will not sound exactly like the real boards would.

III.  The Modern Replica SSI-2001

In 2015, the prayers of many were answered when members of the VOGONS forum produced a replica of the SSI-2001 using a redesigned ISA board built mainly from photos of the card.  This is what my card looks like :

Improvements over the old card include :

Can use 6581 or 8580 SIDs.
Jumper based speed setting for NTSC clock frequency or canonical SID clock frequency
Audio input jack
4-pin audio output header (dual mono on pins 1 & 4, pin 2 is ground)
Plated holes for POTX and POTY inputs
Fully labeled jumper settings

The cards have been made by a VOGONS user named Fagear, who is based in the Russian Federation. His work is top quality and he had the good sense to use mini-jacks instead of the RCA jack on the original.  This meant that you can use any old junky ISA sound card for a bracket instead of having to make a custom bracket.  My card works great, although I had to find my 6581 SID chip from another source.

You may notice, if you order from a card from Fagear, that the markings on the ICs, except for the SID, are not the familiar 74 series designations.  The chips on this card are clones or work-alikes of the 74 series from several manufacturers exported by V/O Elektronorgtechnica.  This company was a part of Elorg, the Soviet state owned entity that controlled imports and exports of computer hardware and where Tetris was born.  However, with one apparent exception, the Russian parts appear to be functionally equivalent and use the same pinouts as the western chips.  The identifying information for every part, western or Russian is silkscreened underneath the part, as can be seen here :

The sole exception is the chip just below the silkscreened SID CLOCK on the replica board, hence the jumper if the Russian or Western part is used.  

You cannot just swap a 6581 for an 8580 in these boards whenever you like.  The 6581 uses +12v, which the ISA bus provides.  The 8580 uses +9v, which is not present on the ISA bus.  In order to use an 8580, you must install a 78L09 voltage converter.  The location is just to the left of the POT X holes.  You would probably need to remove it if you revert to a 6581.

Thanks to VOGONS user form member bristlehog, you can play back .sid files through this card through a DOS utility called SIDPLAY.  However, you will need a fast PC, around at least a 500MHz Pentium III, for proper speed.  This is because .sid files use 6510 CPU instructions and rely on the 6526 CIA or the 6569 VIC-II for their timing, so a fair amount of these chips must be emulated.  That means CPU power.

If you want to order a Replica SSI-2001 and download the player software, you can find it in this thread : http://www.vogons.org/viewtopic.php?f=46&t=27045

With this Board, I was able to verify that Super Jeopardy does output digitized sound.  The output volume is so low as to make it almost useless.  Activision got it right in the BattleTech: The Crescent Hawks' Revenge, the voice in the introduction is nice and clear with an Innovation.