home *** CD-ROM | disk | FTP | other *** search
/ RISCWORLD 7 / RISCWORLD_VOL7.iso / Software / Issue2 / SDL.ARC / !gcc / docs / rink < prev    next >
Encoding:
Text File  |  2001-01-02  |  3.9 KB  |  101 lines
  1. rink documentation
  2. (c) Ben Summers 1994
  3.  
  4. This file contains an overview of the rink system.
  5.  
  6.  
  7.  
  8. What is rink, and what it useful for?
  9. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  10.  
  11. It's easiest to explain rink using an example. If you have a program which
  12. imports and displays graphics (or needs to convert files of any format into
  13. an internal one) it's not too effecient to have all the necessary conversion
  14. code in the program complied in. As the typical user will only want to
  15. convert a small proportion of the availiable formats, it would be better if
  16. only the necessary code could be loaded in.
  17.  
  18. This is a good example of what rink is good for. The format loaders will all
  19. have the same program interface, probably a call to set up and then a call
  20. to convert a file, and output the same data. The calling program doesn't
  21. have to be aware of what kind of file is being converted because the
  22. outputted data is always in the same format.
  23.  
  24. It also has the advantage that it's very easy to write and distribute new
  25. loaders as the main program doesn't have to know anything about the new
  26. loader, only about it's interface. It also allows third partys to produce
  27. loaders without access to your sources.
  28.  
  29. Overlays perform a similar function to rink by only loading code which is
  30. necessary, but aren't as flexiable. Some programs will benifit from rink,
  31. some will benifit from overlays.
  32.  
  33. Relocatable modules are another example of the sort of thing rink is good at.
  34. The calling program, the OS, doesn't know exactly what they do, but does
  35. know how to call them as they all have a standard interface. Of course, RMs
  36. are mainly written in ARM code, and facilities exist to write them in C, but
  37. they do give the right sort of idea about the possible uses of rink.
  38.  
  39.  
  40. rink segements can also contain a number of named functions which can be
  41. enumerated and then called by the parent program. For example, this might be
  42. useful for language extensions or as a more flexiable overlay system.
  43.  
  44.  
  45. Definitions
  46. ~~~~~~~~~~~
  47.  
  48. Segment      A chunk of code which is loaded into the main program, and is
  49.              linked into the main program when it is loaded.
  50.  
  51. Links file   A compact file listing the necessary links which the rink run
  52.              time system needs to perform when it loads the segement.
  53.  
  54. Parent       The main program which calls the loaded segments.
  55.  
  56. Child function
  57.              A function within the segment which is called by the parent.
  58.  
  59. named function
  60.              A function withing the segment which has a name attached to it.
  61.  
  62. rink         The title of this system.
  63.  
  64. rink run time system
  65.              The code linked into the parent to load and unload segments
  66.              and to call child functions.
  67.  
  68. rink         The program which links AOF files to produce segments and
  69.              links files.
  70.  
  71. mkptrmap     The program which creates an AOF file to create the pointer
  72.              block and outputs a map of this for rink.
  73.  
  74.  
  75.  
  76. How does rink work?
  77. ~~~~~~~~~~~~~~~~~~
  78.  
  79. rink takes AOF files, and partically links them together with the aid of
  80. link, and then links areas within the code segment. Finally, it outputs the
  81. code and a compact links file which describes all the links rink was unable
  82. to perform as they refer to external symbols (functions and variables within
  83. the parent). The code file contains a header which tells the run time system
  84. where the child functions are within the code file and how many arguments
  85. these expect.
  86.  
  87. The rink run time system is linked into the parent. As well as a veneer to
  88. call the functions in the segement, it contains code to load and link
  89. segments and to unload them when the parent is finished with it.
  90.  
  91. References to symbols in the parent are refered to by an index into a block
  92. of pointers. A program is provided to automatically generate an AOF file to
  93. create this table from a list of symbols and C header files. It also
  94. generates a map of this table which the main rink program uses to locate
  95. symbols within the table.
  96.  
  97.  
  98.  
  99.  
  100.  
  101.