m68k/peal.h

   1 /**********
   2  * Copyright (c) 2004-2005 Greg Parker.  All rights reserved.
   3  *
   4  * Redistribution and use in source and binary forms, with or without
   5  * modification, are permitted provided that the following conditions
   6  * are met:
   7  * 1. Redistributions of source code must retain the above copyright
   8  *    notice, this list of conditions and the following disclaimer.
   9  * 2. Redistributions in binary form must reproduce the above copyright
  10  *    notice, this list of conditions and the following disclaimer in the
  11  *    documentation and/or other materials provided with the distribution.
  12  *
  13  * THIS SOFTWARE IS PROVIDED BY GREG PARKER ``AS IS'' AND ANY EXPRESS OR
  14  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  15  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  16  * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  17  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  18  * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  19  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  20  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  21  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  22  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  23  **********/
  24
  25 #ifndef PEAL_H
  26 #define PEAL_H
  27
  28 #include <stdint.h>
  29
  30 /*
  31   PealModule *PealLoad(void *mem)
  32     Loads ARM code and data from mem.
  33     If mem points into a relocatable block, that block must be locked before
  34       calling PealLoad() and must remain locked until after PealUnload().
  35     Note that PealLoad() may modify *mem. If mem points into a resource
  36       or feature memory block, then mem must point to the beginning of
  37       the block and the memory must be writeable with DmWrite().
  38     Returns NULL if the load fails for any reason.
  39     Warning: if you do not call PealUnload() before your program exits,
  40       your program may crash with a handle lock overflow error when run
  41       more than 16 times.
  42
  43   PealModule *PealLoadFromResources(DmTypeID type, DmResID baseID)
  44     Loads ARM code and data from resources of the given type, starting
  45       with the given resource ID.
  46     The resources should be numbered sequentially starting with baseID,
  47       one for the ELF header and section list plus one for each ELF section.
  48       This is the output format generated by `peal-postlink -s ...`.
  49     DmGetResource() is used to load the resources. Some sections with
  50       no contents may have no resource, but still occupy a slot in the
  51       resource ID sequence. Some of the resources are kept open and
  52       locked until PealUnload() is called.
  53     Note that some of the resources may be modified using DmWrite().
  54     Returns NULL if the load fails for any reason.
  55     Warning: if you do not call PealUnload() before your program exits,
  56       your program may crash with a handle lock overflow error when run
  57       more than 16 times.
  58
  59   void PealUnload(PealModule *m)
  60     Unloads ARM code and data previously loaded by PealLoad().
  61     The module must not be used after this call.
  62     Warning: if you do not call PealUnload() before your program exits,
  63       your program may crash with a handle lock overflow error when run
  64       more than 16 times.
  65
  66   void *PealLookupSymbol(PealModule *m, char *query)
  67     Returns the address of a named ARM function or variable in module m.
  68     Returns NULL if the module contains no such function or variable.
  69     A function can be called by passing this address to PealCall().
  70     A variable can be read or written by dereferencing this address.
  71
  72   uint32_t PealCall(PealModule *m, void *addr, void *arg)
  73     Calls the function at addr in ARM module m, passing it the given arg.
  74     Returns the value returned by that function.
  75     The ARM function PealArmStub() is used to prepare ARM global state.
  76     The called function should take zero or one arguments.
  77
  78   void PealCxxConstruct(PealModule *m)
  79     Calls C++ constructors if they have not been called already.
  80     By default, Peal calls C++ constructors (if any) during the
  81     first PealCall(). You can force C++ constructors to run earlier
  82     by calling PealCxxConstruct() directly.
  83     The constructors are run only once, even if you call
  84     PealCxxConstruct() multiple times.
  85
  86   void PealCxxDestruct(PealModule *m)
  87     Calls C++ destructors if they have not been called already.
  88     By default, Peal calls C++ destructors (if any) during the
  89     PealUnload(). You can force C++ destructors to run earlier
  90     by calling PealCxxDestruct() directly.
  91     The destructors are run only once, even if you call
  92     PealCxxDestruct() multiple times.
  93  */
  94
  95
  96 typedef struct PealModule PealModule;
  97
  98 PealModule *PealLoad(void *elf);
  99 PealModule *PealLoadFromResources(DmResType type, DmResID baseID);
 100 void PealUnload(PealModule *m);
 101
 102 void *PealLookupSymbol(PealModule *m, char *query);
 103
 104 uint32_t PealCall(PealModule *m, void *addr, void *arg);
 105
 106 void PealCxxConstruct(PealModule *m);
 107 void PealCxxDestruct(PealModule *m);
 108
 109 #endif