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.

1 Legal
=======

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

2 Additional options for this version
=====================================

'-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.
'-keepempty'
     Do not delete empty sections without any symbol definition.

   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.

3 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.

4 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.

5 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.

6 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 suppported
   - 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
