=============================================================================
IVTUTIL v1.01 overview
-----------------------------------------------------------------------------
Ivtutil is a utility program designed to enable easy analysis, conversion,
modification of "real mode" Interrupt Vector Table "save" files on *all* PC's.


=============================================================================
Why do I need this program?
-----------------------------------------------------------------------------
If you need to ask this question then please do NOT use this program, it was
NOT designed for you.  It is a dangerous program to misuse -please delete it!

For everyone else, if you are involved in OS/hardware development, OS porting,
BIOS patches or are just simply curious about how your PC looks on startup
then IVTUTIL may be useful to you, so read on to find out how it might help.



=============================================================================
Examples of the intended "end users" for IVTUTIL
-----------------------------------------------------------------------------
+ People curious to learn how PC's look prior to loading an operating system
+ System programmers working on projects to port OS's to embedded PC hardware
+ System programmers involved with writing or supporting PC operating systems
+ System programmers working on custom BIOS patches for legacy computers
+ Helping to resolve DOS/OS issues where interrupts are not being restored
etc

   *************************************************************************
   ***  Note: See acronym list below if you do not understand any used!  ***
   *************************************************************************


=============================================================================
What can IVTUTIL do?
-----------------------------------------------------------------------------
+ Process binary .DAT saves of the initial IVT (prior to an OS being loaded)
+ Convert IVT binary .DAT saves into an easy to read/understand .TXT format
+ Convert IVT binary .DAT saves into a .CSV format for database/spreadsheets
+ Convert IVT binary .DAT saves into a .REGistry format, e.g. to aid emulators
+ Convert back and forth between IVTUTIL's .IVT TEXT format and .DAT formats
+ Save the "current" IVT from within an OS session into several formats
+ Patch the "current" IVT from within an OS session (*dangerous* see below)


Usage help is built into IVTUTIL so for the type of people that IVTUTIL is
intended to be used by it should be fairly straight forward to use/understand.




=============================================================================
IVTUTIL's usage screen:
-----------------------------------------------------------------------------
IVTUTIL v1.01 - utility for processing/converting Interrupt Vector Table files
                Source and util released as PUBLIC DOMAIN by Richard L. James

Usage:
       IVTUTIL vectable.dat vectable.ivt   =   Convert .dat to .IVT file
       IVTUTIL vectable.dat vectable.txt   =   Convert .dat to .TXT file
       IVTUTIL vectable.dat vectable.csv   =   Convert .dat to .CSV file
       IVTUTIL vectable.dat vectable.reg   =   Convert .dat to .REG file
       IVTUTIL vectable.dat con            =   Display .dat on console
       IVTUTIL vectable.dat con more       =   as above but Line by Line

       IVTUTIL input.ivt vectable.dat      =   Create .DAT from .IVT file

       IVTUTIL mem con                  =   Output current IVT to CONsole
       IVTUTIL mem con more             =   as above but Line by Line
       IVTUTIL mem current.dat          =   Create .DAT from current IVT
       IVTUTIL mem current.ivt          =   Create .IVT from current IVT
       IVTUTIL mem current.txt          =   Create .TXT from current IVT
       IVTUTIL mem current.csv          =   Create .CSV from current IVT
       IVTUTIL mem current.reg          =   Create .REG from current IVT

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



=============================================================================
How to obtain the initial IVT  (prior to an operating system loading)
-----------------------------------------------------------------------------

Q) How can I save/obtain the initial IVT without loading an operating system?
A) With a special bootdisk/CD/Flash which allows this information to be saved.

Q) What programs exist for saving the initial IVT?
A) At the time of writing I only know of the existance of 3 such bootdisks:

+ The original flopper "install" bootdisk - http://www.oldskool.org/pc/flopper
+ My unreleased modified flopper "install" bootdisk (see comments down below)
+ My own unreleased bootdisk which basically works by doing a "double boot"

*Undoubtably other bootdisks must exist but I am just unaware of them myself*



=============================================================================
Using the flopper INSTALL bootdisk to obtain an initial interrupt vector table
-----------------------------------------------------------------------------

What is flopper?
----------------
History: Many early computer programs used their own custom operating systems.
Flopper is a free open source project by that enables these early computer
programs to be used on modern computers.  Flopper was created in July 1997
thus it predates the public release of the now more widely known/used BOCHS
( http://bochs.sourceforge.net/ ) + DOSEMU ( http://dosemu.sourceforge.net/ )

The usefulness of Flopper has in many ways now been replaced by many other
projects, however a particularly interesting unique feature is contained
within Flopper's install program.  Firstly be aware Flopper's install program
doesn't create directories or unzip files etc - as its name might suggest but
rather it is designed to create a special bootdisk which captures the initial
interrupt vector table on the PC upon which it is run.  By "default" usage
it is designed to capture that information onto the same PC upon which it is
run, however it is possible to also use it to capture the initial interrupt
vector table on any PC upon which the bootdisk is booted (providing the disk
boots succesfully and the PC is allowed to write back information to the disk)
by using the "INSTALL /2" switch on another PC to "recover" the saved IVT.

The following thus covers how to use flopper to "capture" an initial IVT:


How to obtain the initial (prior to an OS) IVT with Flopper's bootdisk
----------------------------------------------------------------------
1) Download Flopper from its homepage: http://www.oldskool.org/pc/flopper
2) *** Read Flopper's documentation to understand what its "install" does ***

** Do NOT however follow Flopper's documentation instead do the following **

1) Locate a **BLANK** floppy disk that you do *NOT* care about its contents
2) Label the disk so that you do NOT confuse it with any other disk you have
3) Write ENABLE the disk and FORMAT it with a DOS format, e.g. FAT16, FAT32
4) Do ***NOT*** write PROTECT the disk as flopper's install must write to it
5) Run Flopper's INSTALL to install the IVT saving code onto your *BLANK* disk
6) Boot the device/PC with your write ENABLED disk (note: this may NOT work)
7) Use the /2 parameter "INSTALL /2" to save out the saved IVT table
8) Ensure the resulting VECTABLE.DAT is in the same directory as IVTUTIL
9) Use IVTUTIL to then process the VECTABLE.DAT created by Flopper's install,
   for example "IVTUTIL VECTABLE.DAT VECTABLE.TXT" will create a IVT TeXT file
10) Reformat the flopper INSTALL disk to enable it to be reused safely again,
    I suggest doing this asap to ensure you don't mix up the disk with others.


Flopper install bootdisk problems?
----------------------------------
If you found the device failed to boot from the flopper disk then firstly
check your PC's BIOS settings to ensure that boot from removal media etc
has been enabled.  If it has then try another bootable disk, if that works
then the problem is likely to be as follows:

Some PC's require a bootdisk which has the magic signature 55AA on the disk,
the current version of Flopper (at the time of writing 17/Oct/2009) flopper
INSTALL does NOT include the 55AA signature.  It is fairly straight forward
to add this signature and missing disk structures to flopper and indeed I
have created a modified version of Flopper's INSTALL which works fine
including on a sub-notebook upon which the original INSTALL fails to work.

I plan to feed my work back into the Flopper project at some point but make
no firm guarantees as to when this will happen or indeed if it ever will.

Separately to flopper I do plan to release my own initial IVT saving
bootdisk/CD/Flash which will NOT require writing back to the disk by way
of a "double boot" in the hope that this disk will aid a number of projects.
Note: I did create such a disk a number of years ago but need to relocate it!




=============================================================================
Using IVTUTIL to "PATCH" the current "live" interrupt vector table on a PC
-----------------------------------------------------------------------------
The command to do this is DELIBRATELY not documented from the command-line,
to ensure people read the documentation before using this dangerous feature.

Patching a live interrupt vector table is NOT normally something most people
using IVTUTIL will ever need to do from the command-line....  Still if you
are one of those people for whom this functionality is useful this bit
explains how to use IVTUTIL to PATCH the current interrupt vector table.
                                                      
1) Create a 8.3 textfile with an .IVT extension, e.g. INT5-MOD.IVT
2) Create a [Patches2VectorTable] section
3) Place a list of interrupts you require to be patched into the file

e.g:
     -----------------------
     INT5-MOD.IVT
     ------------
     [Patches2VectorTable]
     Int05=FFFF:0000
     -----------------------

** To apply the patch you in this example type "IVTUTIL INT5-MOD.IVT MEM" **

*****************************************************************************
Use with extreme care: it is UNDOCUMENTED from the command-line for a reason!
*****************************************************************************

Note: IVTUTIL uses DOS to change the Interrupt vector table with this command
      Obviously it would be very easy to update IVTUTIL to patch the IVT
      directly.  If anyone feels direct patching would be useful let me know.


=============================================================================
FAQ
-----------------------------------------------------------------------------
Q)Do you plan to release a version of IVTUTIL for Linux?
A)Maybe, this version should also work under all Linux DOS emulators.

Q)What PC hardware does IVTUTIL require?
A)Basically it should run on anything greater than an 8086.  It has been used
by myself on a range of "unusual" PC hardware without any known usage issues
other than one device with a 40x3 display which wasn't particularly readable:)

Q)Do you plan to release a version of IVTUTIL for Windows?
A)The current "DOS" version runs happily under Windows.  No GUI is planned.

Q)Do I need to ask your permission to do XYZ?
A)No, please go ahead!  There are too many "requirements" with programs these
days, hence I thought I would release IVTUTIL with absolutely no restrictions.




=============================================================================
License
-------
You are free to use this program in anyway you like.
=============================================================================


=============================================================================
Useful/interesting links
-----------------------------------------------------------------------------
Flopper - http://www.oldskool.org/pc/flopper/
BOCHS   - http://bochs.sourceforge.net/
DOSEMU  - http://dosemu.sourceforge.net/
DOSBOX  - http://www.dosbox.com/
JPC     - http://www-jpc.physics.ox.ac.uk/
WP list - http://en.wikipedia.org/wiki/Comparison_of_platform_virtual_machines
QEMU    - http://www.nongnu.org/qemu/ + http://www.qemu.org/



=============================================================================
Revision history
-----------------------------------------------------------------------------
v1.00 - Limited distribution
-----
+ Initial version
+ Text file output
+ Registry output
etc


v1.01 - First public release  (17/Oct/2009)
-----
- Removed some redundant code comments
+ Added some additional code comments
+ Changed to reference Mathcvt.pas
+ Created documentation
+ Initial public release

=============================================================================


=============================================================================
Acronym used in this documentation
-----------------------------------------------------------------------------
Note: This list is included to ensure that the reader understands which
versions of particular acronyms have been used within this documentation:

IVT  = Interrupt Vector Table
INT  = INTerrupt
IDT  = Interrupt Descriptor Table
REG  = Registry
TXT  = TeXT file
GUI  = Graphics User Interface
TSR  = Terminate Stay Resident DOS program
DOS  = Disk Operating System
 OS  = Operating System


=============================================================================
Contact details for the author of IVTUTIL
-----------------------------------------------------------------------------
A method for contact me will shortly be available again via my homepage here:
http://www.wimborne.org/richard/
-----------------------------------------------------------------------------



=============================================================================
=============================================================================
**   ALL registered trademarks/copyrights are appropriately acknowledged   **
=============================================================================
=============================================================================

