Remote x86

A debugging tool for computers to allow automated testing over
a RS-232 or otherwise serial port.

When booted from floppy, CD-ROM, etc. this image minimally sets
up a kernel that communicates with a host over RS-232 and allows
the host to peek/poke memory and upload/execute code.


This remote control code is written in a somewhat modular fashion.
"stage1" is responsible for loading the rest of the program, and
"stage2" is the program.

Stage1 therefore might be:
  + Floppy disk loading code
  + CD-ROM boot loading code
  + USB pen drive/HDD loading code

Stage2 itself is modular, representing each possible "mode" the
CPU may execute in (part of testing is seeing how the CPU acts
in various modes).

  + base mode (8086/8088 16-bit real mode), REQUIRED
  + 286 protected mode (16-bit), OPTIONAL, OFTEN OMITTED
  + 386 protected mode (16-bit), OPTIONAL, OFTEN ATTACHED
  + 386 protected mode (32-bit), OPTIONAL, OFTEN ATTACHED
  + AMD64 long mode (64-bit), OPTIONAL, OFTEN OMITTED

All modes refer to a common page for settings, and all act more
or less the same. The difference is the CPU mode it executes in.

The kernel is written to be stable, but to perform as minimal
modification to the host as possible. For this reason, it doesn't
touch the interrupt table, it doesn't touch very much else, it
only touches the hardware necessary to do it's job. This makes
it possible for the loader to be used as a memory snapshot
program as well, since the previous contents are not cleared.

You will need NASM. Some optional parts are written in C, if
those parts are attached, you will need GCC as well.

The default compile will omit AMD64 long mode on 32-bit hosts,
due to limitations in the elf32 linker. If you want AMD64
support you will need to compile and install a build of binutils
that targets x86_64-pc-linux-gnu.

Each build starts in 8086 real mode, and accepts commands to
switch into other CPU modes. No checkers are made to see if the
CPU supports it, it is expected that you know how to check and
decide for yourself. Know what you're doing.

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

MAIN BUILD:
    stage1*            floppy and El Torito bootable CD-ROM stage 1
    stage2*            actual payload, the debugger

    The main build requires that the computer you are running it
on have a working RS-232 serial port at the standard PC/XT/AT
locations (COM1 on 0x3F8, etc). Most pre-Pentium II laptops made
prior to 1999 and almost all desktops have this, so it should be
workable. If not, see the alternative versions below.

    If a floppy disk is not a viable option for booting (such as:
laptops where the floppy is missing or broken), alternative methods
are provided:

    dosboot.com        Kick DOS out of memory, bring up debugger
    grubboot           GRUB multiboot image containing this debugger

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

Ethernet build: (eth)

    stage1*            floppy and El Torito bootable CD-ROM stage 1
    stage2*            actual payload, the debugger

    This build is intended for laptops where RS-232 ports are
lacking or inaccessible, using instead the onboard ethernet controller.
Debugging is carried on over a low level packet protocol instead.
The host machine is expected to be connected directly to the machine
or through as few routers/hubs as possible.

    Unlike the main build, this version requires a 386 or higher,
it will not run on anything older. This restriction is intentional,
since every pre-1999 laptop I own either has a RS-232 serial port on
the back or makes it available through the docking port, while newer
laptops do not (and therefore need the use of this build). This
restriction also aids development since I can write the drivers in
32-bit C rather than try to write complex network drivers in assembly
language.

    Obviously, for this to work the build must contain at least
one device driver that knows your hardware.

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

The communication library and software are in the comm directory.
Simply tell it which communications device to use (linux serial
ports are named /dev/ttyS0, /dev/ttyS1, etc.) and it will do the
rest.