Explanations to the project 'CallPPCLib.¶'
------------------------------------------

The program 'CallPPCLib' demonstrates how to call PPC shared library
functions. Two functions of the powerpc.library, which are accesible
for the PPC, are called here. The powerpc.library contains functions
for both CPU's.

The two functions 'AllocVecPPC' and 'FreeVecPPC' are called. Therefore,
the include file 'exec/memory.i' has to be included, so that we can
access the memory flags (MEMF_PUBLIC,MEMF_CLEAR).

Second, the include file 'powerpc_lib.i' is included, which contains
all library vector offsets of the powerpc.library. This file should
usually be located in a directory 'lvo:'.

If your include files are not located in the directory 'include:' and
if you LVO files are not located in the directory 'lvo:', you have
to adapt the include paths in the menu 'Project Environment'.

Certainly, the PPC must not directly jump into the location in the
vector table, which contains a 68K JMP command. Instead, it loads
the address, which is situated two bytes behind the opcode, into
a register and stores it into the link register afterwards. Then
it jumps to the address where the LR points to (using a 'blrl' command).

There exist some macros in the LVO files for calling shared library
functions, so that the programmer has not to type in this sequence
every time. In the file 'powerpc_lib.i' there is the macro CALLPOWERPC
which calls a function of the powerpc.library.

This macro though requires the symbol '_PowerPCBase', the library base
of the powerpc.library. Usually you would have to open the library and
to evaluate the base in this way. But if executables are created directly
using the PowerASM, some libraries are already opened at startup of
the program and the correspondig symbols are exported. Thus it's possible
to import symbols with XREF and to create an executable nevertheless
(for that purpose, the directive 'executable' has to be located in the
source).


---------------------------------------------------------------------
Rule 13:

If executables are created using the PowerASM, the following symbols can
be imported:

_SysBase:       Base address of exec.library.
_DosBase:       Base address of dos.library which is opened at startup.
_PowerPCBase:   Base address of powerpc.library which is opened at startup.
_LinkerDB:      Pointer to the base of all relative accesses (this value
                is always located in the register r2).
---------------------------------------------------------------------


For PPC shared library functions there is no explizit register assignment,
it is fixed defined, which parameters are passed in which registers. The
library base is always passed in r3 (which is done automatically by the
macros, for example CALLPOWERPC), the other parameters are passed in r4-r10.


---------------------------------------------------------------------
Rule 14:

When calling a PPC shared library function, the actual parameters have to
be passed in the registers r4-r10 (resp. f1-f13) in asceding order. The
library base has to be passed in r3, which is done automatically by the
call-macros and which has not be done by the programmer explicitely. The
return value is always located in r3 (resp. in f1).
---------------------------------------------------------------------


In our example the memory size is passed as first parameter in r4, the
memory flags in r5 and the alignment in r6. The macro CALLPOWERPC
copies the library base to r3, before it calls the function.

The directive 'version' in the source cares, that the program is aborted,
if the current powerpc.library has a version number less than 7. This
directive would be obsolete here, because there is no powerpc.library with
a version number less than 7. But if programs are created which use special
features of WarpOS, the 'version' directive should be used to define the
minimal version number.

© 1997 HAAGE&PARTNER Computer GmbH