git.gag.com Git - fw/sdcc/blob - doc/TININative.txt

   1 Using SDCC to develop Native Java functions
   2 -------------------------------------------
   3
   4 Prerequisites
   5 --------------
   6
   7 1) Download the latest compiler sources from http://sdcc.sourceforge.net (Subversion download), build &
   8    install the compiler.
   9 2) Download & install tini development kit. SDCC uses 'a390' assembler to generate Native libraries,
  10    it is NOT distributed with the compiler. Tested with Version 1.02d.
  11
  12
  13 Small Example
  14 -------------
  15
  16 Hello.java :-
  17
  18 import com.dalsemi.comm.*;
  19 import com.dalsemi.system.*;
  20
  21 public class Hello
  22 {
  23         public static native int method1(int i,int j);
  24         static void main(String args[])
  25         {
  26                 System.out.println("Hello Started");
  27                 try {
  28                     System.loadLibrary("myn.tlib");
  29                     System.out.println("Load Success");
  30                     System.out.println("Native method1 returned " + method1(200,100));
  31                 }
  32                 catch (Throwable t) {
  33                       System.out.println(t);
  34                 }
  35         }
  36 }
  37
  38 myn.c :-
  39
  40 long Native_method1() _JavaNative
  41 {
  42     long l = NatLib_LoadInt(0);
  43     long k = NatLib_LoadInt(1);
  44     return l-k;
  45 }
  46
  47 Before you start compiling make sure
  48 a) 'macro' & 'a390' are in the PATH
  49 b) The files tini.inc, ds80c390.inc, tinimacro.inc & apiequ.inc are in the SAME directory as
  50    the C file.
  51
  52 > javac -bootclasspath <path to>/tiniclasses.jar Hello.java
  53 > java -cp <path to>/tini.jar TINIConvertor -f Hello.class -o Hello.tini -d <path to>/tini.db
  54 > sdcc -mTININative myn.c
  55
  56 Load Hello.tini & myn.tlib into the TINI board then
  57
  58 TINI /> java Hello.tini
  59 Hello Started
  60 Load Success
  61 Native method1 returned 100
  62
  63 TINI />
  64
  65 Details you MUST know
  66 ---------------------
  67 SDCC has a completely different and incompatible parameter passing and register usage
  68 than the TINI java environment. The Native API has been implemented using the __builtin,
  69 or intrinsic function support in SDCC . Each of the Native API functions are mapped to an
  70 SDCC intrinsic function, the code generator for the intrinsic function takes care of mapping
  71 the registers and parameters to the TINI Java environment's expectations .
  72
  73 The _JavaNative keyword is used to map the return value from a Native function to R4:R0, by
  74 default SDCC uses DPTR:b:a to return a value.
  75
  76         Type Mapping
  77         ------------
  78
  79         SDCC can support types that are upto 4 bytes (32 bits).
  80
  81         Java                            SDCC
  82         ----                            ----
  83         char                            char
  84         short                           short/int
  85         int                             long
  86         long                            NOT SUPPORTED
  87         double                          NOT SUPPORTED
  88
  89         _bpx & _ap
  90         ---------
  91         SDCC requires a 16 bit frame pointer to access local variables (on the stack), and
  92         function parameters . In the TININative environment _bpx is mapped to R7_B3:R6_B3
  93         (register R7:R6 in bank3). The compiler also uses AP as a temp register, for the
  94         TINI environment this is mapped to R5_B3.
  95
  96 Limitations
  97 -----------
  98
  99 The TININative environment does not have a linker. Multiplication & Division of 16 & 32 bit
 100 numbers are implemented in SDCC as library functions this implies that , division & multiplication
 101 of these numbers are not supported in the TININative environment. The compiler transforms div/mul by
 102 power of 2 to shifts . For other mul/divs there are two ways around .
 103
 104 a) Copy the library function from the library to your code . The sources can be found in
 105    sdcc/device/lib.
 106 b) Use the --use-accelerator option, with this option the compiler will generate code to use
 107    the on-chip arithmetic accelerator for 16 bit multiplication & division & modulus.
 108    NOTE The compiler will disable interrupts during this operation to prevent corruption of
 109         MA & MB registers. MUL/DIV/MOD of unsigned quantities are more efficient than signed
 110         quantities.
 111
 112 API Mappings
 113 ------------
 114 As mentioned earlier the Native APIs are implemented using compiler intrinsic functions, at this
 115 time only the following functions have been mapped (more will be mapped in the future). Some
 116 Native API calls return multiple values, I haven't found a good way to handle this yet, in most
 117 cases these return a HANDLE and a pointer to ABSOLUTE memory in DPTR, in such cases SDCC will
 118 return ONLY the HANDLE and ignore the POINTER value. The HANDLE can then be used with MM_Deref to
 119 obtain the POINTER value again (I hope my assumption is correct here).
 120
 121 SDCC Prototype                                     Native API
 122 --------------                                     ----------
 123 char NatLib_LoadByte (char parmnum);               NatLib_LoadPrimitive
 124 int  NatLib_LoadShort(char parmnum);               NatLib_LoadPrimitive
 125 long NatLib_LoadInt  (char parmnum);               NatLib_LoadPrimitive
 126 char *NatLib_LoadPointer (char parmnum);           NatLib_LoadPointer
 127
 128 /* in the following cases the compiler will fill in the pointer to LibraryID when required*/
 129 /* NatLib_Get* return mutiple values return value is HANDLE , pointer is ignored */
 130
 131 char NatLib_InstallImmutableStateBlock(void *state_block,int handle);
 132                                                    NatLib_InstallImmutableStateBlock
 133 char NatLib_InstallEphemeralStateBlock(void *state_block,int handle);
 134                                                    NatLib_InstallEphemeralStateBlock
 135 void NatLib_RemoveImmutableStateBlock ();          NatLib_RemoveImmutableStateBlock
 136 void NatLib_RemoveEphemeralStateBlock ();          NatLib_RemoveEphemeralStateBlock
 137 int  NatLib_GetImmutableStateBlock();              NatLib_GetImmutableStateBlock
 138 int  NatLib_GetEphemeralStateBlock();              NatLib_GetEphemeralStateBlock
 139
 140 int MM_XMalloc (long size);                        MM_XMalloc   /* returns HANDLE */
 141 int MM_Malloc (int size);                          MM_Malloc    /* return HANDLE  */
 142 int MM_ApplicationMalloc ( int size );             MM_ApplicationMalloc /* returns HANDLE */
 143 int MM_Free (int handle);                          MM_Free
 144 char *MM_Deref (int handle);                       MM_Deref
 145 char MM_UnrestrictedPersist(int handle);           MM_UnrestrictedPersist
 146
 147 char System_ExecJavaProcess(char *image,int handle-to-processname)
 148                                                    System_ExecJavaProcess
 149 void System_GetRTCRegisters(char *regsavearea)     System_GetRTCRegisters
 150 void System_SetRTCRegisters(char *regsavearea)     System_SetRTCRegisters
 151 void System_ThreadSleep(long timeout)              System_ThreadSleep
 152 void System_ThreadSleep_ExitCriticalSection(long timeout)              System_ThreadSleep_ExitCriticalSection
 153 void System_ThreadResume(char threadid,char processid)                 System_ThreadResume
 154 void System_SaveJavaThreadState()                  System_SaveJavaThreadState
 155 void System_RestoreJavaThreadState()               System_RestoreJavaThreadState
 156 void System_ProcessSleep(long timeout)             System_ProcessSleep
 157 void System_ProcessSleep_ExitCriticalSection(long timeout)             System_ProcessSleep_ExitCriticalSection
 158 void System_ProcessYield()                         System_ProcessYield
 159 void System_ProcessSuspend()                       System_ProcessSuspend
 160 void System_ProcessResume(char processid)          System_ProcessResume
 161 char System_RegisterPoll((void *)(funcpointer)())  System_RegisterPoll
 162 char System_RemovePoll((void *)(funcpointer)())    System_RemovePoll
 163 char System_GetCurrentThreadId()                   System_GetCurrentThreadId
 164 char System_GetCurrentProcessId()                  System_GetCurrentProcessId
 165
 166
 167 Some Notes
 168 ----------
 169
 170 The register convention mapping causes a lot of push & pops to be generated.
 171 The source for the built in functions can be found in file src/ds390/gen.c.