Table of Content  Branch Up  

Overview

The H1ASM v.0 assembler is designed to work without a Linker companion; the assembler directly produces executable code, implying that it will not export symbols and it won't work with precompiled object code or libraries which is indeed a limitation.

It does, however, accept source file inclusion which allows for organizing a large project into manageable source modules. It also implements the notion of variable which, combined with file inclusion, will hopefully help in writing structured, reusable, maintainable code.

Macros, conditional compilation, pseudoinstructions and other advanced features are not implemented in this version but plans exist for provide those in the near future.

The assembler's main file is a PHP script named: h1asm.php. Assuming you have exec writes on that script, you launch the assembler with the following command:

h1asm.php  main_src_file_path  include_dir

The first argument is a path to the intended main source file. The second argument is optional and refers to the directory where included files are located; if missing, the assembler will extract the include directory from the first argument assuming that the main file is placed together with all included files.

The assembler processes the source file one line at a time. Lines are trimmed before processing so leading spaces and tab characters can be inserted for better formatting if desired. Each line could be one of the following types:

- Blank line                : Will be ignored
- Comment                      : Starts with semicolon (;)
- Instruction               : Syntactically valid Hieritage/1 instruction
- Label                     : Symbolic address. Start with colon (:)
- Symbol definition         : In the form SYMBOL equ VALUE, or: #define SYMBOL = VALUE
- Origin directive             : In the form #org ADDRESS
- Data directive            : In the form #data EXPRESSION
- Output Format directive   : In the form #format FORMAT
- Include directive         : In the form #include FILE_NAME

Comments cannot appear in a line that is not a comment. Following is an example of acceptable assembly code.

; Listing #1
; ----------------------------------------------------
; HERITAGE/1 -- SAMPLE ASSEMBLY CODE
; ----------------------------------------------------
; This code implements INT 7 both vector and handler code
;   for copying BUFF_SIZE words from BUFF_SRC to BUFF_DES
;
#format H12
#include vectors.equ
        INT_7_CODE      equ     0x0400
        BUFF_SRC        equ     0x4000
        BUFF_DES        equ     0x0800
        BUFF_SIZE       equ     0x0020
    
#org    INT_7_VECTOR
#data   INT_7_CODE

#org    INT_7_CODE
         mvi        c,    BUFF_SIZE
         mvi        d,     BUFF_SRC
         mvi        e,    BUFF_DES
:LOOP
         ldx        a, d
         stoxa, e
         inc        d
         inc        e
         dec        c
         jnz        LOOP
         jp        QUIT

; garbage, just to justify the forward jump
#data    0xffff            

:QUIT
    ret

The assembly process results in two files:

- Code file (.bin)            : Executable (binary) code.
- Listing file (.lst)      : As built (ASCII) listing of source with numeric
                             addresses and error messages if any as well as
                             extra info such as the Symbols Table.

The assembler creates their filenames from the source filename by replacing the file extension with .lst and .bin respectively.

The code file (.bin) is built acording to one of the following formats (indicated in code by the directive #format FORMAT):

- H10 : Exact image of code in memory using relative branch instructions only.
- H11 : Monolithic code with header specifying the ORG address.
- H12 : Fragmented code with header specifying different ORG addresses.
- H13 : Relocatable code with header indicating words (off-sets) in need
        for relocation.

These different formats are targeted to different operational environment that the target computer may offer. At early stage of development, no operational environment exists so formats H10 and H11 are the most appropriate. Format H12 is useful for full memory dumping including vectors (such as in Listing #1). Format H13 is better suited for applications in presence of a Loader capable of relocation.

If #format H10 is specified, the Assembler will translate absolute branch instructions to relative ones, automatically. If the directive is missing, format H12 will be assumed.

The assembler reports errors in the Listing file (.lst) in the form of single-line messages inserted right after the line where the error was found. The code file (.bin) will not be produced if errors have occurred.

There is no distinction between "errors" and "warning"; errors are simply errors and will be reported as such.

Error checking depends on the targeted format. For example, duplicated #org directives will be reported if H11 format was requested.