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

		hp21asm Directory

This directory provides three programs:

	hp21asm - A cross-assembler for the HP2100 series.

	hp21abs - A utility program for HP21xx Absolute Load format (ABS) files, providing two functions:
			- Display of the structure and contents of an ABS file.
			- Concatenating multiple ABS files into a single ABS file.

	hp21cvt - A utility program to convert to/from ABS format:
			- Conversion of ABS format to octal XNS format.
			- Conversion of octal XNS format to ABS format.
			- Extracting the octal object code from assembler listings and outputting it in ABS format. 

		hp21cvt may be used to convert the block size of absolute files by converting to XNS and back to ABS,
		with the blk size specified in the latter conversion, e.g.:

			hp21abs -ax < file.abs | hp21abs -xa -m 128 > filenew.abs

--------------------------
LOG:
	2014 Oct: This README file created / bhilpert.
	2014 Nov / hp21asm: Reformatted.
	2014 Nov / hp21asm: Allow output files to be specified at invokation, rather than fixed names.
	2014 Nov / hp21asm: Allow ABS block length to be specified at invokation.
	2014 Nov / hp21asm: bug in EOL test fixed.
	2014 Nov / hp21asm: bug in parse_dec fixed, parsing wasn't checking for '-' in exponent.
	2014 Nov / hp21asm: Symbol scoping added, longer symbols allowed.
	2014 Nov / hp21asm: Allow tabs as spaces.
	2014 Nov / hp21asm: Allow empty lines.
	2014 Nov / hp21asm: SKP & SPC directives done.
	2014 Nov / hp21asm: File List module added, with INC directive.
	2014 Nov / hp21asm: Tests added in try routines to avoid false positives by checking for end of instruction.
	2014 Nov / hp21asm: Allow modern number syntax, MDN directive.
	2014 Nov / hp21asm: STR directive added.
	2014 Nov / hp21asm: Split into multiple files.
	2014 Dec / hp21asm: Machine instruction generation redone as table.
	2021 Oct: Makefile corrected to include .h files in tar / bh.


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

		hp21asm - A Cross-Assembler for the HP-2100 Series

--------------------------
THIS PROGRAM:

This program began as the "hpasm" assembler, the source of which was traced back to:
	http://www.taurus.com/~jeff/2100/emulator/index.html
It has since been reformatted, split into multiple files, and various modifications, extensions and fixes added.

This program relies on only a few very basic standard C library routines.
As such, it should be compilable and executable on many systems
supporting the C language. 32-bit or larger ints are expected.
Current development was done under MacOSX-10.7.5.

				bhilpert / 2014

--------------------------
ASSEMBLY:

This assembler is intended to assemble source written in the original HP-2100 assembler syntax.
Output is in the form of either or both a binary in HP Absolute Load format and a text listing.
Multiple source files may be specified at invokation and will be treated as a single source stream.
For use options, see the useMsg in hp21asm.c or run "hp21asm -u"

--------------------------
COMPATIBILITY WITH ORIGINAL HP ASSEMBLER:

Relocatable output format is not supported.
As such, the COM, ENT, EXT & ORB directives are not implemented.

The ASMB control statement is ignored. The N & Z conditionals are supported via invokation flags.
The ORR directive is not supported.
The DEX directive is not supported.
Most of the listing control directives are ignored.

--------------------------
EXTENSIONS:

- A simple symbol-scoping mechanism has been added. A symbol starting with "_" is considered a 'local' symbol
and is prepended by the most recent preceding symbol not beginning with an "_".
This allows, for example, the symbol "_loop" to be used in multiple routines within one assembly.

- A MDN (modern) directive has been added to support modern number-base syntax.
The original source code number-base handling is very different than modern standards.
In the original syntax a leading 0 does not imply octal, instead the DEC or OCT directives distinguish
base where they are usable, in other situations a B suffix to a number indicates octal instead of decimal.

For modern sensibilities, the MDN directive switches to leading-zero octal interpretation,
as well as providing ASCII character constants.
Hex is currently still not supported.

- A STR directive has been added to provide quoted, null-terminated strings.
Escaped characters within the string are supported.
There is no need to specify the number of words in the string, in contrast to ASC.

- An INC directive to include files.

--------------------------
HP-2100 ASSEMBLY REFERENCE:

See:	http://www.taurus.com/~jeff/2100/asmref/index.html
or:	http://www.cs.ubc.ca/~hilpert/e/HP21xx/pgmref.html


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


ABS Format:
-----------

Absolute Load Format is an encoding format used with the HP 2100 series computers for loading binary images into a machine.
'Absolute' refers to the encoding containing absolute addresses at which to load data, in contrast to the data being relocatable.

An Absolute Load file is a sequence of 0 or more blocks, followed by a trailer of 10 or more null bytes:

	<AbsFile> = <Block> ... <Block> 0 0 0 0 0 0 0 0 0 0

where each block is a sequence of bytes:

	<Block> = <LEN> <IGNORE> <ADDR_HI_BYT> <ADDR_LO_BYT> <DATA1_HI_BYT> <DATA1_LO_BYT>
                  ... <DATA<LEN>_HI_BYT> <DATA<LEN>_LO_BYT> <CHECKSUM_HI_BYT> <CHECKSUM_LO_BYT>

<LEN> = the number of data words in the block.
The checksum is the sum of the address word and the data words.

The trailer is necessary as an EOF indication for the BBLs.
The null bytes of the trailer correspond to unpunched paper tape.

== EOF ===============================================================================================================
