This chapter describes the AmigaOS hunk-format output module which can be selected with the -Fhunk option to generate objects and with the -Fhunkexe option to generate executable files.

Legal
=====

This module is written in 2002-2022 by Frank Wille and is covered by the vasm copyright without modifications.

Additional options for this module
==================================

-hunkpad=<code>
     Sets a two-byte code used for aligning a code hunk to the next 32-bit border. Defaults to 0x4e71 for M68k code sections, to allow linking of functions which extend over two object files. Otherwise it defaults to zero.

-keepempty
     Do not delete empty sections without any symbol definition.

-kick1hunks
     Use only those hunk types and external reference types which have been valid at the time of Kickstart 1.x for compatibility with old assembler sources and old linkers. For example: no longer differentiate between absolute and relative references. In executables it will prevent the assembler from using 16-bit relocation offsets in hunks and rejects 32-bit PC-relative relocations.

-linedebug
     Automatically generate an SAS/C-compatible LINE DEBUG hunk for the input source. Overrides any line debugging directives from the source text.

These options are valid for the hunkexe module only:

-databss
     Try to shorten sections in the output file by removing zero words without relocation from the end. This technique is only supported by AmigaOS 2.0 and higher.

General
=======

This output module outputs the hunk object (standard for M68k and extended for PowerPC) and hunkexe executable format, which is a proprietary file format used by AmigaOS and WarpOS.

The hunkexe module will generate directly executable files, without the need for another linker run. But you have to make sure that there are no undefined symbols, common symbols, or unusual relocations (e.g. small data) left.

It is allowed to define sections with the same name but different attributes. They will be regarded as different entities.

Restrictions
============

The hunk/hunkexe output format is only intended for M68k and PowerPC cpu modules and will abort when used otherwise.

The hunk module supports the following relocation types:

  - absolute, 32-bit

  - absolute, 16-bit

  - absolute, 8-bit

  - relative, 8-bit

  - relative, 14-bit (mask 0xfffc) for PPC branch instructions.

  - relative, 16-bit

  - relative, 24-bit (mask 0x3fffffc) for PPC branch instructions.

  - relative, 32-bit

  - base-relative, 16-bit

  - common symbols are supported as 32-bit absolute and relative references

The hunkexe module supports absolute 32-bit relocations only.

Known Problems
==============

Some known problems of this module at the moment:

  - The hunkexe module won't process common symbols and allocate them in a BSS section. Use a real linker for that.

Error Messages
==============

This module has the following error messages:

  - 3001: multiple sections not supported by this format

  - 3002: output module doesn't support cpu <name>

  - 3003: write error

  - 3004: section attributes <attr> not supported

  - 3005: reloc type <m>, size <n>, mask <mask> (symbol <sym> + <offset>) not supported

  - 3006: reloc type <n> not supported

  - 3009: undefined symbol <%s> at %s+0x%lx, reloc type %d

  - 3010: section <%s>: alignment padding (%lu) not a multiple of %lu at 0x%llx

  - 3011: weak symbol <%s> not supported by output format, treating as global

  - 3014: data definition following a databss space directive

  - 3016: absolute file path exceeds maximum size of %d characters

  - 3017: converting NONE relocation <%s> to 8-bit ABS with zero addend

  - 3018: no additional space in section to convert NONE relocation <%s> to ABS

  - 3019: section <%s>: kickstart 1.x cannot initialize bss sections >256k to zero