Black Box 4/BlackBox.cdr/fileutil/unld8615.arj/UNLOAD86.DOC

Text File | 1992-06-04 | 17.5 KB | 391 lines

UNLOAD86.COM is a program that converts or "unloads" a file into it's INTeL
hex representation.  Alternately, it will also output a BNPF, BHLF, OR B10F
type file for those users that require these formats.  This program was
written in response to the need to have INTeL hex files for downloading to
an EPROM programmer.  As MS-DOS programs don't support INTeL hex, the need
to convert binary files to hex arose.  Most development systems, INTeL, CP/M,
& others do support INTeL hex, and most EPROM programmers expect it.


Use of the program is simple:


UNLOAD86  <RETURN>

prints a brief help screen.

The main form of the unload86 invocation is:

UNLOAD86 FILENAME.TYP [/OPTIONS]

B  output a BNPF file instead of INTeL hex.  This option overrides any other
selections (Except Z).  If the B option is chosen, no other options will work,
and the program will output a straight 8-bit BNPF file, uless it has been
modified for BHLF, or B10F.

Z  Simply adds a Control-Z end-of-file mark (1A Hex) to the end of the
output file, be it INTeL hex or BNPF.  Most well-behaved programs ignore
this, some expect it, but some can't tolerate it.

L  Selects the new "extended linear address record".  See the discussion
at the end of this document for details.  If you don't know what this is,
you probably don't need it.  Interacts with /E, /O, & /P.  Automaticly
turns on /O, thus /O shouldn't be used with /L as /O will turn off /L.
/L also turns off /E & /P.

O Override extended addressing.  Any output file representative of 64K or
greater normally uses extended address records.  This is any file created
with /PC, /PD, /PE, or /PF, as well as any time the input file is longer
than 64K.  This inhibits the extended address records for the rare cases
where this is needed.  Interacts with /E.  Whichever is last is the effective
switch, normaly only one would be used at a time.  This option also turns
off /L

E forces the use of extended address records for file smaller than 64K.  Files
larger than 64K already automaticly select extended addressing.  Interacts
with /O and /L.  Whichever is last is the effective switch, normaly only one
would be used at a time.

P allows selection of an EPROM size so that all unused locations are filled
with the user specified data (defaults to FF)  This option interacts with
/L.  Whichever is last is the effective switch, normaly only one would be
used at a time.  This option is followed immediately by a parameter number
0-F.  This parameter is:

0  32 bytes.  Creates a file to fill a 32 byte ROM.  All unused locations
are filled with the user defined data.  As with all these options, if the
file is already longer than 32 bytes, an error message will be displayed
on the system console, and the operation will be aborted.  The file left in
this case is a useful INTeL hex file, but isn't padded up to size as it is
already too big for the device specified.  32 byte devices are generally
little bipolar ROMs often used as memory decoders

1  64 bytes.  This is also generally a bipolar device.

2  128 bytes.  Bipolar.

3  256 bytes.  1702A EPROM, some bipolars

4  512 bytes.  2704 EPROM.

5  1k bytes.  2708 EPROM.

6  2k bytes.  2716 EPROM.

7  4k bytes.  2732 EPROM.

8  8K bytes.  2764 EPROM.

9  16K bytes.  27128 EPROM.

A  32K bytes.  27256 EPROM.

B  64K bytes.  27512 EPROM.

C  *128K bytes.  27010 EPROM.

D  *256K bytes.

E  *512K bytes.

F  *1M bytes.

   * These options force the generation of extended addressing and thus
     do not require the use of the 'E' option.  This may be overridden
     with the 'O' or 'L' options.

It was felt un-necessary to provide padding when the /L switch is used as
an extended linear address is normally used only for files larger than 1
megabyte.  If you are reading this in 1999 and you're still stuck with a
computer that can run MS-DOS programs, need to pad a 4 megabyte PROM, you're
getting what you deserve!  Get a real computer!

It should be noted that all INTeL hex output, regardless of options selected,
is padded up to the next 32 byte increment.  This makes the /P0 parameter
redundant, but what else am I going to do with it?

ERRORLEVEL support.  UNLOAD86 now supports ERRORLEVEL.  It exits with 0
for no errors, and 255 if there was some kind of error.


EXAMPLES:


UNLOAD86 FOOBAR.COM/B    <-- produces a BNPF file called FOOBAR.BNP

UNLOAD86 FOOBAR.COM/EB   <-- produces a BNPF file called FOOBAR.BNP

UNLOAD86 FOOBAR.COM/E    <-- produces a hex file called FOOBAR.HEX
                             w/extended addressing

UNLOAD86 FOOBAR.COM/EZ   <-- produces a hex file called FOOBAR.HEX
                             w/extended addressing & CNTRL-Z at the
                             end of the output file

UNLOAD86 FOOBAR.COM/L    <-- products a hex file called FOOBAR.HEX
                             w/extended linear addressing

UNLOAD86 FOOBAR.COM/LE   <-- produces a hex file called FOOBAR.HEX
                             w/extended addressing

UNLOAD86 FOOBAR.COM/EL   <-- products a hex file called FOOBAR.HEX
                             w/extended linear addressing

UNLOAD86 FOOBAR.COM      <-- produces a hex file called FOOBAR.HEX
                             w/extended addressing if input >64K

UNLOAD86 FOOBAR.COM/P0   <-- produces a hex file called FOOBAR.HEX
                             padded to 32 bytes.

UNLOAD86 FOOBAR.COM/PF   <-- produces a hex file called FOOBAR.HEX
                             padded to 1M byte, w/ extended addressing

UNLOAD86 FOOBAR.COM/PFO  <-- produces a hex file called FOOBAR.HEX
                             padded to 1M byte, WITHOUT extended addressing

UNLOAD86 FOOBAR.COM/PFE  <-- produces a hex file called FOOBAR.HEX
                             padded to 1M byte, w/ extended addressing

UNLOAD86 FOOBAR.COM/EPF  <-- produces a hex file called FOOBAR.HEX
                             padded to 1M byte, w/ extended addressing

UNLOAD86 FOOBAR.COM/EPFB <-- produces a BNPF file called FOOBAR.BNP



Notes, patches, etc.:

UNLOAD86 cannot realisticly handle binary input larger than a megabyte as
the extended addressing scheme runs out of addresses.  If you unload a file
larger than 1 megabyte, the extended addressing will wrap around if it has
been selected with the /E or the /Px options.  This limitation does not apply
if you use the /L switch to select the extended linear address records.


There are several user patchable options that can be patched with DEBUG.
They are as follows:

102:  FF   This is the data that is padded when using the /Px option.
           Change to meet your requirements.

103:  'PN' Change to 'HL' for BHLF output instead of BNPF, or '10' for B10F.
           Or any other two ASCII characters for other variations of this.

105:  '.'  This is the dot for the hex filename.  Must not be changed...

106:  'HEX' Output file type for INTeL hex.  Change to meet your needs

109:   00  This is the termination for the hex filename.  Don't change...

10A:  '.'  This is the dot for the BNPF filename.  Must not be changed...

10B:  'BNP' Output file type for BNPF.  Change to 'BHL' for BHLF, or
            'B10' for B10F, or to whatever filetype you prefer for this
            format.

10E:   00  This is the termination for the BNPF filename.  Don't change...

10F:   00  Change to FF to add a control-Z to the end of file by default.
           In this case, the Z switch turns control-Z OFF instead of ON.


This program was written by Mark D. Pickerill on the Pro-Log ABL-2 CP/M
microcomputer. (what else?)  It bears no resemblance to UNLOAD 2.2 or
2.3 for CP/M by the same author.

THE USER BEARS ALL RESPONSIBILITY FOR TESTING AND USE!  IF THE PROGRAM
MANGLES YOUR DATA, BLOWS YOUR HARD DRIVE, MAKES YOUR CAT BARF ON YOUR
KEYBOARD, OR HAS OTHER UNDESIRED EFFECTS, YOUR SOLE RECOURSE IS TO
DISCONTINUE USE OF THE PROGRAM!!


UPDATES:

Ver. 1.5a.  Very minor cleanups to source code and documentation.  Made
the /Z option a toggle rather than a set.  No real functional changes, so
this is just the new 1.5 that will be distributed. 06/04/92

Ver. 1.5  After considerable work, and three tries, I have finally hung
a buffered disk I/O routine onto the program.  I've learned a good deal
about 80x86 programming in general, and disk I/O in particular in the four
years this program has been under development.  As the original disk routines
were closely tied to the actual UNLOAD routine, an attempt to increase
the size of data read by these routines was scrapped as un-workable.  Instead,
I borrowed a technique from my CP/M BIOS hacking days called BLOCK/DEBLOCK.
The original routines see no difference in their I/O requests, but instead
calls a couple of new routines pass the data back and forth, and maintain
a rather large set of disk I/O buffers.  The result?  As you might expect,
a huge increase in speed.  A test file, 271,634 bytes long was used.  Ver.
1.4 took 1:42 to UNLOAD this into Intel hex on a 25MHZ '286.
The new ver. 1.5 only took 0:16.  A test of BNPF resulted in 3:15 vs. 0:36
for the new version.  Plus it no-longer bangs the disk heads reading and
writing all those little blocks of data.  This was all done with a slight
DECREASE in size from 1.4 due to more intellegent buffer overlaying of the
help screen.  No operational differences from 1.4.  Released 04/23/92,
one year to the day that 1.3 was released!

Ver. 1.4  After receiving multiple complaints, I found and fixed a bug
that wrote 6 garbage bytes after the EOF mark.  Well-behaved programs
were not affected, but as MS-DOS is *full* of ill-behaved programs....
09/25/91  Also added the Z switch to turn on the CNTRL-Z EOF mark.

Ver. 1.3  It has come to my attention that Intel has finally patched
their specification to accomodate files larger than 1 Megabyte with the
addition of the "Extended Linear Address Record".  Support for this has
been added.  Also changed the help screen such that if the user patches
the file type for .HEX or .BNP, that the help screen will reflect this
change.  Added Intel hex discussion to the documentation.  04/23/91

Ver. 1.2  After receiving multiple complaints, I changed the command line
parser so that spaces are now allowed between the filename and the switch
character.  Added - and [ as alternate switch characters for UNIX and CP/M
types.  Input files larger than 64K now automaticly generate extended
address records unless overridden with the /O switch.  /O also overrides
forced extended addressing on the larger /Px options.  Added ERRORLEVEL
support. 01/18/91

Ver. 1.1  Corrects a bug that dis-allowed zeros in the output filename.
An input file of ROM0.BIN would be unloaded to ROM.HEX instead of
ROM0.HEX.  Spurious bugs possibly could have also appeared if the input
filename had no extension. 10/3/88

Ver. 1.0  Initial release. 8/10/88


DISCUSSION OF INTEL HEX:

Intel hex is a method of representing binary data as ASCII data.  This
has several advantages.  First, it can be viewed and changed with ordinary
text editors.  Second, the data has a checksum so that transmission errors
can be detected.  Third, it is an excellent way to transfer binary data through
a 7 bit port or with software that only has ASCII transfer capability.  Fourth,
and lastly, additional information such as load addresses and execution start
addresses are incoded in the file.  It has one drawback however.  The Intel
hex file is always at least slightly more than twice the size of the binary
file it represents.

Intel hex is represented in records.  All records have the same format.
They start with a colon, this is followed by a two digit byte count which tells
how many data bytes are in the data field.  This is followed by a four digit
load address which tells where the data loads in memory.  Then comes a two
digit record type specifier (discussed below) which tells what kind of record
this is.  Then comes 1 or more bytes (two or more digits) of actual data.  Last
comes a one byte (two digit) two's complement checksum (modulo-256) of
everything that came before, except of course, the colon.  Anything that comes
after this checksum, such as carriage return - line feed pairs, etc. is
ignored until the next colon.

:020000020000FC

This is a typical Intel hex record.  We will add spaces for clarity:

: 02 0000 02 0000 FC --Checksum
|  |   |  |    |
|  |   |  |    --Data bytes, two in this example
|  |   |  --Record type
|  |   --Load address for data
|  --Byte count of data record
-- Leading colon

RECORD TYPES:

There are currently 6 types of records.  The Intel hex specification has
undergone 3 different revisions over the years.  The original specification
only defined two record types, then the next revision added one more, and
the most recent has added three more to that.  These revisions were made such
that software that processes Intel hex need only write one routine to process
all different types.  Unfortunately people cannot seem to realize this and
use 3 different routines to process data that was intended to be backwards
compatable.  The exact same problem exists with the XMODEM file transfer
protocol.  XMODEM checksum, XMODEM CRC, and 1K XMODEM are all backwards
compatable, yet most file transfer software makes you select between the three.


00 - Data record

This record has a 00 in the record type field.  The byte count is typicaly
10 or 20 (hex), although it can be any number from 01 to FF.  The "wider"
the record (larger the byte count), the less overhead there is in the file,
but the checksum is less reliable.  Some software cannot handle byte counts
larger than 40.

01 - End record

This record has a 01 in the record type field.  This is the only record
type which can have (and always does have) a byte count of zero.  The most
common end record is :00000001FF.  This is a byte count of zero, a load
address of zero, a record type of 1, and the checksum of FF.  What most
people don't know is that the start execution address of the file can be
stored in the address field, with appropiate alterations to the checksum.
However, a lot of software will barf if it encounters a end record other than
the one shown here.

The above two types are the original Intel hex specification

02 - Extended address record

This record has a 02 in the record type field.  Its byte count is always 02.
It has a load address of zero, and the extended address is in the two data
bytes.  Why the address isn't stored in the address field for this, and all
succeeding record types is unknown.  This record type was added by Intel when
they introduced the 8086.  What Intel didn't make clear at the time was the
fact that this two byte extended address is actually a *segment* address.
It represents address bits 4 through 19.  So this address is the tired old
segment addition:

     0000  -- "Extended address"
      0000 -- "Load address"
     00000 -- "Physical address"

Some software, especially software written to do Intel hex for other processors
such as the 68000 family, use the extended address record to represent address
bits 16-31.  This is incorrect!  When Intel (finaly) introducted a processor
capable of doing flat addressing, they added record type 4 for this purpose.
When UNLOAD86 uses this type of record, it starts at zero and increments it
in blocks of 64K which adds 1000 hex to this segment address.

The above three types are the "Rev 2" Intel hex specification

03 - Extended start address

This record has a 03 in the record type field.  Its byte count is always 02.
It is otherwise identical to record type 02, and is used to indicate the
segment start execution address of the file.  As UNLOAD86 has no way of knowing
this information, this record type is not supported.

04 - Extended linear address record

This record has a 04 in the record type field.  Its byte count is always 02.
The data field contains the extended linear load address, address bits 16-31.
This is the much more sensable extended address record.  When UNLOAD86 uses
this type of record, it starts at zero and increments it in blocks of 64K
which merely adds one to this address.  A lot of software cannot handle any
of these new record types.  It is recomended that this type of addressing be
used if your application and your software permit it, rather than record
type 02.  Although it is perfectly legal to use both types, UNLOAD86 only
uses one at a time as it is converting a contiguous binary file to Intel hex,
thus it doesn't make a lot of sense to use both.  Both types might be used
in the case of a compiler or assembler output where the data is non-contiguous.

05 - Extended linear start address

This record has a 05 in the record type field.  Its byte count is always 02.
It is otherwise identical to record type 04, and is used to indicate the
extended linear start execution address of the file.  As UNLOAD86 has no
way of knowing this information, this record type is not supported.


Discussion of BNPF:

BNPF is an old paper tape format that still crops up from time to
time.  It has a couple of varients, BHLF, and B10F.  They all work the
same way.


BPNPNNPNPF  ... Represents one byte.  The B stands for Begin.  The
following 8 Ns and Ps stand for Negative or Positive.  The F stands for
Finish.  Thus the byte pictured is A5 hex.  BHLF uses H & L for High
and Low instead of N & P.  B10F uses 1 and 0.  These are all ASCII characters,
although I suppose they could be coded in Baudot as well.  You'd think
from the name that BNPF would really be called BPNF, but it never is.