Amiga library in high-level language

[TCH]

Are there any example codes of an Amiga library written in a high-level language? (Preferably C, but actually any.) I've found only two examples on the net (#1, #2) and both of them are assembly examples.

Edit: Okay, never mind, google did not throw this out...

[TCH]

I am trying to understand what this stuff does, how it does it and why, but the internal documentations are insufficient...

For example, here is the base

struct

of the example library:

struct ExampleBase
{
 struct Library         exb_LibNode;
 SEGLISTPTR             exb_SegList;
 struct ExecBase       *exb_SysBase;
 struct IntuitionBase  *exb_IntuitionBase;
 struct GfxBase        *exb_GfxBase;
};

Is there any documentation about what should be inside in this structure? I guess the pointers to the bases of intuition and graphics libraries are not mandatory, but the example library uses them, so it needs to store them.

Then there are the opener and closer functions:

ULONG __saveds __stdargs L_OpenLibs(struct ExampleBase *ExampleBase);
void  __saveds __stdargs L_CloseLibs(void);

Are

__saveds

and

__stdargs

mandatory for them; i mean an Amiga library has to have a near data section and it has to use the stack for arguments? (The closer function does not even has any arguments.)

[phx]

Originally Posted by TCH

Is there any documentation about what should be inside in this structure?

The

struct Library

at the beginning is mandatory, as it describes your library. The rest of the structure is filled by data your library code needs.

__saveds

and

__stdargs

mandatory for them;

I haven't seen your example library source. It probably uses a small data base register? Then you absolutely need

__saveds

, because your library code is called by other tasks which have not set up the base register as needed. I see no need for

__stdargs

, though.

i mean an Amiga library has to have a near data section and it has to use the stack for arguments?

No, it doesn't have to use near data. Best is if your library has no data or bss sections at all. Preferably allocate your data in the library base structure.
Library functions always pass their arguments in registers.

[TCH]

Originally Posted by phx

The

struct Library

at the beginning is mandatory, as it describes your library. The rest of the structure is filled by data your library code needs.

Even the seglist is optional?

Originally Posted by phx

I haven't seen your example library source.

It's here.

Originally Posted by phx

It probably uses a small data base register? Then you absolutely need

__saveds

, because your library code is called by other tasks which have not set up the base register as needed. I see no need for

__stdargs

, though.

I see, thanks. How do i know if it does use small data base in C? Is there a macro for it? Or C just do that?

Originally Posted by phx

No, it doesn't have to use near data. Best is if your library has no data or bss sections at all. Preferably allocate your data in the library base structure.

Got, it, thank you.

Originally Posted by phx

Library functions always pass their arguments in registers.

In that case i see no reason for using

__stdargs

either, but then why does this library use it?

[alkis]

There is also this one:

https://github.com/bebbo/libnix/blob...es/simplelib.c

Compiles with:
m68k-amigaos-gcc -nostdlib -O3 -fomit-frame-pointer -fbaserel /opt/amiga/gcc6/m68k-amigaos/libnix/lib/libinit.o simplelib.c

(change the path to libinit.o according to your gcc prefix)

Haven't actually tested it. Disassembled executable looks fine at first glance.

[Steady]

Don't worry too much about the fields that follow struct Library. They are for use by whatever library you are creating to store variables that the library might need to access, regardless of the application that opens the library and calls a function.

In particular, don't worry about the seglist. Unless you need to use seglist for some reason (and you will know if you do) then you can get rid of it.

The SysBase, IntuitionBase and GfxBase fields are so that your library can open the libraries it needs to use and store the base there so it can be accessed at any time you need. This takes the burden of opening and closing those libraries away from the caller (application), mostly because without clairvoyance how can the caller of a function know for sure which resources your library code needs now or in the future. Just be aware that you need to make provisions for accessing those library base variables instead of globals that are usually used for applications. This differs between C compilers. In assembler, just load the base into A6 and call in the usual way.

You can add any variable your library needs here which is accessed as a positive offset of your library's base address (you get it in register A6 when called).

Just be careful to restrict the globals to those values you need for the library itself, rather than support for the functions you provide. Your library functions should allocate values on the stack or in registers as applicable.

Good luck!

[TCH]

@alkis: Thanks, but this one is libnix-dependent and

stabs.h

is full of assembly macros and i would like to make a pure C-based Amiga library.

@Steady: Thanks, that shed some light on a few things. But what the seglist is for? When i'll need it?

[bebbo]

If you are using amiga-gcc you might also check https://github.com/bebbo/example.library

[Thomas Richter]

Originally Posted by TCH

@Steady: Thanks, that shed some light on a few things. But what the seglist is for? When i'll need it?

You collect it in your LibInit() function, and return it as result code in LibExpunge() if your library can be removed from memory. It is the segment list that consists of your code, and it will be unloaded by dos if the library is supposed to be flushed from memory.

[Thomas Richter]

Originally Posted by Steady

In particular, don't worry about the seglist. Unless you need to use seglist for some reason (and you will know if you do) then you can get rid of it.

Heck, no! The seglist you need to cleanly remove your library from memory, see separate reply.

Originally Posted by Steady

The SysBase, IntuitionBase and GfxBase fields are so that your library can open the libraries it needs to use and store the base there so it can be accessed at any time you need.

Whether a library needs them is another question. SysBase you most likely do need, and it is better to get it through the library base than through AbsExecBase.

Originally Posted by Steady

This takes the burden of opening and closing those libraries away from the caller (application), mostly because without clairvoyance how can the caller of a function know for sure which resources your library code needs now or in the future.

Well, it is up to *your* library to open them if *your* library code needs them. Whether the caller code needs them is another question, but if so, the caller needs to open them, too. It is bad practise to "steal" library base pointers from another library.

Originally Posted by Steady

Just be aware that you need to make provisions for accessing those library base variables instead of globals that are usually used for applications. This differs between C compilers. In assembler, just load the base into A6 and call in the usual way.

This is compiler dependent. If you compile with SAS/C and LibCode, the compiler will be smart enough to store all your "globals" (actually, objects with external linkage) in the library base, and will access them through the library base. Other compilers may be less smart, and you may need to fiddle them then through the library base yourself.


Some care should be taken in designing LibOpen, LibClose and LibExpunge. LibInit() is usually called through RamLib, and thus can do a lot of things, then through ramlib, including activities that break a Forbid(). LibOpen(), LibClose() and LibExpunge() are called in the context of the task using the library, and under Forbid() state.



While there are ways around it, it is advisable (at those for those unexperienced with the pitalls of AmigaOs) to avoid any calls in these functions that may potentially break a Forbid() state. Such as opening other libraries, obtaining semaphores or performing I/O. Any such things should better happen in LibInit() where it is well-isolated from the rest of the system through ramlib.


Note that this changed in Kick 2.0, in Kick 1.3 it is even trickier.

[TCH]

Originally Posted by bebbo

If you are using amiga-gcc you might also check https://github.com/bebbo/example.library

Thank you, this looks promising and simple enough for easy understanding. Although i have to ask, what is the "magic" part responsible for? I see, that it is a function array, but what purpose it does serve and why is that magical? That's the jump table for AmigaOS?
Yes, i do use amiga-gcc for development, but i also would like to support SAS/C and VBCC.

Originally Posted by Thomas Richter

You collect it in your LibInit() function, and return it as result code in LibExpunge() if your library can be removed from memory. It is the segment list that consists of your code, and it will be unloaded by dos if the library is supposed to be flushed from memory.

I am trying to understand this...so the seglist is essentially a pointer which points to the library's code segment and when the last program/library/handler/device/whatever closes the library, then DOS will call a "free" on it?

Originally Posted by Thomas Richter

Whether a library needs them is another question. SysBase you most likely do need, and it is better to get it through the library base than through AbsExecBase.

So, the

SysBase

is not mandatory, but highly recommended?

[alkis]

Originally Posted by bebbo

If you are using amiga-gcc you might also check https://github.com/bebbo/example.library

Since this is missing a makefile....what's the build invocation?

[bebbo]

Originally Posted by alkis

Since this is missing a makefile....what's the build invocation?

Oh - it's an Eclipse project :-)

this should do it

m68k-amigaos-gcc -nostartfiles -o "example.library" alibrary.c myfx.c -Os

specify alibrary.c as the first file

[Steady]

Never mind. I had misremembered about the seglist and it is supplied by LibInit() as written by Thomas above. Apologies.

[Thomas Richter]

Originally Posted by TCH

Although i have to ask, what is the "magic" part responsible for? I see, that it is a function array, but what purpose it does serve and why is that magical?

The resident structure is required for the system to initialize the library, and the function array it points (indirectly) to is used to setup the trampoline functions to your library entries.

Originally Posted by TCH

That's the jump table for AmigaOS?

That, plus version information.

Originally Posted by TCH

so the seglist is essentially a pointer which points to the library's code segment and when the last program/library/handler/device/whatever closes the library, then DOS will call a "free" on it?

Yes, except that it is a BPTR (not a C pointer) and the function to release the segments is called UnloadSeg(), not free.

Originally Posted by TCH

So, the

SysBase

is not mandatory, but highly recommended?

Nothing in the system forces you to keep a copy of SysBase in the library. If you make a copy elsewhere, that is also good. Just saying, accessing exec.library through a base pointer (either in your library, or elsewhere) is better than fetching its entry point through AbsExecBase every call. The latter is slow because accesses to AbsExecBase have to be emulated for some configurations, most notably if debugging tools like MuForce are running.

[TCH]

Originally Posted by Thomas Richter

The resident structure is required for the system to initialize the library, and the function array it points (indirectly) to is used to setup the trampoline functions to your library entries.

How does the Amiga recognize that there is a jump table + version information? By some markers? There is a

void foo() {}

line in the code, i guess that compiles to a single

rts

; is that necessary for something, like marking something? There is also this part

// dunno
long LibExtFunc(void) {
	return 0;
}

What is this responsible for?

Originally Posted by Thomas Richter

Yes, except that it is a BPTR (not a C pointer) and the function to release the segments is called UnloadSeg(), not free.

I meant "free" in as generic memory-freeing, not explicitly

free()

, but thanks for clarifying.

Originally Posted by Thomas Richter

Nothing in the system forces you to keep a copy of SysBase in the library. If you make a copy elsewhere, that is also good. Just saying, accessing exec.library through a base pointer (either in your library, or elsewhere) is better than fetching its entry point through AbsExecBase every call. The latter is slow because accesses to AbsExecBase have to be emulated for some configurations, most notably if debugging tools like MuForce are running.

Got it, thanks.

[Thomas Richter]

Originally Posted by TCH

How does the Amiga recognize that there is a jump table + version information?

It scans the code for the resident tag. That is, the structure that starts with the magic word 0x4afc, and is followed by a pointer to itself. This structure is a "struct Resident" and documented in exec/resident.h.


The infromation therein is used by the InitResident() function call to create the library, which includes building the jump table.


LibExtFunc() is currently not at all in use, but please return 0 for forward compaibility. There are at least some plans to use it in future versions for some kind of "Gestalt" function that returns properties of the library (or device), in a much better way than NSD could.

[TCH]

Thanks, now almost everything seems to be clear, but what is that

void foo() {}

?
Does that needed there at all?

[Thomas Richter]

I don't see what this should be good for.

[bebbo]

Originally Posted by TCH

Thanks, now almost everything seems to be clear, but what is that

void foo() {}

?
Does that needed there at all?

a leftover from - I don't remember... :-)


I put it once together from here and there (e.g. libnix library example) and tried to make it as simple as possible to be used with amiga-gcc.


Now I also added a semaphore to really init the library only once and created __myinit/__myexit functions in a separate file.


I added a variant to provide a separate base per opener too... untested ;-)