               [Tand-Em -- The PCjr and Tandy 1000 Emulator]

               Tand-Em Copyright (c) 1998-1999, Vincent Joguin

             Documentation Copyright (c) 1998-1999, Jim Leonard

                           Version 0.55 - 19991803

           The latest version of this document is always kept at:
            http://www.oldskool.org/pc/tand-em/tand-em_docs.html

----------------------------------------------------------------------------

Table of Contents

   * Disclaimer
   * Introduction
   * Preparation
   * Usage
   * Frequently-Asked Questions
   * Future Development
   * Contributions and Contact Info

----------------------------------------------------------------------------

Disclaimer

Tand-Em 0.55 is still in an early alpha stage, so please expect many bugs!
This program is delivered "as is" and neither Vincent Joguin nor Jim Leonard
can be liable for any damage it could do to your computer.

This program must not be sold by any way, but it can still be distributed on
shareware CDs as long as there are no financial benefits received from the
act of selling it. You are highly encouraged to copy this emulator as long
as it remains in its original, zipped form. This program must not be
modified in any way.

Tandy 1000 is a registered trademark of Tandy Corporation/Radio Shack. PCjr
is a registered trademark of IBM Corporation. Sierra is a registered
trademark of Sierra On-Line, Inc. Sound Blaster is a registered trademark of
Creative Labs Inc. All other trademarks are owned by their respective
companies.

----------------------------------------------------------------------------

Introduction

Welcome to Tand-Em! Tand-Em is a Tandy 1000 and IBM PCjr emulator. The PCjr
and Tandy 1000 were 8088-based PCs that had enhanced graphics and sound well
before EGA or Adlib came out, and due to the Tandy's popularity in the
states, many games (well over 200) were programmed to take advantage of
those enhanced graphics and sound. Some particular early games have hidden
graphics and music that non-PCjr and non-Tandy owners have simply never seen
or heard!

Now that most of those machines are gone, the only way to experience these
great old programs is through some sort of emulation. That's where Tand-Em
comes in: Tand-Em fully emulates a 8088 or 80188, and uses a V8086 "window"
to access 8087 instructions if programs require a math coprocessor. Through
exact emulation of an 8088 via software, exact speed throttling and
redirection of ALL port writes and memory accesses are now possible, and are
able to be translated to another format (Tandy graphics to EGA, for example)
or completely emulated (Tandy's TI-SN76496 3-voice sound chip).

Because of Tand-Em's reliance on 80386 protected mode, Tand-Em requires an
80386 or higher CPU (or compatible).

For more complete information on the PCjr and Tandy 1000, including an
illustrated history, visit The Oldskool Shrine to The IBM PCjr and Tandy
1000 located at http://www.oldskool.org/shrines/pcjr_tandy/.

What's new in 0.55:

   * Version 0.55 now has Sound Blaster, SB 2/Pro and SB 16 support in
     addition to Adlib, and defaults to the best available in the system.
     Sound Blaster output is 8-bit, 23KHz (about), Sound Blaster Pro/2.0
     output is 8-bit, 44KHz (about), and Sound Blaster 16 output is 16-bit,
     44100Hz.
   * The menu system (hit the Right-ALT key to enter the menu) has been
     cleaned up a bit, and more options added.

----------------------------------------------------------------------------

Preparation

Tand-Em is a cycle-exact, opcode-exact, BIOS-exact emulator. As such, it
requires a "dump" of a Tandy 1000 BIOS ROM (or, in a future release, an IBM
PCjr ROM) in order to fully emulate a Tandy (or PCjr). In addition, Tand-Em
has its own protected-mode CPU and memory manager, so it must be used under
a clean DOS boot.

To prepare Tand-Em for use, you must go through a couple of preparatory
procedures, some of which require an actual Tandy and a method for getting
files off of a Tandy and onto the machine running Tand-Em. (For getting
files to/from your Tandy, you can use a network card, serial or parallel
cable, or simply put a 5.25" drive into your modern PC.) You must:

   * Dump the Tandy 1000's ROM from your Tandy and copy it to your PC
   * Dump a 360K diskette image and copy it to your PC
   * Make a "virtualized" 360K diskette out of a high-density disk

...before you run Tand-Em. Let's go over these steps in detail:

  1. Boot to pure DOS, with no memory managers like EMM386.EXE or HIMEM.SYS.
     No Windows 95/98/NT, please--they throw the machine into protected mode
     and prevent Tand-Em from working; if you have Windows 95/98, you must
     press shift-F5 at boot time in order to run Tand-Em. The same goes for
     x86 protected-mode emulators, like dosemu--they already run in
     protected mode and interfere with Tand-Em. (True software-only 80x86
     emulators like Bochs or SoftPC may work, but they've never been
     tested.)
  2. Copy the program JROMRIP.COM (located in the UTILS subdirectory of the
     Tand-Em distribution, along with other utilities you'll need) to your
     Tandy and run it. This will dump your Tandy's ROM into a file. Copy the
     resulting file (.ROM) back to your PC and into your Tand-Em directory.
  3. Copy the program DISK2FDI.EXE over to your Tandy and run it to copy a
     360KB disk into a raw diskette image file (.FDI). Copy this image file
     back to your PC.
  4. Use the program FDI2DISK.EXE to copy the image file onto a high density
     formatted disk of any kind located in drive A:.
  5. Leave this disk in drive A: and execute JR.EXE. Remember not to have
     any memory manager installed.

You should see your PC transformed into a Tandy, looking exactly like what
you see when you boot your Tandy computer--right down to 40-column textmode.
:-)
----------------------------------------------------------------------------

Usage

Keys:

The following keys can be pressed at any time to control Tand-Em during
execution:

   * Hit CTRL-` to quit the emulator. (The ` key is the back-quote key right
     above the TAB key.)
   * The Right-CTRL key enters Tand-Em's internal debugger. The debugger is
     very powerful; it runs completely outside of the emulation process
     controlled by v8086 mode, so you can step/trace, set hardware
     breakpoints, watch registers, etc. (In fact, if you're used to using
     DEBUG.COM for all of your assembly debugging, you may want to switch to
     Tand-Em's debugger! Just remember that it's emulating a Tandy, so some
     hardware calls may behave differently than your regular PC.)
   * The Right-ALT key enters Tand-Em's control menu. From here you can
     modify Tand-Em's configuration, including what speed/model CPU is being
     emulated, enabling/disabling hard-drive emulation, joystick support,
     etc.
   * Hitting ESC returns you to the emulation from the debugger or the
     control menu.

Emulation:

You can execute DOS and many programs (games, music software, graphics
software, etc.) in either CGA or Tandy graphic modes. Tandy video modes will
be emulated through your EGA/VGA card. Please understand, however, that
Tand-Em is still in the alpha stage, and nothing is guaranteed to work!

Tand-Em perfectly emulates Tandy's TI-SN76496 3-voice sound chip using your
Sound Blaster, Sound Blaster Pro, or Sound Blaster 16 (or compatibles).
Emulation is nearly perfect, with digital synthesis for the noise channel
and mixing actual sampled waveforms for the sound/music channels. (The DAC
of the TL/SL series is not yet implemented; this will be addressed in a
future release.)

(For those without a Sound Blaster or compatible, Tand-Em can emulate Tandy
sound through a Yamaha FM OPL3-compatible sound board, like an Adlib Gold.
With a regular OPL2 board, such as the original Adlib, it might work, but it
hasn't been tested. Right now the OPL3 sound emulation is very fast, but is
inaccurate; the noise channel is very simple, and the Tandy's frequency
waveform is only approximated. Since used Sound Blaster cards are very
cheap, we recommend obtaining one for best emulation quality.)

Tand-Em's control menu lets you change Tand-Em's operation. The emulated
processor (8088 or 80188), its speed, and the selected ROM image can be
changed in the configuration menu. You can also toggle the usage of hard
drives C: to Z: and joystick support. (Please note that while you will be
able to copy the files off of hard drives, you cannot execute programs
directly off of them. You will need to copy the executable files to a floppy
disk in drive A: in order to get them to execute. For example, COPY GAME.EXE
A:, then A:GAME, while staying in the game's directory on C:)

Hint: When changing the CPU speed in the configuration menu, holding down
the ALT key when hitting left-arrow and right-arrow makes the values jump in
larger increments.
----------------------------------------------------------------------------

Frequently-Asked Questions

Q: I don't have a Tandy--can't you just give me the ROM?
A: No. Doing so would be a violent breach of Tandy Corporation's copyright.
ROMs may be dumped and used for whatever you like as long as you own the
original. If we simply give you the ROM, we could be sued! Remember: All
emulators are legal, but ROM trading is not.

Q: If I need an original Tandy to dump the ROM, why bother writing the
emulator when I'll have a real Tandy in front of me?
A: Because your Tandy may eventually fail to work! With Tand-Em, you can
continue to play your favorite old games, run your great old music software,
etc. on modern PCs that can be repaired easily.

----------------------------------------------------------------------------

Future Development

There's still work to be done on Tand-Em, which we haven't gotten to for one
of two reasons: We don't have the knowledge to implement a feature, or we've
run into problems trying to implement it. See the Contributions and Contact
Info section at the end of this document to help!

   * More ROM compatibility (PCjr, Tandy SL/TL series, etc.)
   * More Tandy video modes support (640x200x4, etc.)
   * Better compatibility
   * Screenshot capability
   * Support for the Gravis Ultrasound (if you ask for it!)
   * The ability to execute files off of the C: drive and above (CDROM,
     etc.)
   * Disk image support
   * Tandy 1000 TL/SL DAC support

----------------------------------------------------------------------------

Contributions and Contact Info

For comments, contributions, suggestions, etc. regarding Tand-Em itself,
contact Vincent Joguin at aph@multimania.com. For any other matters, such as
the www.oldskool.org website, this documentation, etc., contact Jim Leonard
at trixter@oldskool.org.
