CMHG
====

C Module Header Generator.
See the Acorn C/C++ manual for further information.

Changes from CMHG 5.02 to 5.10
==============================

1) CMHG now gets the date for the module header from the datestamp of
   the CMHG input file, rather than using the current date. This will
   stop the silly situation of a simple rebuild producing something
   looking like a later version.

2) The date can be overridden using the new keyword "date-string:".
   For example:
   
       date-string:  26 Jun 1974

3) CMHG's help output (*cmhg -h) now details all command-line options.

4) CMHG can now preprocess the cmhg file using the C preprocessor if you
   use the "-p" command line option. This allows code like the following:
   
       swi-chunk-base-number:   0x82880
       
       service-call-handler:    Window_services 0x46, 0x44ec1, 0x44ec2
   
   to be replaced by the more readable and maintainable:
   
       #include "window.h"
       #include "services.h"
       
       swi-chunk-base-number:   Window_SWIChunkBase
       
       service-call-handler:    Window_services Service_ModeChange,
                                                Service_ToolboxTaskBorn,
                                                Service_ToolboxTaskDied

       #ifdef DEBUG
       command-keyword-table:   Window_commands Window_Memory(),
                                                Window_Tasks()
       #endif

   In conjunction with this, CMHG now accepts the command-line options 
   -I and -D. These function in the same way as with the C compiler. Note
   that the default include path (in the absence of -I) is C:.
   
   For example:
   
        cmhg -p -DDEBUG -IC:,TCPIPLibs: -o o.InetHdr InetHdr
   
5) The header file that CMHG outputs is now much more readable. Changes
   include:
   
   a) The file is now bracketed by "#ifndef __cmhg_<filename>" rather
      than "#ifndef __cmhg_defs_h".
      
   b) CMHG_VERSION is #defined to the version of CMHG that generated
      the file, allowing the source to ensure its header was built
      with a new enough version of CMHG.
   
   c) Module_Title, Module_Help, Module_VersionString,
      Module_VersionNumber, Module_Date and Module_MessagesFile are
      #defined according to what was entered in the module header.
   
   d) Function prototypes are defined for each function/veneer
      mentioned in the CMHG file. Extensive comments (more accurate
      than those in the Acorn C/C++) are generated.
   
   e) Useful constants are defined to simplify the rather nasty
      command handler interface.
   
   f) The #define of SWI names is bracketed by a #ifndef to prevent
      problems if you include another header file defining your
      SWIs.      
   
6) CMHG now supports throwback if the command-line option "-t" or
   "-throwback" is specified.

7) Text processing has been slightly altered. \n now inserts ASCII
   code 13, rather than 10, as this is what OS_PrettyPrint expects.
   CMHG now accepts the C \x specifier, eg \x07 to insert ASCII
   code 7.

8) Command descriptions have a new flag "add-syntax:" that signifies
   that the invalid-syntax string should be appended to the help-text
   string.
   
   This means that the standard idiom
   
       MyCommand(help-text: "*MyCommand does something.\r"
                            "Syntax: *MyCommand",
                 invalid-syntax: "Syntax: *MyCommand")
   
   can now be written as
   
       MyCommand(add-syntax:,
                 help-text: "*MyCommand does something.\n",
                 invalid-syntax: "Syntax: *MyCommand")
   
   Note that modules designed for RISC OS 3.6 or later should use
   the internationalised help flag ("international:"). This option
   is then superfluous.

9) CMHG 5.02 (as supplied with Acorn C/C++) had a few undocumented
   features. These are now documented here:
   
   a) The keyword "international-help-file:" to specify the name of
      the file to look up help text in (RISC OS 3.6 or later - see
      PRM 5a-34).
   b) The command description keyword "international:" to set bit 28
      of a command entry, indicating that this command has
      internatialised help.
   c) The command line allows output definitions and object files
      to be specified using -d and -o respectively instead of
      relying on the order of the parameters.
   d) The "-b" flag (b for bodge!). Only used by ShareFS - now
      removed and superceded by library-enter-code (see below).
   e) The keyword "module-is-not-re-entrant:" indicates to the
      C stubs that it need not copy your data into a separate
      RMA workspace area. This could save memory, but will have
      many potentially nasty side-effects. If you're considering
      doing something like this to save memory, you should probably
      look at using TinyStubs.
   f) A documentation clarification: "status:" and "configure:"
      (Acorn C/C++ p286) are exactly synonymous; both set bit 30 of
      the flags word.

10) The "swi-decoding-code" keyword can now accept a pair of keywords
    to specify a text->number and number->text conversion pair. This
    allows nicer prototypes:
    
        swi-decoding-code: text_to_number/number_to_text
    
        int text_to_number(const char *string, void *pw);
        int number_to_text(int swi_no, char *buffer, int offset,
                           int end, void *pw);

11) "irq-handlers" has been deprecated, as IrqV is long obsolete.
    Instead, the keyword has been replaced by "vector-handlers",
    and the comment text placed in the definitions file emphasises
    these veneers use as a general vector hook. "irq-handlers" is
    still accepted, but a warning is emitted.

12) A new type of veneer has been added, the "generic veneer". These
    are designed as a replacement for the common use of irq-handlers
    as general purpose hooks onto OS_AddCallBack etc. They are
    specified in the same way as irq-handlers, but using the keyword
    "generic-veneers:". They work in the same way, except they
    either return preserving processor flags, or set V to
    return an error:
    
       _kernel_oserror *generic_handler(_kernel_swi_regs *r, void *pw);

    The veneer switches to SVC mode, does not alter interrupt status,
    and preserves R0-R11. R12 is corrupted.
    
    In future, generic veneers will be extended to allow them to
    totally replace vector handlers and event handlers. At present
    the generic veneer is totally separate from the vector/event
    veneer in the module header, so using both veneers is slightly
    wasteful of memory.

13) Bug fix: the swi decoding veneer corrupted R4 and R5.

14) The SWI handler veneer made slightly (one instruction!) faster
    in the case of a successful SWI.

15) Your SWI handler can now return the magic error code error_BAD_SWI,
    which will cause the veneer to look up and return the standard
    internationalised 'SWI value out of range for module XXX' error.

16) CMHG will leave out extraneous header fields, saving a few
    words of memory.

17) Fast service and event filtering code changed to use TEQ
    rather than CMP where possible.

18) Fast service filtering code given a few more brain cells.
    Where CMHG 5.02 produced for the ShareFS module the code: 
    
        CMP     R1,#&27            
        CMPNE   R1,#&40            
        CMPNE   R1,#&4B            
        CMPNE   R1,#&4C            
        CMPNE   R1,#&4F            
        CMPNE   R1,#&74            
        CMPNE   R1,#&95            
        CMPNE   R1,#&96            
        STMFD   R13!,{R14}
        MOV     R14,#&C0           
        ORR     R14,R14,#&0100     
        ORR     R14,R14,#&00080000
        CMPNE   R14,R1
        MOV     R14,#&C1           
        ORR     R14,R14,#&0100     
        ORR     R14,R14,#&00080000
        CMPNE   R14,R1
        MOV     R14,#&C2           
        ORR     R14,R14,#&0100     
        ORR     R14,R14,#&00080000
        CMPNE   R14,R1
        MOV     R14,#&C3           
        ORR     R14,R14,#&0100     
        ORR     R14,R14,#&00080000
        CMPNE   R14,R1
        MOV     R14,#&C5           
        ORR     R14,R14,#&0100     
        ORR     R14,R14,#&00080000
        CMPNE   R14,R1
        LDMNEFD R13!,{PC}^
        <rest of veneer>
    
    CMHG 5.10 produces:
    
        TEQ     R1,#&27
        TEQNE   R1,#&40
        TEQNE   R1,#&4B
        TEQNE   R1,#&4C
        TEQNE   R1,#&4F
        TEQNE   R1,#&74
        TEQNE   R1,#&95
        TEQNE   R1,#&96
        STMDB   R13!,{R14}
        MOVNE   R14,#&01C0
        ADDNE   R14,R14,#&00080000
        TEQNE   R1,R14
        ADDNE   R14,R14,#1
        TEQNE   R1,R14
        ADDNE   R14,R14,#1
        TEQNE   R1,R14
        ADDNE   R14,R14,#1
        TEQNE   R1,R14
        ADDNE   R14,R14,#2
        TEQNE   R1,R14
        LDMNEIA R13!,{PC}^
        <rest of veneer>
    
    (CMHG now sorts the list, so the order in the input file is no
    longer significant).

19) A new keyword "library-enter-code:" has been introduced. This
    allows you to supply your own assembler veneer routine to be
    called instead of _clib_entermodule when the module is started
    as an application. It is analogous to
    "library-initialisation-code:".

20) CMHG now attempts filename translation in the same way as the
    C compiler. So ^.cmhg.fred, ^.fred.cmhg, ^.fred/cmhg,
    ../fred.cmhg etc. will all be accepted as equivalent file
    specifiers.

21) The !CMHG frontend has been modified to allow setting all the
    new options.

22) Bug fix: the initialisation and irq-handler veneers did not
    correctly set fp to 0 before calling the C routines. This would
    break stack backtraces.

23) Now possible to return the special error 0 (Bad configure
    option) from a *Configure handler, as the veneer will map the
    return value -1 to 0.
    
24) CMHG now generates a version 3.11 AOF file, rather than a
    verion 1.50 file with type 1 relocations. The main effect of
    this is that DecAOF can now successfully disassemble a
    CMHG-generated object file.

25) New command line option -depend. It is passed on to the C
    preprocessor so it can generate dependency information for AMU.

Changes from 5.10 to 5.11
=========================

1) Some more veneers refined.

2) Change 13) above reversed. Documentation is wrong: R4-R6 can be
   corrupted.

3) Bug fix: service call veneer accessed banked R14 after TEQP.

4) Bug fix: generic-veneers corrupted stack if error returned.

5) Bug fix: generated header would #define Module_VersionNumber
   to values like 019, which C interprets as octal.

6) If outputting header to a filename with no extension, CMHG
   will now #define __cmhg_<source root>_h. This makes header files
   generating using !CMHG make more sense (otherwise it would
   #define __cmhg_x35e19ab2).

7) Bug fix: typo in definition of error_BAD_SWI.

8) Bug fix: the swi veneer BadSWI error code was incorrectly assembled
   in small headers.

9) Initialisation veneer streamlined, and hard-coded use of -536
   etc (instead of _Lib$Reloc$Offset) removed.

Changes from 5.11 to 5.12
=========================

1) Allow -b flag with a warning, rather than generating an error.

Changes from 5.12 to 5.13
=========================

Bug fix: Generated C header contained incorrect declarations for
event handlers.

Changes from 5.13 to 5.14
=========================

Versions 5.12 and 5.13 generated broken generic veneer and
vector handler code.

Changes from 5.14 to 5.15
=========================

The "-b" flag generated the wrong symbol (the leading underscore
was missing).
The generic veneer (and vector handler) code included some BLs
instead of Bs. This was harmless but odd. Now fixed.

Changes from 5.15 to 5.16
=========================

Lots of tidy-ups in the generated header file, including
tightened up constness in function declarations.

Changes from 5.16 to 5.30
=========================

1) CMHG will generate fast service call dispatch tables for Ursula kernels to
   make use of (see Ursula kernel spec for details).

2) Module titles may be quoted - either in single or double quotes. 

3) Cross-compilation capability added.

4) -U option to undefine symbols to match -D. 

5) Numbers in service call lists etc. may be bracketed.  This means that CMHG
   files can #include "Global/Services.h" to get service call macros, SWI
   chunk base; "Global/RISCOS.h" to get event and vector numbers etc to
   make it more readable.  

6) Pre-processor command-line buffer increased to 1K to avoid overflows
   (was only 128 bytes)

7) New -26bit and -32bit options to control the APCS variant CMHG will
   assume that user code is using.

8) _clib_finalisemodule is called during module initialisation if an
   error is returned by the user's init routine.  This avoid any
   potential memory leaks, and ensures that the atexit functions are
   called before the module dies.

Changes from 5.30 to 5.37
=========================

Minor tweaks to the veneers, including a bug fix to avoid hitting a bug
in StrongARM in the 32-bit veneers.  Changed default APCS variant to 32-bit.

Changes from 5.37 to 5.42
=========================

1) Bugfix to APCS-32 generic-veneers and irq-handlers' despatch code: the lr
   on entry had no PSR bits in it, even when running in 26-bit mode. However,
   APCS-32 code running on a 26-bit system is permitted to return using
   MOVS PC,R14 - a notable case where this may happen is where the
   generic-veneer code has a tail-call optimised branch into the C library,
   which on a 26-bit system will always enforce lr's flags on exit, resulting
   in an unintended mode switch.

2) Added comment to the auto-generated header file to warn that the command
   handler arg_string may not be null-terminated (eg when called from BASIC's
   OSCLI statement).

3) Added ability to replace the C library module finalisation routine:
   keyword 'library-finalisation-code:' works much like 'library-enter-code:'
   and 'library-initialisation-code:'.

Changes from 5.42 to 5.43
=========================
1) generic_veneers can now handle being called in SYS mode (or ABT, UND, MON
   or HYP modes) and will switch to SVC32 mode. Note that this is not
   intended as a replacement wrapper for top-level RTSupport routines;
   instead it is to permit direct calls between different modules when the
   caller is in SYS mode: the primary concern is typically to switch the
   static base context when moving from one module to another, and to
   restore it on return. Since RISC OS direct-call APIs generally do not
   mandate the stack limit register is valid on entry, it has to be inferred
   from the stack pointer (but the usual method cannot be relied upon in SYS
   mode, hence the need to switch to SVC mode in addition).

2) Corrected the comments about argc associated with the command handler:
   it has always been the case that argc is valid for help entries, but not
   valid for configure/status entries.

3) The "help:" flag in the command description in the CMHG file was
   previously of little use, because both the entry offsets for command
   execution and command help execution caused the C command handler to be
   called with the same value in cmd_no, so they couldn't be distinguished.
   Now separate values of cmd_no are used for the two cases; the help code
   case is distinguished with a CMDHELP_ prefix rather than a CMD_ prefix.

4) Previously, for dependency generation, the target filename was generated
   by taking the source file name and substituting the prefix with "o." (or
   the suffix with ".o" on cross-compilation builds).  Now the target
   filename is taken from the -d and/or -o arguments, both filename and
   prefix/suffix parts. If both -d and -o are present, both sets of
   dependencies are generated.

Changes from 5.43 to 5.45
=========================

1) Multiple -I switches may now be specified on the command line.

2) A special return value of -1 may now be returned by the initialisation-code
   handler to denote that the module has no static data. The private word
   will be set to zero and the Shared C Library shut down, yet the module
   remains registered with the kernel. Any subsequent attempts to
   call Shared C Library functions have undefined behaviour.
