The Datafile PD-CD 4/DATAFILE_PDCD4.iso/utilities/utilsp/rink010/Docs/Parent

Text File | 1995-06-25 | 7.6 KB | 229 lines

How to use rink in the parent program
rink documentation, (c) Ben Summers 1995



The run time system
~~~~~~~~~~~~~~~~~~~

The rink run time system is supplied as an AOF file. This is currently bound
to the C run time system, but can easily be modified to work with any
lanuage using command line switches to rinkptr.

The parent must be linked with the run time system and the pointer block
created by rinkptr.

A C header file, called rink.h is provided for use with C. It defines
several functions used to control the run time system.


****************************************************************************

rink_load is used to load a segment.

   os_error *rink_load(char *segment_name, char *links_name,
      rink_seghandle *sh, rink_check *ck)

It returns a handle to the segment for use with future calls to the system
in *sh, and returns 0 to signify that no error occured.

The pointer to the error block is either an operting system error, or a rink
internal error. These can be translated by the parent application by using
rinkptr to create a sugar function to a translation function other than the
default.

ck is a pointer to a structure. This must match the header of the file to be
loaded as a check that the file is the right thing to be loading. The
segment will be rejected if the main version number of the segment is
greater than that given in this check block. The code version number is
ignored, and is merely for information only.

Version numbers can be read with rink_readversion().


****************************************************************************

rink_fn returns a pointer to a function. It should be cast to a suitable
function pointer. The demonstration program shows one possible method of use.

   typedef void *(*_rink_fn)(void);

   _rink_fn rink_fn(rink_seghandle ch, int entry);

It returns the address of the function, or zero if it does not exist in the
header. ch is the handle of the segement as returned by rink_seghandle.
entry is the entry number within the header, numbered from zero.


As well as using it to find pointers which are then cached, you can also use
it to call functions directly. For example, to call a function taking 6
integer arguments which returns an integer, use something like

  typedef int (*fn6)(int, int, int, int, int, int);

  result = ((fn6)rink_fn(code, 6))(1, 2, 3, 4, 5, 6);


****************************************************************************

rink_enum_named is used to find the names of all named functions, and a
pointer to that function.

   _rink_fn rink_enum_named(rink_seghandle cd, int *ref, char **name);

Set *ref to 0 before starting, and the call it repeatedly until *ref == -1.
After each call, *ref is set to refer to the next function, *name contains a
pointer to the name of the function, and a pointer to the function is
returned.

For example, to print the names of all named functions within a segment, and
call them assuming that they take no arguments, use something like


typedef void (*fn0)(void);

void list_and_call(void)
{
  int l;
  char *name;
  _rink_fn fn;

  l = 0;
  do {
    fn = rink_enum_named(code, &l, &name);
    printf("*** %s\n", name);
    ((fn0)fn)();
  } while(l >= 0);
}


****************************************************************************

rink_readversion returns a pointer to a structure containing the version
numbers of a segment.

   rink_version *rink_readversion(rink_seghandle sh);


****************************************************************************

rink_unload is used to remove a segement from the parents memory.

   void rink_unload(rink_seghandle ch);


****************************************************************************


Using rinkptr and extractsym to create a pointer block map
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To tell rink which functions and data you want the segments to be able to
call, you need to create a pointer block map. This is basically a list of
symbols to which rink can link items in segments.

The format of the file is simple. Each line contains a symbol name. Blank
lines are ignored, and lines beginning with '#' are comments.

To help in creating these maps, extractsym will extract a list of possible
symbols from an AOF file, or from an ALF (library) file. This list can be
used directly as a pointer block map.

It's command line syntax is

  extractsym o|e <output file> <input files>

The first argument tells it whether to overwrite or to extend the output
file. The latter is useful if all the AOF files you want to include are too
long for one command line.

The input files are simply a list of AOF files. You can include as many as
you want.

For library files you need to specify which AOF files within the library you
want to scan. This is done by specifing the internal name after a comma, for
example, 'C:o.RISC_OSLib,o.werr'. You can use a '*' wildcard, although it
must be the last character of the filename.

Use libfile to find a list of all AOF files inside the library, or <name>,*
to include all symbols.

As an example, the demo program uses

  extractsym o ptrblkmap o.rinkdemo C:o.stubs

to generate it's map from the shared C library stubs and it's own main
program. This allows access to all C library functions and functions within
the program to the segments.


In creating the pointer block map, you have two options. You can either use
extractsym to create the map directly, or you can create the map by hand.
The first method has the advantage that it is easy to do, but the second
means that you can create maps which are backwards compatible.

To ensure that segments which have been rinked with an old version of rink
are still compatible, only add symbols to the end. A good strategy is to
create a map by hand at the beginning of the project containing the symbols
for your library (stubs or perhaps UnixLib) and then add to this as rink
faults symbols not found in the map.

You can then either add them one by one, or use extractsym to get all the
symbols out of an object file to add all the symbols in an AOF file.


Creating the pointer block
~~~~~~~~~~~~~~~~~~~~~~~~~~
After creating the pointer block map, you need to create the pointer block
for linking into your program. rinkptr performs this function. It's command
line syntax is

  rinkptr <map filename> <output filename>

For example,

  rinkptr ptrblkmap o.pointerblk

You should remake the pointer block every time you change the pointer block
map and re-rink all segments, otherwise segments could be linked to the wrong
things, giving unpredicitable results.


The sugar functions
~~~~~~~~~~~~~~~~~~~
The rink run time system requires memory allocation and memory freeing
routines. These default to malloc and free respectively. However, these may
not be appropriate for your program. You can change them with the -A and -F
command line switches on rinkptr.

For example, to change them to my_alloc and my_free, use

  rinkptr ptrblkmap o.pointerblk -A my_alloc -F my_free


The rink run time system can generate it's own errors, not just returning OS
errors. You may want to change the default error messages, perhaps for
internationalisation or to change them to messages more appropirate for your
application. You can do this by replacing the internal error translation
function using the -T switch, for example

  rinkptr ptrblkmap o.pointerblk -T my_translation

Your function should have a prototype similar to

  os_error *my_translation(int err_number);

The default error translator returns a pointer to an error block with a
textual message in english, and the error number as err_number. Values for
err_number can be

Number  Default message
  -1    "No room"
  -2    "Not a rink segment"
  -3    "Not a rink links file"
  -4    "Segment is too recent"