comodore_amiga_inc.-Amiga ROM Kernel Manual Volume 2 - eBook-ENG.pdf - amiga literatura ENG - TJAHZI

ROM Kernel Manual

Volume 2

Appendix A

Routine Summaries

This appendix contains Unix-like summaries for the routines that are built into the Amiga

ROM (or kickstart) software, as well as summaries of routines in disk-loadable libraries. The

debug library documentation is included here as well.

These documentation files are organized on a functional basis. For example, things pertinent

to Exec are listed under uexec.library/someDocFile". Things pertinent to graphics are listed

under "graphics.library/someDocFile".

The tutorial sections of this manual give you information that shows how these routines

relate to each other and the prerequisites for calling them.

Most routines are listed as part of a library of routines. Before you can use a routine within

your program, you must assure that the library is opened. This is explained fully in the

"Libraries" chapter of this manual but it bears repeating here. You open a library by using

the OpenLibrary() function. The call takes the form:

struct LibBase *LibBase;

LibBase = OpenLibrary("library.name",version);

where:

library.name

is a string that describes the name of the library you wish to open.

version

is the version number of the library that you wish to have opened. A value of 0 says

give me any version. A value of 31, for example (latest as of this writing) says open

specifically version 31 of this library or greater if 31 is not available.

If the library is disk-resident, it gets loaded and initialized. The OpenLibraryQ returns the

address of the library base, which you must assign to a specific variable. It is through this

means that your program links into the library-specific interface code that is contained in

amiga.lib.

The following is a list of the names of the libraries that are currently part of the Amiga

software and the corresponding names of the library base pointers associated with them:

Library Name Library Base Pointer Name

exec.library ExecBase

clist.library ClistBase

graphics.library GfxBase

layers.library LayersBase

intuition.library IntuitionBase

mathffp.library MathBase

mathtrans.library MathTransBase

mathieeedoubbas.library MathleeeDoubBasBase

dos.library

DosBase

translator.library

TranslatorBase

icon,library

IconBase

diskfont.library

DiskfontBase

ramlib.library

—

(not useful to C language)

Example:

#include "graphics/gfx.h"

struct GfxBase *GfxBase;

GfxBase = OpenLibrary("graphics.library",0);

if(GfxBase == NULL) exit(NO_GRAPHICS_LIBRARY_FOUND);

Note: If your program is coming up through the normal startup code (see the Work

bench chapter of this manual) the exec.library and dos.library are already opened

for you. Thus you needn't open them yourself.

The reason for this code are

1. C, when calling a routine, takes the parameters for the routine and pushes them

onto the stack. For example:

x = Routine(parmA, parmB);

Then it calls a routine named ".Routine" (adds an underscore to the head of the

routine name).

2. The underlying ROM (or disk based) code usually expects its parameters to be

passed in registers rather than on the stack. This is to make it truely general pur

pose (does not impose a particular stack frame), and more efficient for assembly

language coding.

Therefore, the interface code at ..Routine, in turn, saves the contents of registers

the routine will use and pulls parameters off of the stack and jams them into

registers, finally passing control directly to the actual starting location of the routine

itself.

The linker needs the library base location since it is through a jump-with-offset from

a machine register that the ..Routine entry point is found. (The Amiga uses a relo

cating loader in AmigaDOS, so you can never be sure exactly where a library of rou

tines is located. However once the system has loaded a library, it knows how and

where to find it and gives you a way to use the library's routines.)

The following shows typical interface code linked to your program from amiga.lib:

xref _LibBase ;Library base name is defined in

;user's file, this code gets linked

;to user's program, get the value

;from there when library is opened,

xdef JRoutine

;make ^Routine name external,

;visible to linker.

JRoutine:

move.l A6,-(sp) ;save register(s)

move.l 8(sp),A0/Al ;copy parms A and B to regs.

move.l _LibBase,A6 ;load library base address

jsr _LVORoutine(A6) ;go to real routine

move.l (sp)+,A6 jrestore registers

rts

where JLVORoutine is a value representing the offset, within the library, at which the

"real" routine (the one that expects parameters in registers) is located.

When you are finished using a library, at the end of your program, you should close it, using

the CloseLibrary function as follows:

CloseLibrary(LibBase);

If the system is running out of memory and needs to free up space, it can check the library-

accessors field for various libraries and for those whose accessors value is zero, it can retrieve

the memory that the library had used.

comodore_amiga_inc.-Amiga ROM Kernel Manual Volume 2 - eBook-ENG.pdf

Plik z chomika:

Inne pliki z tego folderu:

Inne foldery tego chomika: