HC Software Development Kit for Retro Computing [Veja em Português]

This document is under construction

Aiming to create an assembly SDK focused on retro computing, using NASM code style as a base, making it easier for new users coming from x86 to migrate to 8-bit processors.

This set of tools is distributed under the 4-Clause BSD License.

Tool	Description
	Assembler with structure and code style based on NASM
	Object linker and executable generator from objects and libraries
	Project manager, responsible for compiling and cleaning project output files
	Library manager, which are sets of objects that can be referenced by a project

Links to distribution/installation files

Download for browsers that do not support javascript

Installer for Windows (Intel 32-bit)

Binary package for Windows (Intel 32-bit)

Installer for Windows (Intel 64-bit)

Binary package for Windows (Intel 64-bit)

Installation package for Debian/Ubuntu or compatible (Intel 64-bit)

Binary package for Linux (Intel 64-bit)

Installer for macOS (Intel 64-bit/Apple Silicon)

Binary package for macOS (Intel 64-bit/Apple Silicon)

Source Code Samples

Download for browsers that support javascript

Latest version directly from GitHub

HC Assembler for Retro Computing

Assembler compatible with NASM style.

Both the source code and the generated binary are composed of sections, as follows:

• Text: Section where the executable code resides
• Data: Section where initialized data resides
• BSS: Section where uninitialized data resides

The sections are independent and their contents are grouped sequentially in the order they are defined in the file, so even if the section contents are defined interleaved and mixed, the result will always be grouped by section.

The assembly source code consists of a few distinct blocks of information:

• Labels and Constants
• Only one per line, always at the beginning of the line
  
• Mnemonics (CPU instructions) and their arguments
• Only one per line, after the label if present
• Their arguments come right after the instruction, separated by commas
  
• Comments
• Only one per line, if located at the end of the line
  
• Assembler Directives
• They replace mnemonics, but do not necessarily generate binary code, and are processed by the assembler as internal commands.
• Their arguments come right after the directive, separated by commas

The directives accept as arguments values in the format supported by the assembler.

All topics listed above will be explained in more detail later

Example:

Supported Architectures

• Intel 8080 or Compatible via hcasm-8080
  
• Intel 8085 or Compatible via hcasm-8085
  
• Zilog Z80 or Compatible via hcasm-z80
  
• Intel 8086/8088 or Compatible via hcasm-8086
  

Usage

For each supported architecture, an assembler executable is provided, with the name starting with "hcasm-" followed by the supported processor.

Example to compile Z80 code (file.s) into an object (file.obj):

Label Definition

There are 2 types of labels:

• Primary Label
• Any label starting with a letter
• The label name can contain letters, numbers, and underscore '_'
  
• Accessible throughout the file directly
• The label is defined as the current primary label until the definition of the next primary label, and all its secondary labels can be called directly without the primary label prefix
  
• Secondary Label
• Any label starting with a dot '.'
• Accessible within the current primary label directly, or externally using the primary label name as a prefix. Example: .secondary1 (accessible only within the current primary label) -> primary1.secondary1 (accessible from the entire current file)

Optionally for better identification, a label definition can be followed by the character ':' as a separator between the label and the next mnemonic/assembler directive; however, when using a label name as a reference to an existing label, the use of the ':' character is forbidden.

Any label that is not present in the current file but is referenced in it will be automatically considered as coming from another object, and will be handled by HC Linker.

Example (Intel 8086/8088 code):

Constant Definitions

Every constant is declared as a label, following the same rules. (See Labels)

What differentiates a label from a constant is that instead of containing a pointer to that position in the source/binary, it contains a predefined value.

Constants can be either secondary or primary to other constants or labels, with no distinction in their use in source code; however, constants are not subject to relocation calculation, making them useful for fixed memory references.

To declare a constant, simply declare a label and on the same line after the label use the marker 'equ' followed by the desired expression.

Example:

Argument Values

As arguments for directives, values are accepted in the following formats:

• Decimal value. Example: 123
• Hexadecimal value. Example: 0x1234
• Octal value. Example: 0o777 or 0777
• Binary value. Example: 0b10101010
• Character value. Example: 'A'
  
• String. Example: "Text in double quotes"
• Processor Register. Example: AX or ax
  
• Previously defined constants. Example: test_const
  
• Address for data manipulation. Example: [label]  or  [mathematical expression]  or  [register]  or  [label + mathematical expression]  or  [register + mathematical expression containing constants and/or values]
• Direct address. Example: label
  

When used as arguments, they must be separated by commas.

Example (in 8086/8088):

Assembler Directives

To aid development, the assembler supports several basic directives based on their NASM equivalents.

DB and DW

This directive emits binary directly to the output file, and can only be used in the TEXT and DATA segments.
The bytes (db) or words (dw) are emitted according to the sequence of numbers given as arguments to the directive.
There is no limit on the number of arguments, and they can be numeric or strings.

RB/RESB and RW/RESW

This directive reserves an empty space in the output file.
Reservations of bytes (rb or resb) or words (rw or resw) are made according to the quantity given in its argument.

TIMES

This directive repeats the content that follows it a defined number of times in the output file

SECTION

Changes the current output section, allowing interleaving of multiple output sections in the same file.

Supported sections: text, data, bss*
* The BSS section does not support any directive that generates binary data, only directives that reserve space and labels of all types are allowed

HC Linker for Retro Computing

Merges necessary objects to create executables.

Executables, regardless of output format, are built as follows:

• Object files will be read in the order provided to the linker, always using the first object as the root
• From the root object, all references to other objects are mapped recursively
  
• Objects that are not directly or indirectly referenced by the root object and its dependencies are discarded from the final executable
• Each section is emitted sequentially: TEXT, DATA, and BSS
• If it exists and if the format requires it, the label _start will be used as the executable entry point

Supported Output Formats

Usage

When calling the linker, you should call the version equivalent to the desired format, specifying the output file and the objects and libraries

Linker Constants

These constants are automatically added during linking and editing of objects to generate the final executable.

HC SDK Object Format

An object is a file made up of individual records, each executing a command when creating the final executable.

Object Record Format

Record Types

The list below is subject to future additions; as a reference, the file include/obj.h should be used as the official basis.

• Source Code
  
• 0x00: Source file name (Content: File Name)
• 0x01: Position in source code (Value: Line; Auxiliary: Column)
• 0x02: End of file (Content: File Name)
• Section
  
• 0x10: Change current section to TEXT (Executable code section)
  
• 0x11: Change current section to DATA (Data section containing initial data)
  
• 0x12: Change current section to BSS (Section allocated at load time, containing no initial data)
  
• 0x13: Change current section to RELOC (Special section that stores relocation pointers in memory during loading)
• Data
• 0x20: Emit Binary Data in the current section (Content: Binary Data)
• 0x21: Reserve blank space in the current section (Value: Space size)
• Constants
• 0x30: Local label marking the current position in the current section, must be unique per file (Content: Label Name)
• 0x31: Local constant (Content: Constant Name; Value: Initial value of the constant)
• 0x32: Export Constant/Label globally, visible to other objects (Content: Constant/Label Name)
• Mathematical and Logical Expressions
• 0x40: Reset value stack
• 0x41: Push a value specified using signed 16-bit integer format (Value: Value to push)
• 0x42: Push a value specified using unsigned 16-bit integer format (Value: Value to push)
• 0x43: Push the current position in the current section of the executable binary (Value: Offset considering the start of the opcode if necessary)
  
• 0x44: Push the value of a constant/label (Content: Constant/Label Name)
• 0x45: Push the segment of the current section, used in multi-segment per section files
• 0x50: Pop two values, add the first value to the second popped value, push the result (PUSH(SECOND POP() + FIRST POP()))
  
• 0x51: Pop two values, subtract the first value from the second popped value, push the result (PUSH(SECOND POP() - FIRST POP()))
• 0x52: Pop two values, multiply the second value by the first popped value, push the result (PUSH(SECOND POP() * FIRST POP()))
• 0x53: Pop two values, divide the second value by the first popped value, push the result (PUSH(SECOND POP() / FIRST POP()))
• 0x54: Pop two values, divide the second value by the first popped value, push the resulting modulo (PUSH(SECOND POP() % FIRST POP()))
• 0x55: Pop two values, shift left the second value by the number of bits in the first popped value, push the result (PUSH(SECOND POP() << FIRST POP()))
• 0x56: Pop two values, shift right the second value by the number of bits in the first popped value, push the result (PUSH(SECOND POP() >> FIRST POP()))
• 0x57: Pop one value, logically invert the value, push the result (PUSH(~POP()))
• 0x58: Pop two values, perform logical AND of the second value with the first popped value, push the result (PUSH(SECOND POP() & FIRST POP()))
• 0x59: Pop two values, perform logical OR of the second value with the first popped value, push the result (PUSH(SECOND POP() | FIRST POP()))
• 0x5a: Pop two values, perform logical EXCLUSIVE OR of the second value with the first popped value, push the result (PUSH(SECOND POP() ^ FIRST POP()))
• 0x60: Pop a value and save it in a constant (Content: Constant name)
• 0x61: Pop a value and emit it in the output binary as a single byte
• 0x62: Pop a value and emit it in the output binary as a single word (2 bytes)
• 0x63: Pop a value and emit it in the output binary as a single word (2 bytes), marking the emitted position as relocatable
• 0x64: Pop a value and start repeating the following commands the number of times contained in the popped value
• 0x65: Mark the end of the list of commands to be repeated by the previous command
• Architecture / Processor Identification
• 0xf0: Intel 8080 or compatible
• 0xf1: Intel 8085 or compatible
• 0xf2: Zilog Z80 or compatible
• 0xf3: Intel 8086 or compatible
  

Relocatable Executable Format

The file contains a header describing the file content, which must be discarded during loading, and is disregarded in relocation calculation.

Sections are placed sequentially in the file, following the order:

• Header
• Text Section
• Data Section
• Relocation Table

The BSS section is allocated during loading, placed after the Data section.

Relocation

When loading the sections to the target memory location, the relocation records must be read according to the format described below:

How to perform relocation:

• Go to the address considering: ADDRESS = INITIAL LOAD MEMORY POSITION + POSITION CONTAINED IN THE RECORD
• Read a word (2 bytes)
  
• Add the value of the Initial Load Memory Position
• Save the word (2 bytes) at the same position that was read
  

HC Builder for Retro Computing

Coordinates actions for compiling and maintaining projects

Usage

To compile a configuration, it must be called with the make action followed by the configuration

To clean the output files from a previous compilation, simply call with the clean action followed by the configuration

Project File Format (*.prj)

The file follows the format compatible with the standard INI configuration file, where files are separated into sections and variables, and comments start with the character ';'

Example of a project for generating a relocatable executable:

[link:CONFIGURATION] Section

• format =
• Specifies the output file format
  
• Accepts bin or rex
• Required
• filename =
• Specifies the output file name
• Default value: a.out
• Optional
• symbols =
• Specifies the symbol file name
• Generates the symbol file only if this field is provided
  
• Optional
• Exclusive to: format = bin
• text =
• Target memory position for the TEXT section
• Default value: 0
• Optional
• data =
  
• Target memory position for the DATA section
• Default value: allocated immediately after the TEXT section automatically
• Optional
• bss =
  
• Target memory position for the BSS section
• Default value: allocated immediately after the DATA section automatically
• Optional
• align =
• Specifies the alignment of segments
• Default value: 16
• Optional
  

HC Librarian for Retro Computing

Groups objects into a single library

The library follows the same object format, simply allocating the object records sequentially in the library file

Usage

When calling the librarian, you must provide the name of the library to be created/edited, followed by the objects to be added/replaced

Licensing