compiler/include/utility/hooks.h

   1 #ifndef UTILITY_HOOKS_H
   2 #define UTILITY_HOOKS_H
   3
   4 /*
   5     Copyright © 1995-2010, The AROS Development Team. All rights reserved.
   6     $Id$
   7 */
   8
   9 #ifndef EXEC_TYPES_H
  10 #   include <exec/types.h>
  11 #endif
  12 #ifndef EXEC_NODES_H
  13 #   include <exec/nodes.h>
  14 #endif
  15 #ifndef AROS_ASMCALL_H
  16 #   include <aros/asmcall.h>
  17 #endif
  18
  19 /* A callback Hook */
  20 struct Hook
  21 {
  22     struct MinNode  h_MinNode;
  23     APTR            h_Entry;        /* Main entry point */
  24     APTR            h_SubEntry;     /* Secondary entry point */
  25     APTR            h_Data;         /* Whatever you want */
  26 };
  27
  28 /* You can use this if you want for casting function pointers. */
  29 typedef IPTR (*HOOKFUNC)();
  30
  31 /*
  32     Calling conventions for Amiga Hooks.
  33
  34     The callback hook is invoked with the following parameters, which
  35     on an Amiga/m68k are passed in the following registers:
  36
  37     A0  -   pointer to the Hook data structure
  38     A2  -   pointer to Hook specific data ("object")
  39     A1  -   pointer to Hook parameters ("message")
  40
  41     When the Hook is invoked, control is passed to the h_Entry function.
  42     This function MUST be defined in the following manner for correct
  43     operation on all systems.
  44
  45     AROS_UFH3(  return type ,  function name ,
  46         AROS_UFHA(struct Hook *,    hook, A0),
  47         AROS_UFHA(APTR,             object, A2),
  48         AROS_UFHA(APTR,             message, A1)
  49     )
  50
  51     Note the order of the arguments, hook, object, message.
  52
  53     ----------------------------------------------------------------------
  54      Note for people using Amiga compilers without registerized arguments
  55     ----------------------------------------------------------------------
  56
  57     If your compiler cannot accept these parameters in these registers
  58     (where applicable), you will have to define a small assembly stub
  59     to push the arguments on the stack, and then call the h_SubEntry
  60     function.
  61
  62     However this is unlikely to be required unless you are trying to
  63     compile your program on an Amiga with a very old compiler.
  64
  65     A sample stub (in new Motorola m68k syntax):
  66
  67     _HookEntry:
  68         move.l  a1,-(sp)
  69         move.l  a2,-(sp)
  70         move.l  a0,-(sp)
  71         move.l  (h_SubEntry,a0),a0
  72         jsr     (a0)
  73         lea     (12,sp),sp
  74         rts
  75
  76     There is a suitable function defined in amiga.lib called HookEntry
  77     that can be used for this purpose. See the documentation of HookEntry
  78     for more information.
  79
  80 */
  81
  82 #define CALLHOOKPKT(hook, object, message)     \
  83     AROS_UFC3                                  \
  84     (                                          \
  85         IPTR, ((struct Hook *) hook)->h_Entry, \
  86         AROS_UFCA(struct Hook *, hook,    A0), \
  87         AROS_UFCA(APTR,          object,  A2), \
  88         AROS_UFCA(APTR,          message, A1)  \
  89     )
  90
  91 #endif /* UTILITY_HOOKS_H */