/vendor/gc/doc/README.amiga

http://github.com/feyeleanor/RubyGoLightly · Unknown · 322 lines · 232 code · 90 blank · 0 comment · 0 complexity · 2a3a65aca359b73ff6fa768f921ff10f MD5 · raw file

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