  ___  ___       _
 / _ \/ __|_ __ | |__  __ _
|  _  \__ \ '  \|  _ \/ _` | 0.02 (11 October 2000)
|_| |_|___/_|_|_|_| |_\__, |  Darren Salt, 2000
                      \___/

This software is COPYRIGHT, but has been released as FREEWARE. Please see the
end of this file for conditions of use and distribution.

ASmhg is intended for use alongside AS and DRLink to produce relocatable
modules. It requires a descriptor file which contains the module title and
help string, and a description of the commands and help the module provides,
as well as the SWI names list.

THIS PROGRAM DOES NOT GENERATE MODULE HEADERS SUITABLE FOR USE WITH CODE
GENERATED BY ANY C or C++ COMPILER whether directly or via an intermediate
assembly stage. It only generates files suitable only for linking against
files produced by an AOF assembler such as AS.


Installation


Somewhere appropriate, for example in the same directory as the AS
executable.


Usage


ASmhg [options] [descriptor file]

The descriptor file is simply the file which describes the module header
(detailed below).

-o <filename>           The output file.
--output=<filename>     ASmhg -o o.header asmhg.header

-h, --help              Display the help text.
-v, --version           Display the version information.


For each command that has both help text and syntax string, the help text
will be CR-terminated instead of the more normal NUL-termination such that
the syntax string forms part of it. This is, however, not done if a messages
filename has been supplied.


There is no provision for zero-init areas; any extra workspace you need
should be claimed and released explicitly by your code, in the usual way.


Descriptor file contents


The following tokens collectively describe the module header. Each may be
omitted or used once, unless otherwise indicated.

runnable:
        This specifies that the module has an entry point (and so may be
        *Run). This is linked directly to a function called "main".

initcode: <function>
        This specifies that the named function be called on module
        initialisation. (The relocation code, automatically generated by
        DRLink, is called prior to any other initialisation code.)

finishcode: <function>
        This specifies that the named function be called on module shutdown
        (when it's RMKilled).

service: <function>
        This specifies that the named function be used as the module's
        service call handler.

moduletitle: <text>
        The supplied text is used as the module's title.
        The module must have a title.

modulehelp: <text>
        The supplied text is used as the module's help string.
        The module must have a help string.

commands:
        This introduces a list of tokens which describe the module's command
        and help keywords list. You may specify as many as you need. The
        following list describes the available tokens.

  cmd: <name>
        Command keyword.
        Requires: call, args
        Optional: help, syntax
  info: <name>
        Information keyword.
        Requires: help
  config: <name>
        Configuration keyword.
        Requires: call
        Optional: help
  fscmd: <name>
        Filing system command keyword.
        Requires: call, args
        Optional: help, syntax

        The following tokens describe each keyword.

  call: <function>
        The function called by this keyword.
  args: <number>
        The number of arguments which must be supplied. This is equivalent to
        specifying both minargs and maxargs.
        (Where args is required, minargs and maxargs may be used instead.)
  minargs: <number>
        The minimum number of arguments which must be supplied.
  maxargs: <number>
        The minimum number of arguments which must be supplied.
  help: <text>
        The help text for the keyword. This is in GSTrans format so that you
        can make use of RISC OS's dictionary (and include CRs).
  helpcode: <function>
        The help text generator for the keyword.
        (You cannot use both help: and helpcode:.)
  syntax: <text>
        The syntax string for the keyword. This is also in GSTrans format.

        The GSTrans format is only partially implemented: in particular, <>
        may only contain decimal or hex values. NULs are not allowed.

swichunk: <number>
        The SWI chunk number for the module.
        Range 0x00000040 to 0x00FFFFC0; must be a multiple of 64.
        May not be specified without an SWI handler function.

swihandler: <function>
        The SWI handler function.
        May not be specified without an SWI chunk number.

swinames: <list>
        A comma-separated list of SWI names, the first of which is the SWI
        prefix for the chunk used by this module.
        May not be specified without an SWI chunk number.
        No more than 65 names may be specified.

swidecoder: <function>
        The SWI decoder function. Only use this where you need to trap old
        SWI names.
        May not be specified without an SWI handler function.

msgsfile: <filename>
        This is the name of the file which will be used to expand the
        keywords' help and syntax strings. Usage of this facility limits the
        module to RISC OS 3.60 and later.


Exported symbols


Currently, none.

Sensible suggestions welcome, as they are for anything else concerning ASmhg.


Example descriptor file


title:          ExampleMod
help:           Example module  0.00 (xx yyy zzzz)

commands:
    cmd:        wibble
        call:   wibble_code
        args:   0
        help:   Does nothing.
        syntax: |[|A
    cmd:        flurble
        call:   flurble_code
        args:   0
        help:   Does nothing.

initcode:       module_init
finishcode:     module_finish


Portability notes


This program relies on RISC OS-like environments (eg. endianness, word size,
alignment; ISO-8859, or at least ASCII, character sets). It avoids short
ints, and relies on bitfields in a few places; identically functional code
should consequently be produced on any RISC OS-based compiler.


Copyright


This software and its associated documentation may only be distributed in
unmodified form (ie. no files may be altered, and no files may be omitted).
Where it is available, so must AS be, whether explicitly or implicitly as
part of GCC.

This software is provided as is with no warranty as to its suitability or
otherwise for any particular task. If it does anything nasty then I want to
know so I can fix it, but I cannot (and cannot afford to) take any
responsibility.

Please note that I reserve the right to make alterations to this program, its
operation, documentation, and/or conditions of use without notice in any way
I see fit. I rarely see fit to make things worse :-)


Contact


Darren Salt - ds@youmustbejoking.demon.co.uk
