home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 4 / DATAFILE_PDCD4.iso / utilities / utilsp / rink010 / Docs / Segment < prev   
Encoding:
Text File  |  1995-06-25  |  3.0 KB  |  101 lines
  1.  
  2. How to write a rink segment
  3. rink documentation, (c) Ben Summers 1995
  4.  
  5.  
  6. Writing a code segment
  7. ~~~~~~~~~~~~~~~~~~~~~~
  8. Write your code as you would a standard C file, and compile it with the same
  9. compiler options as the rest of your program. You can write the segment in as
  10. many seperate files as you like. You can also include AOF files written in
  11. ARM code, such as produced by objasm, or AOF files from any other APCS
  12. compilant language compiler.
  13.  
  14. The only thing different is that the AOF files produced by the compilers are
  15. linked together using rink rather than link, and you need to provide certain
  16. other files.
  17.  
  18.  
  19.  
  20. Running rink
  21. ~~~~~~~~~~~~
  22. rink is the rink linker. It has the command line syntax
  23.  
  24.    rink -o <segment> -l <links> -h <header description> -m <map file>
  25.        -a <list of AOF files to link...> [-v|-vv]
  26.  
  27. The flags and switches can be in any order.
  28.  
  29. <segment> is the file name of the output segment. <links> is the file name
  30. of the output links file. <header description> is the name of the file which
  31. describes the segment header. It's format is described below. <map file> is
  32. the pointer block map file - see the file Docs.Parent for details of how to
  33. create it.
  34.  
  35. -a is followed by the list of all the AOF files you want to link together to
  36. create the segment. You can include as many as you like, but there must be
  37. at least one.
  38.  
  39. The switch -v causes rink to output more information on what it's doing, and
  40. -vv causes it to also output a textual table listing all the run time links
  41. in the links file.
  42.  
  43. During the process of creating the segment rink creates the temporary file
  44. 'o.rinkXscrap' (containing the output of the inital link -aof stage). This
  45. file is deleted after the file has been succesfully rinked.
  46.  
  47.  
  48. The header description file
  49. ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  50. This file contains all the information rink needs to make the segment header.
  51. It contains five entries, in any order. All except 'named_entries' must be
  52. present.
  53.  
  54. id:<id name>
  55.  
  56. The id of the segment. This is the first part of the block used to check the
  57. loaded segments. You should use a 8 character string to uniquely identify
  58. your application. It must be exactly 8 characters, or rink will fault it.
  59.  
  60. main_version:<number>
  61.  
  62. The version of the parent application.
  63.  
  64. code_version:<number>
  65.  
  66. The version of the segment.
  67.  
  68.  
  69. The parent program supplies the run time system with a similar list of
  70. values. A segment will only be loaded if the id matches exactly, and the main
  71. version number of the segment is less than or equal to that of the parent
  72. program. The code version is ignored.
  73.  
  74.  
  75. The functions to include in the header are given with entries:
  76.  
  77. entries:
  78. <fn_name0>
  79. <fn_name1>
  80. ...
  81. <fn_nameN>
  82. //
  83.  
  84. '//' terminates the list
  85.  
  86. If you call the functions the same thing in each segment, you only need
  87. create one header description file for all the segments in your project.
  88.  
  89.  
  90. Named functions are given with named_entries:
  91.  
  92. named_entries:
  93. <fn_name0>
  94. <fn_name1>
  95. ...
  96. <fn_nameN>
  97. //
  98.  
  99. This entry is optional. If it is not included, a named function header will
  100. not be included in the segment.
  101.