How to Build Stubs for 68k Libraries - Revision history

Costel Mincea: Text replacement - "" to ""

2025-01-26T19:27:08Z

Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

← Older revision		Revision as of 19:27, 26 January 2025
Line 37:		Line 37:
	For example you have dopus_pragmas.h file and dopus.fd files (fd files are a standard way to describe the interface for libraries) and dopus_pragmas entries look like this:		For example you have dopus_pragmas.h file and dopus.fd files (fd files are a standard way to describe the interface for libraries) and dopus_pragmas entries look like this:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	#pragma libcall DOpusBase RemovedFunc0 1e 0		#pragma libcall DOpusBase RemovedFunc0 1e 0
	#pragma libcall DOpusBase Random 24 001		#pragma libcall DOpusBase Random 24 001
Line 48:		Line 48:
	If we look at the dopus_lib.fd file we see:		If we look at the dopus_lib.fd file we see:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	* "dopus.library"		* "dopus.library"
	##base _DOpusBase		##base _DOpusBase
Line 99:		Line 99:
	5. build a test program to use one function from dopus5.library, here StrConcat()		5. build a test program to use one function from dopus5.library, here StrConcat()

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	#include <proto/exec.h>		#include <proto/exec.h>
	#include <proto/dos.h>		#include <proto/dos.h>
Line 166:		Line 166:
	5. build a test program (its a bit different compared to the previous test program because the name of the interface is a bit different (big/small letters, 5 at end, etc) :		5. build a test program (its a bit different compared to the previous test program because the name of the interface is a bit different (big/small letters, 5 at end, etc) :

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	#include <proto/exec.h>		#include <proto/exec.h>
	#include <proto/dos.h>		#include <proto/dos.h>
Line 221:		Line 221:
	Now for something interesting. You may want to check if it all works from AmigaOS 4 and with your new lib.l.main and native AmigaOS includes, code, etc. You then choose any "simple" function from the library and make a simple AmigaOS 4 native test program for it. Let's say it will be the StrConcat() function from dopus5.library, which is described in the pragma file as:		Now for something interesting. You may want to check if it all works from AmigaOS 4 and with your new lib.l.main and native AmigaOS includes, code, etc. You then choose any "simple" function from the library and make a simple AmigaOS 4 native test program for it. Let's say it will be the StrConcat() function from dopus5.library, which is described in the pragma file as:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	#pragma libcall DOpusBase StrConcat 47a 09803		#pragma libcall DOpusBase StrConcat 47a 09803
	</syntaxhighlight>		</syntaxhighlight>
Line 227:		Line 227:
	and in dopus_lib.fd like:		and in dopus_lib.fd like:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	StrConcat(s1,s2,len)(a0/a1,d0)		StrConcat(s1,s2,len)(a0/a1,d0)
	</syntaxhighlight>		</syntaxhighlight>
Line 241:		Line 241:
	In other words you can build your .fd file from scratch, which will look like this:		In other words you can build your .fd file from scratch, which will look like this:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	* "dopus.library"		* "dopus.library"
	##base _DOpusBase		##base _DOpusBase
Line 262:		Line 262:
	Obviously, you can go the more elegant way and use .sfd instead, which have "reserved" keyword, so no need to put all those empty-functions like:		Obviously, you can go the more elegant way and use .sfd instead, which have "reserved" keyword, so no need to put all those empty-functions like:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	==id $Id: dopus5_lib.sfd,v 1.0 2013/03/29 09:24:08 noname Exp $		==id $Id: dopus5_lib.sfd,v 1.0 2013/03/29 09:24:08 noname Exp $
	* "dopus5.library"		* "dopus5.library"

Ray Sbaitso: /* Links */

2020-12-25T21:28:33Z

Links

← Older revision		Revision as of 21:28, 25 December 2020
Line 284:		Line 284:
	= Links =		= Links =

	[1] Libraries and devices: ~~http~~://wiki.amigaos.net/~~index.php~~/Libraries_and_Devices		[1] Libraries and devices: https://wiki.amigaos.net/wiki/Libraries_and_Devices

	[2] RamLib autodoc.		[2] RamLib autodoc.

Steven Solie: /* I want one single function to work */

2013-05-08T18:52:05Z

I want one single function to work

← Older revision		Revision as of 18:52, 8 May 2013
Line 219:		Line 219:
	= I want one single function to work =		= I want one single function to work =

	Now something interesting: ~~you~~ may want to check ~~only~~ if it all works from AmigaOS 4 and with your new lib.l.main and native AmigaOS includes, code ~~and co~~. You then choose any "simple" function from library and ~~want to~~ make a simple AmigaOS 4 native test program for it. Let's say it will be the StrConcat() function from dopus5.library, which is described in pragma file as:		Now for something interesting. You may want to check if it all works from AmigaOS 4 and with your new lib.l.main and native AmigaOS includes, code, etc. You then choose any "simple" function from the library and make a simple AmigaOS 4 native test program for it. Let's say it will be the StrConcat() function from dopus5.library, which is described in the pragma file as:

	<syntaxhighlight>		<syntaxhighlight>

Steven Solie: /* Method 2: fd2pragma + fd */

2013-05-08T18:49:47Z

Method 2: fd2pragma + fd

← Older revision		Revision as of 18:49, 8 May 2013
Line 168:		Line 168:
	<syntaxhighlight>		<syntaxhighlight>
	#include <proto/exec.h>		#include <proto/exec.h>
		⚫	#include <proto/dos.h>
	#include <proto/dopus5.h>		#include <proto/dopus5.h>
⚫	#include <~~stdio~~.h>
	#include <stdlib.h>
	#include <string.h>

	struct Library *DOpusBase;		struct Library *DOpusBase;
	struct Dopus5IFace *IDopus5;		struct Dopus5IFace *IDopus5;

	~~void~~ main(int argc, char **argv)		int main(int argc, char **argv)
	{		{
	~~char~~ buffer[256] = "First part-";		TEXT buffer[256] = "First part-";
	~~char~~ *concat = "Second part";		CONST_STRPTR concat = "Second part";

	// Need dopus library		// Need dopus library
	if (!(DOpusBase=IExec->OpenLibrary("PROGDIR:dopus5.library",1L))) {		if (!(DOpusBase = IExec->OpenLibrary("PROGDIR:dopus5.library", 1))) {
	~~printf~~("~~cant~~ library");		IDOS->Printf("Can't open library");
			}
	exit(10);
			else {
	};
	if (!(IDopus5=IExec->GetInterface(~~(struct Library *)~~DOpusBase,"main",1L,NULL))) {		if (!(IDopus5 = IExec->GetInterface(DOpusBase, "main", 1, NULL))) {
	~~printf~~("~~cant~~ interface");		IDOS->Printf("Can't get interface");
	~~exit(10);~~		}
	};		else {
		⚫	IDopus5->StrConcat(buffer, concat, 36);
		⚫	IDOS->Printf("Result=%s\n", buffer);

			IExec->DropInterface((struct Interface*)IDopus5);
			}

		⚫	IExec->CloseLibrary(DOpusBase);
⚫	IDopus5->StrConcat(buffer, concat, 36);
			}
⚫	~~printf~~("Result=%s\n", buffer);


			return 0;
⚫	IExec->CloseLibrary(DOpusBase);
	}		}
	</syntaxhighlight>		</syntaxhighlight>

Steven Solie: /* Method 1: fdtrans + sfd */

2013-05-08T18:46:39Z

Method 1: fdtrans + sfd

← Older revision		Revision as of 18:46, 8 May 2013
Line 101:		Line 101:
	<syntaxhighlight>		<syntaxhighlight>
	#include <proto/exec.h>		#include <proto/exec.h>
		⚫	#include <proto/dos.h>
	#include <proto/dopus5.h>		#include <proto/dopus5.h>
⚫	#include <~~stdio~~.h>
	#include <stdlib.h>
	#include <string.h>

	struct Library *DOpusBase;		struct Library *DOpusBase;
	struct DOpusIFace *IDOpus;		struct DOpusIFace *IDOpus;

	~~void~~ main(int argc, char **argv)		int main(int argc, char **argv)
	{		{
	~~char~~ buffer[256] = "First part-";		TEXT buffer[256] = "First part-";
	~~char~~ *concat = "Second part";		CONST_STRPTR concat = "Second part";

	// Need dopus library		// Need dopus library
	if (!(DOpusBase = IExec->OpenLibrary("PROGDIR:dopus5.library", 1))) {		if (!(DOpusBase = IExec->OpenLibrary("PROGDIR:dopus5.library", 1))) {
	~~printf~~("~~cant~~ library");		IDOS->Printf("Can't open library\n");
			}
	exit(10);
			else {
	};
	if (!(IDOpus=IExec->GetInterface(DOpusBase, "main", 1, NULL))) {		if (!(IDOpus = (struct DOpusIFace*)IExec->GetInterface(DOpusBase, "main", 1, NULL))) {
	~~printf~~("~~cant~~ interface");		IDOS->Printf("Can't get interface\n");
	~~exit(10);~~		}
	};		else {
		⚫	IDOpus->StrConcat(buffer, concat, 36);
		⚫	IDOS->Printf("Result=%s\n", buffer);

			IExec->DropInterface((struct Interface*)IDOpus);
			}

		⚫	IExec->CloseLibrary(DOpusBase);
⚫	IDOpus->StrConcat(buffer, concat, 36);
			}
⚫	~~printf~~("Result=%s\n", buffer);


			return 0;
⚫	IExec->CloseLibrary(DOpusBase);
	}		}
	</syntaxhighlight>		</syntaxhighlight>

Steven Solie: /* Second method: fd2pragma + fd */

2013-05-08T18:40:58Z

Second method: fd2pragma + fd

← Older revision		Revision as of 18:40, 8 May 2013
Line 137:		Line 137:
	It works!		It works!

	== ~~Second~~ ~~method~~: fd2pragma + fd ==		== Method 2: fd2pragma + fd ==

	1. Create an XML file:		1. Create an XML file:

Steven Solie: /* First method: fdtrans + sfd */

2013-05-08T18:40:44Z

First method: fdtrans + sfd

← Older revision		Revision as of 18:40, 8 May 2013
Line 76:		Line 76:
	Let's say we have dopus_lib.fd and only protos in different includes in different places. We then create proto file from all those includes (in referring to the dopus_lib.fd), and then auto-tools time coming. As I say we have 2 ways:		Let's say we have dopus_lib.fd and only protos in different includes in different places. We then create proto file from all those includes (in referring to the dopus_lib.fd), and then auto-tools time coming. As I say we have 2 ways:

	== ~~First~~ ~~method~~: fdtrans + sfd ==		== Method 1: fdtrans + sfd ==

	1. generate a .sfd file:		1. generate a .sfd file:

Steven Solie: /* Now What? */

2013-05-08T17:53:41Z

Now What?

← Older revision		Revision as of 17:53, 8 May 2013
Line 72:		Line 72:
	= Now What? =		= Now What? =

	We have 2 methods to build lib.l.main and required includes. But for both of them you need .fd file as a minimum (if you have .sfd its even better), and a proto file which will describe all (or not all) your functions. While .fd/.sfd should be done by the original developer, you still can make them from scratch if you have a pragma file with lib calls (you make this file with the same order and the same offsets). If you don't have one proto file, but many in different includes, then you can make your own one, just copy one by one all the protos from all the include files, while all your FD entries will not have necessary proto descriptions in proto file (~~btw~~, if you don't have proto for some functions, then entries from the fd/sfd file will be reserved when you will auto generate AmigaOS code/includes, so respect offsets).		We have 2 methods to build lib.l.main and required includes. But for both of them you need .fd file as a minimum (if you have .sfd its even better), and a proto file which will describe all (or not all) your functions. While .fd/.sfd should be done by the original developer, you still can make them from scratch if you have a pragma file with lib calls (you make this file with the same order and the same offsets). If you don't have one proto file, but many in different includes, then you can make your own one, just copy one by one all the protos from all the include files, while all your FD entries will not have necessary proto descriptions in proto file (by the way, if you don't have proto for some functions, then entries from the fd/sfd file will be reserved when you will auto generate AmigaOS code/includes, so respect offsets).

	Let's say we have dopus_lib.fd and only protos in different includes in different places. We then create proto file from all those includes (in referring to the dopus_lib.fd), and then auto-tools time coming. As I say we have 2 ways:		Let's say we have dopus_lib.fd and only protos in different includes in different places. We then create proto file from all those includes (in referring to the dopus_lib.fd), and then auto-tools time coming. As I say we have 2 ways:
Line 88:		Line 88:
	ram:> fdtrans dopus5_lib.sfd -x -s		ram:> fdtrans dopus5_lib.sfd -x -s

	Change manually in the ~~crosscall~~-stubs file (dopus5.c) "main_vectors" in "main_v1_vectors", as it seems some typo between different tools. No other changes is needed, fdtrans automatically insert including of interface (while fd2pragma will skip it, see later).		Change manually in the cross call-stubs file (dopus5.c) "main_vectors" in "main_v1_vectors", as it seems some typo between different tools. No other changes is needed, fdtrans automatically insert including of interface (while fd2pragma will skip it, see later).

	3. generate proto/interface/inline (i.e. includes) and vectors:		3. generate proto/interface/inline (i.e. includes) and vectors:
Line 109:		Line 109:
	struct DOpusIFace *IDOpus;		struct DOpusIFace *IDOpus;

	void main(int argc,char **argv)		void main(int argc, char **argv)
	{		{
	char buffer[256] = "First part-";		char buffer[256] = "First part-";
Line 115:		Line 115:

	// Need dopus library		// Need dopus library
	if (!(DOpusBase=IExec->OpenLibrary("PROGDIR:dopus5.library",1L))) {		if (!(DOpusBase = IExec->OpenLibrary("PROGDIR:dopus5.library", 1))) {
	printf("cant library");		printf("cant library");
	exit(10);		exit(10);
	};		};
	if (!(IDOpus=IExec->GetInterface(~~(struct Library *)~~DOpusBase,"main",1L,NULL))) {		if (!(IDOpus=IExec->GetInterface(DOpusBase, "main", 1, NULL))) {
	printf("cant interface");		printf("cant interface");
	exit(10);		exit(10);
Line 173:		Line 173:
	struct Dopus5IFace *IDopus5;		struct Dopus5IFace *IDopus5;

	void main(int argc,char **argv)		void main(int argc, char **argv)
	{		{
	char buffer[256] = "First part-";		char buffer[256] = "First part-";

Steven Solie: /* pragmas/fd/sfd/protos */

2013-05-08T17:52:13Z

pragmas/fd/sfd/protos

← Older revision		Revision as of 17:52, 8 May 2013
Line 68:		Line 68:
	So respect offsets in the jump table.		So respect offsets in the jump table.

	Note that .sfd files work like .fd files but with more possibilities. You won't find them in old 68k dev archives of libraries as its something new. They contain a lot more ~~infomation~~ than .fd and are easier to use. But more or less they follow the same logic, the same respect for offsets, etc.		Note that .sfd files work like .fd files but with more possibilities. You won't find them in old 68k dev archives of libraries as its something new. They contain a lot more information than .fd and are easier to use. But more or less they follow the same logic, the same respect for offsets, etc. To see a full description of .fd and .sfd formats check the fd2pragma guide.
	To see a full description of .fd and .sfd formats check fd2pragma guide.

	= Now What? =		= Now What? =

Steven Solie: /* PowerPC->68k Glue Stubs */

2013-05-08T17:51:17Z

PowerPC->68k Glue Stubs

← Older revision		Revision as of 17:51, 8 May 2013
Line 13:		Line 13:
	= PowerPC->68k Glue Stubs =		= PowerPC->68k Glue Stubs =

	While 68k libraries are old and almost all libraries on AmigaOS today are PowerPC native ones, there are still some old AmigaOS 3.x libraries which are necessary and have no native PowerPC replacement. In that case we need to create for them necessary PowerPC->68k glue stub files, so we can call those 68k ~~libraries's~~ routines from native, PowerPC code, or, we can use EmulateTags(). The latter makes it easy for your code to use both PowerPC and 68k native libraries ~~transparent~~ with only a small bit of small overhead; just a few instructions. But this only works when the PowerPC native code is available and when there are just a few functions in the library. Quite often, you just don't want to deal with all this because of the large number of functions in a 68k library and the different ways of using them from the code. In this case, creating of PowerPC->68k stubs is a simpler and faster way.		While 68k libraries are old and almost all libraries on AmigaOS today are PowerPC native ones, there are still some old AmigaOS 3.x libraries which are necessary and have no native PowerPC replacement. In that case we need to create for them necessary PowerPC->68k glue stub files, so we can call those 68k library routines from native, PowerPC code, or, we can use EmulateTags(). The latter makes it easy for your code to use both PowerPC and 68k native libraries transparently with only a small bit of small overhead; just a few instructions. But this only works when the PowerPC native code is available and when there are just a few functions in the library. Quite often, you just don't want to deal with all this because of the large number of functions in a 68k library and the different ways of using them from the code. In this case, creating of PowerPC->68k stubs is a simpler and faster way.

	For a better explanation of what a PowerPC->68k stub is, refer to the [[Migration_Guide\|Migration Guide]]. In short, if you have, let's say, the 68k version of dopus5.library and want to use it from native AmigaOS 4 binaries then you need to create dopus5.l.main. When code in your native binary needs to interface to a old AmigaOS3 library, the system (ramlib to be more precise) will automatically scan its library search path for the file "dopus5.l.main" and if found, it will open it and obtain the interface from there. That l.main file is pure non-startup code which contains the necessary stubs. You do not need to write the stubs from scratch manually. This is a job for different set of tools (fd2pragma, fdtrans and IDLTool). The library.l.main code consists of 2 files if you auto generate them: PowerPC->68k ~~crosscall~~ stubs and vectors. Of course you can write them from scratch manually, but its a pain and there are already tools which do it for you.		For a better explanation of what a PowerPC->68k stub is, refer to the [[Migration_Guide\|Migration Guide]]. In short, if you have, let's say, the 68k version of dopus5.library and want to use it from native AmigaOS 4 binaries then you need to create dopus5.l.main. When code in your native binary needs to interface to a old AmigaOS3 library, the system (ramlib to be more precise) will automatically scan its library search path for the file "dopus5.l.main" and if found, it will open it and obtain the interface from there. That l.main file is pure non-startup code which contains the necessary stubs. You do not need to write the stubs from scratch manually. This is a job for different set of tools (fd2pragma, fdtrans and IDLTool). The library.l.main code consists of 2 files if you auto generate them: PowerPC->68k cross call stubs and vectors. Of course you can write them from scratch manually, but its a pain and there are already tools which do it for you.

	The name of the file in general does not matter. A library does not necessarily have to be named ".library" and could be named ".module" or whatever. Ramlib will search for the first "." in the library name, starting from the end, the first part up to and including the dot plus one more character, usually the 'l' in library, is used, another dot is appended, then the interface name is added. It then calls the exec function.		The name of the file in general does not matter. A library does not necessarily have to be named ".library" and could be named ".module" or whatever. Ramlib will search for the first "." in the library name, starting from the end, the first part up to and including the dot plus one more character, usually the 'l' in library, is used, another dot is appended, then the interface name is added. It then calls the exec function.
Line 24:		Line 24:
	foobar.blabla -> foobar.b.main		foobar.blabla -> foobar.b.main
	foobar.module -> foobar.m.main		foobar.module -> foobar.m.main


	{{Note\|text=Because of the way RamLib parses glue-stubs names, you can't call your glue stub for "foobar.library" as "foobar.library.main". It is understandable from the explanation above, but it can be misleading when you run for example "snoopy" and can see how it tries to search for "foobar.library.main", but it didn't tries to search for a file, just for "resident" code in memory. The real file ramlib will look for is only foobar.l.main when the main library is called as foobar.library.}}		{{Note\|text=Because of the way RamLib parses glue-stubs names, you can't call your glue stub for "foobar.library" as "foobar.library.main". It is understandable from the explanation above, but it can be misleading when you run for example "snoopy" and can see how it tries to search for "foobar.library.main", but it didn't tries to search for a file, just for "resident" code in memory. The real file ramlib will look for is only foobar.l.main when the main library is called as foobar.library.}}