libgc/doc/README.amiga

   1 ===========================================================================
   2             Kjetil S. Matheussen's notes (28-11-2000)
   3 ===========================================================================
   4 Compiles under SAS/C again. Should allso still compile under other
   5 amiga compilers without big changes. I haven't checked if it still
   6 works under gcc, because I don't have gcc for amiga. But I have
   7 updated 'Makefile', and hope it compiles fine.
   8
   9
  10 WHATS NEW:
  11
  12 1.
  13    Made a pretty big effort in preventing GCs allocating-functions from returning
  14    chip-mem.
  15
  16    The lower part of the new file AmigaOS.c does this in various ways, mainly by
  17    wrapping GC_malloc, GC_malloc_atomic, GC_malloc_uncollectable,
  18    GC_malloc_atomic_uncollectable, GC_malloc_stubborn, GC_malloc_ignore_off_page
  19    and GC_malloc_atomic_ignore_off_page. GC_realloc is allso wrapped, but
  20    doesn't do the same effort in preventing to return chip-mem.
  21    Other allocating-functions (f.ex. GC_*_typed_) can probably be
  22    used without any problems, but beware that the warn hook will not be called.
  23    In case of problems, don't define GC_AMIGA_FASTALLOC.
  24
  25    Programs using more time actually using the memory allocated
  26    (instead of just allocate and free rapidly) have
  27    the most to earn on this, but even gctest now normally runs twice
  28    as fast and uses less memory, on my poor 8MB machine.
  29
  30    The changes have only effect when there is no more
  31    fast-mem left. But with the way GC works, it
  32    could happen quite often. Beware that an atexit handler had to be added,
  33    so using the abort() function will make a big memory-loss.
  34    If you absolutely must call abort() instead of exit(), try calling
  35    the GC_amiga_free_all_mem function before abort().
  36
  37    New amiga-spesific compilation flags:
  38
  39    GC_AMIGA_FASTALLOC - By NOT defining this option, GC will work like before,
  40                         it will not try to force fast-mem out of the OS, and
  41                         it will use normal calloc for allocation, and the rest
  42                         of the following flags will have no effect.
  43
  44    GC_AMIGA_ONLYFAST - Makes GC never to return chip-mem. GC_AMIGA_RETRY have
  45                        no effect if this flag is set.
  46
  47    GC_AMIGA_GC - If gc returns NULL, do a GC_gcollect, and try again. This
  48                  usually is a success with the standard GC configuration.
  49                  It is allso the most important flag to set to prevent
  50                  GC from returning chip-mem. Beware that it slows down a lot
  51                  when a program is rapidly allocating/deallocating when
  52                  theres either very little fast-memory left or verly little
  53                  chip-memory left. Its not a very common situation, but gctest
  54                  sometimes (very rare) use many minutes because of this.
  55
  56    GC_AMIGA_RETRY - If gc succeed allocating memory, but it is chip-mem,
  57                     try again and see if it is fast-mem. Most of the time,
  58                     it will actually return fast-mem for the second try.
  59                     I have set max number of retries to 9 or size/5000. You
  60                     can change this if you like. (see GC_amiga_rec_alloc())
  61
  62    GC_AMIGA_PRINTSTATS - Gather some statistics during the execution of a
  63                          program, and prints out the info when the atexit-handler
  64                          is called.
  65
  66    My reccomendation is to set all this flags, except GC_AMIGA_PRINTSTATS and
  67    GC_AMIGA_ONLYFAST.
  68
  69    If your program demands high response-time, you should
  70    not define GC_AMIGA_GC, and possible allso define GC_AMIGA_ONLYFAST.
  71    GC_AMIGA_RETRY does not seem to slow down much.
  72
  73    Allso, when compiling up programs, and GC_AMIGA_FASTALLOC was not defined when
  74    compilling gc, you can define GC_AMIGA_MAKINGLIB to avoid having these allocation-
  75    functions wrapped. (see gc.h)
  76
  77    Note that GC_realloc must not be called before any of
  78    the other above mentioned allocating-functions have been called. (shouldn't be
  79    any programs doing so either, I hope).
  80
  81    Another note. The allocation-function is wrapped when defining
  82    GC_AMIGA_FASTALLOC by letting the function go thru the new
  83    GC_amiga_allocwrapper_do function-pointer (see gc.h). Means that
  84    sending function-pointers, such as GC_malloc, GC_malloc_atomic, etc.,
  85    for later to be called like f.ex this, (*GC_malloc_functionpointer)(size),
  86    will not wrap the function. This is normally not a big problem, unless
  87    all allocation function is called like this, which will cause the
  88    atexit un-allocating function never to be called. Then you either
  89    have to manually add the atexit handler, or call the allocation-
  90    functions function-pointer functions like this;
  91    (*GC_amiga_allocwrapper_do)(size,GC_malloc_functionpointer).
  92    There are probably better ways this problem could be handled, unfortunately,
  93    I didn't find any without rewriting or replacing a lot of the GC-code, which
  94    I really didn't want to. (Making new GC_malloc_* functions, and just
  95    define f.ex GC_malloc as GC_amiga_malloc should allso work).
  96
  97
  98    New amiga-spesific function:
  99
 100      void GC_amiga_set_toany(void (*func)(void));
 101
 102    'func' is a function that will be called right before gc has to change
 103    allocation-method from MEMF_FAST to MEMF_ANY. Ie. when it is likely
 104    it will return chip-mem.
 105
 106
 107 2. A few small compiler-spesific additions to make it compile with SAS/C again.
 108
 109 3. Updated and rewritten the smakefile, so that it works again and that
 110    the "unnecesarry" 'SCOPTIONS' files could be removed. Allso included
 111    the cord-smakefile stuff in the main smakefile, so that the cord smakefile
 112    could be removed too. By writing smake -f Smakefile.smk, both gc.lib and
 113    cord.lib will be made.
 114
 115
 116
 117 STILL MISSING:
 118
 119 Programs can not be started from workbench, at least not for SAS/C. (Martin
 120 Tauchmanns note about that it now works with workbench is definitely wrong
 121 when concerning SAS/C). I guess it works if you use the old "#if 0'ed"-code,
 122 but I haven't tested it. I think the reason for MT to replace the
 123 "#if 0'ed"-code was only because it was a bit to SAS/C-spesific. But I
 124 don't know. An iconx-script solves this problem anyway.
 125
 126
 127 BEWARE!
 128
 129 -To run gctest, set the stack to around 200000 bytes first.
 130 -SAS/C-spesific: cord will crash if you compile gc.lib with
 131  either parm=reg or parm=both. (missing legal prototypes for
 132  function-pointers someplace is the reason I guess.).
 133
 134
 135 tested with software: Radium, http://www.stud.ifi.uio.no/~ksvalast/radium/
 136
 137 tested with hardware: MC68060
 138
 139
 140 -ksvalast@ifi.uio.no
 141
 142
 143 ===========================================================================
 144                            Martin Tauchmann's notes             (1-Apr-99)
 145 ===========================================================================
 146
 147 Works now, also with the GNU-C compiler V2.7.2.1. <ftp://ftp.unina.it/pub/amiga/geekgadgets/amiga/m68k/snapshots/971125/amiga-bin/>
 148 Modify the `Makefile`
 149 CC=cc $(ABI_FLAG)
 150 to
 151 CC=gcc $(ABI_FLAG)
 152
 153 TECHNICAL NOTES
 154
 155 - `GC_get_stack_base()`, `GC_register_data_segments()` works now with every
 156    C compiler; also Workbench.
 157
 158 - Removed AMIGA_SKIP_SEG, but the Code-Segment must not be scanned by GC.
 159
 160
 161 PROBLEMS
 162 - When the Linker, does`t merge all Code-Segments to an single one. LD of GCC
 163   do it always.
 164
 165 - With ixemul.library V47.3, when an GC program launched from another program
 166   (example: `Make` or `if_mach M68K AMIGA gctest`), `GC_register_data_segments()`
 167   found the Segment-List of the caller program.
 168   Can be fixed, if the run-time initialization code (for C programs, usually *crt0*)
 169   support `__data` and `__bss`.
 170
 171 - PowerPC Amiga currently not supported.
 172
 173 - Dynamic libraries (dyn_load.c) not supported.
 174
 175
 176 TESTED WITH SOFTWARE
 177
 178 `Optimized Oberon 2 C` (oo2c) <http://cognac.informatik.uni-kl.de/download/index.html>
 179
 180
 181 TESTED WITH HARDWARE
 182
 183 MC68030
 184
 185
 186 CONTACT
 187
 188 Please, contact me at <martintauchmann@bigfoot.com>, when you change the
 189 Amiga port. <http://martintauchmann.home.pages.de>
 190
 191 ===========================================================================
 192                            Michel Schinz's notes
 193 ===========================================================================
 194 WHO DID WHAT
 195
 196 The original Amiga port was made by Jesper Peterson. I (Michel Schinz)
 197 modified it slightly to reflect the changes made in the new official
 198 distributions, and to take advantage of the new SAS/C 6.x features. I also
 199 created a makefile to compile the "cord" package (see the cord
 200 subdirectory).
 201
 202 TECHNICAL NOTES
 203
 204 In addition to Jesper's notes, I have the following to say:
 205
 206 - Starting with version 4.3, gctest checks to see if the code segment is
 207   added to the root set or not, and complains if it is. Previous versions
 208   of this Amiga port added the code segment to the root set, so I tried to
 209   fix that. The only problem is that, as far as I know, it is impossible to
 210   know which segments are code segments and which are data segments (there
 211   are indeed solutions to this problem, like scanning the program on disk
 212   or patch the LoadSeg functions, but they are rather complicated). The
 213   solution I have chosen (see os_dep.c) is to test whether the program
 214   counter is in the segment we are about to add to the root set, and if it
 215   is, to skip the segment. The problems are that this solution is rather
 216   awkward and that it works only for one code segment. This means that if
 217   your program has more than one code segment, all of them but one will be
 218   added to the root set. This isn't a big problem in fact, since the
 219   collector will continue to work correctly, but it may be slower.
 220
 221   Anyway, the code which decides whether to skip a segment or not can be
 222   removed simply by not defining AMIGA_SKIP_SEG. But notice that if you do
 223   so, gctest will complain (it will say that "GC_is_visible produced wrong
 224   failure indication"). However, it may be useful if you happen to have
 225   pointers stored in a code segment (you really shouldn't).
 226
 227   If anyone has a good solution to the problem of finding, when a program
 228   is loaded in memory, whether a segment is a code or a data segment,
 229   please let me know.
 230
 231 PROBLEMS
 232
 233 If you have any problem with this version, please contact me at
 234 schinz@alphanet.ch (but do *not* send long files, since we pay for
 235 every mail!).
 236
 237 ===========================================================================
 238                           Jesper Peterson's notes
 239 ===========================================================================
 240
 241 ADDITIONAL NOTES FOR AMIGA PORT
 242
 243 These notes assume some familiarity with Amiga internals.
 244
 245 WHY I PORTED TO THE AMIGA
 246
 247 The sole reason why I made this port was as a first step in getting
 248 the Sather(*) language on the Amiga. A port of this language will
 249 be done as soon as the Sather 1.0 sources are made available to me.
 250 Given this motivation, the garbage collection (GC) port is rather
 251 minimal.
 252
 253 (*) For information on Sather read the comp.lang.sather newsgroup.
 254
 255 LIMITATIONS
 256
 257 This port assumes that the startup code linked with target programs
 258 is that supplied with SAS/C versions 6.0 or later. This allows
 259 assumptions to be made about where to find the stack base pointer
 260 and data segments when programs are run from WorkBench, as opposed
 261 to running from the CLI. The compiler dependent code is all in the
 262 GC_get_stack_base() and GC_register_data_segments() functions, but
 263 may spread as I add Amiga specific features.
 264
 265 Given that SAS/C was assumed, the port is set up to be built with
 266 "smake" using the "SMakefile". Compiler options in "SCoptions" can
 267 be set with "scopts" program. Both "smake" and "scopts" are part of
 268 the SAS/C commercial development system.
 269
 270 In keeping with the porting philosophy outlined above, this port
 271 will not behave well with Amiga specific code. Especially not inter-
 272 process comms via messages, and setting up public structures like
 273 Intuition objects or anything else in the system lists. For the
 274 time being the use of this library is limited to single threaded
 275 ANSI/POSIX  compliant or near-complient code. (ie. Stick to stdio
 276 for now). Given this limitation there is currently no mechanism for
 277 allocating "CHIP" or "PUBLIC" memory under the garbage collector.
 278 I'll add this after giving it considerable thought. The major
 279 problem is the entire physical address space may have to me scanned,
 280 since there is no telling who we may have passed memory to.
 281
 282 If you allocate your own stack in client code, you will have to
 283 assign the pointer plus stack size to GC_stackbottom.
 284
 285 The initial stack size of the target program can be compiled in by
 286 setting the __stack symbol (see SAS documentaion). It can be over-
 287 ridden from the CLI by running the AmigaDOS "stack" program, or from
 288 the WorkBench by setting the stack size in the tool types window.
 289
 290 SAS/C COMPILER OPTIONS (SCoptions)
 291
 292 You may wish to check the "CPU" code option is appropriate for your
 293 intended target system.
 294
 295 Under no circumstances set the "StackExtend" code option in either
 296 compiling the library or *ANY* client code.
 297
 298 All benign compiler warnings have been suppressed. These mainly
 299 involve lack of prototypes in the code, and dead assignments
 300 detected by the optimizer.
 301
 302 THE GOOD NEWS
 303
 304 The library as it stands is compatible with the GigaMem commercial
 305 virtual memory software, and probably similar PD software.
 306
 307 The performance of "gctest" on an Amiga 2630 (68030 @ 25Mhz)
 308 compares favourably with an HP9000 with similar architecture (a 325
 309 with a 68030 I think).
 310
 311 -----------------------------------------------------------------------
 312
 313 The Amiga port has been brought to you by:
 314
 315 Jesper Peterson.
 316
 317 jep@mtiame.mtia.oz.au           (preferred, but 1 week turnaround)
 318 jep@orca1.vic.design.telecom.au (that's orca<one>, 1 day turnaround)
 319
 320 At least one of these addresses should be around for a while, even
 321 though I don't work for either of the companies involved.
 322