Migration Guide - Revision history

Costel Mincea: Text replacement - "" to ""

2025-01-26T19:08:47Z

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

← Older revision		Revision as of 19:08, 26 January 2025
Line 11:		Line 11:
	To use a library under AmigaOS 4, you simply include its proto file, in addition to any other file that may be required. For example, to use Intuition Windows and Screens, you would add the following to your program:		To use a library under AmigaOS 4, you simply include its proto file, in addition to any other file that may be required. For example, to use Intuition Windows and Screens, you would add the following to your program:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	#include <intuition/intuition.h>		#include <intuition/intuition.h>
	#include <intuition/screens.h>		#include <intuition/screens.h>
Line 110:		Line 110:
	System libraries may be opened automatically using the libauto link library. libauto can automatically open a number of system libraries (see [[#libauto_Libraries\|libauto Libraries]] for a list of these libraries) and also set up their interface pointers. If you include the proto file in your program and link with libauto, the appropriate library will be all set up. For example, including <proto/intuition.h> will set up IntuitionBase and IIntuition automatically so that they are all set up when your program enters the main() function. The following example program opens a simple window, waits a bit then closes it again:		System libraries may be opened automatically using the libauto link library. libauto can automatically open a number of system libraries (see [[#libauto_Libraries\|libauto Libraries]] for a list of these libraries) and also set up their interface pointers. If you include the proto file in your program and link with libauto, the appropriate library will be all set up. For example, including <proto/intuition.h> will set up IntuitionBase and IIntuition automatically so that they are all set up when your program enters the main() function. The following example program opens a simple window, waits a bit then closes it again:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	#include <proto/exec.h>		#include <proto/exec.h>
	#include <proto/dos.h>		#include <proto/dos.h>
Line 141:		Line 141:
	Libraries can also be initialized by hand. As with the old system, the function to do this is exec.library's OpenLibrary function. However, as we have hinted above, the library base is not the only requirement for using a library - you need to retrieve the interface pointer (or rather, all interface pointers you need) from the library to make use of it. On the classic system, opening for example intuition.library looked like this:		Libraries can also be initialized by hand. As with the old system, the function to do this is exec.library's OpenLibrary function. However, as we have hinted above, the library base is not the only requirement for using a library - you need to retrieve the interface pointer (or rather, all interface pointers you need) from the library to make use of it. On the classic system, opening for example intuition.library looked like this:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	IntuitionBase = (struct IntuitionBase *)OpenLibrary("intuition.library", 36);		IntuitionBase = (struct IntuitionBase *)OpenLibrary("intuition.library", 36);
	if (IntuitionBase == NULL) PanicExit("Cannot open intuition library");		if (IntuitionBase == NULL) PanicExit("Cannot open intuition library");
Line 154:		Line 154:
	Under AmigaOS 4, this will look like this:		Under AmigaOS 4, this will look like this:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	IntuitionBase = IExec->OpenLibrary("intuition.library", 50);		IntuitionBase = IExec->OpenLibrary("intuition.library", 50);
	IIntuition = (struct IntuitionIFace *)IExec->GetInterface(		IIntuition = (struct IntuitionIFace *)IExec->GetInterface(
Line 181:		Line 181:
	The interface pointer is needed to actually call the functions of a library (remember that the "original" jump table only contains 68k pointers). Thus, to call an Intuition function, you write "IIntution->OpenWindowTags" instead of a simple "OpenWindowTags". Note that there are ways around this; as we said in the introduction, using the preprocessor symbol __USE_INLINE__ will automatically include a file that contains a macro definition of the following type:		The interface pointer is needed to actually call the functions of a library (remember that the "original" jump table only contains 68k pointers). Thus, to call an Intuition function, you write "IIntution->OpenWindowTags" instead of a simple "OpenWindowTags". Note that there are ways around this; as we said in the introduction, using the preprocessor symbol __USE_INLINE__ will automatically include a file that contains a macro definition of the following type:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	#define OpenWindowTags(...) \		#define OpenWindowTags(...) \
	IIntuition->OpenWindowTags(__VA_ARGS__)		IIntuition->OpenWindowTags(__VA_ARGS__)
Line 192:		Line 192:
	Opening a device also works largely the same as under OS 3.x. If a device doesn't export its own function table, like serial device, then there is no additional step required. If, on the other hand, the device does export its own function table, you need to retrieve the interface pointer just as you would retrieve the interface pointer from a library. For example, timer device is usually opened like this (error checking removed for clarity):		Opening a device also works largely the same as under OS 3.x. If a device doesn't export its own function table, like serial device, then there is no additional step required. If, on the other hand, the device does export its own function table, you need to retrieve the interface pointer just as you would retrieve the interface pointer from a library. For example, timer device is usually opened like this (error checking removed for clarity):

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct MsgPort *TimerMP = IExec->AllocSysObject(ASOT_PORT, NULL);		struct MsgPort *TimerMP = IExec->AllocSysObject(ASOT_PORT, NULL);

Line 231:		Line 231:
	Finally, the interfaces allow for other things. For example, expansion library uses interfaces in a sort of object-oriented way - every PCI device on the bus is represented by a separate interface. That means that instead of repeating the PCI bus, device and function ID's as parameters every time, you can write something like:		Finally, the interfaces allow for other things. For example, expansion library uses interfaces in a sort of object-oriented way - every PCI device on the bus is represented by a separate interface. That means that instead of repeating the PCI bus, device and function ID's as parameters every time, you can write something like:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	a = MyDevice->ReadConfigByte(PCI_INTERRUPT_LINE);		a = MyDevice->ReadConfigByte(PCI_INTERRUPT_LINE);
	MyDevice->WriteConfigByte(PCI_INTERRUPT_LINE, a & 0x0F);		MyDevice->WriteConfigByte(PCI_INTERRUPT_LINE, a & 0x0F);
Line 242:		Line 242:
	Interfaces have a usage count. That count is implicitly incremented when you call GetInterface and decremented again on DropInterface. You can explicitly do that using the Obtain() and Release() method that all interfaces implement. You must do this if you intend to use the interface you obtained somewhere outside the context of your task. For example, consider an image loader library that returns a picture in the form of an interface. Suppose that this interface contains a Print() method that you can use to send the image to a printer. Quite naturally, this will take its time, so the program launches a subtask that takes care of that. The subtask would look something like that (some error handling removed for clarity):		Interfaces have a usage count. That count is implicitly incremented when you call GetInterface and decremented again on DropInterface. You can explicitly do that using the Obtain() and Release() method that all interfaces implement. You must do this if you intend to use the interface you obtained somewhere outside the context of your task. For example, consider an image loader library that returns a picture in the form of an interface. Suppose that this interface contains a Print() method that you can use to send the image to a printer. Quite naturally, this will take its time, so the program launches a subtask that takes care of that. The subtask would look something like that (some error handling removed for clarity):

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	void print_task(struct PictureIFace *IPicture)		void print_task(struct PictureIFace *IPicture)
	{		{
Line 318:		Line 318:
	A hook function should always look like this:		A hook function should always look like this:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	uint32 HookFunction(struct Hook *hook, APTR object, APTR message);		uint32 HookFunction(struct Hook *hook, APTR object, APTR message);
	</syntaxhighlight>		</syntaxhighlight>
Line 330:		Line 330:
	Although frequently used, the following code is highly system- and compiler-dependent:		Although frequently used, the following code is highly system- and compiler-dependent:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	void somefunc(int messageid, ...)		void somefunc(int messageid, ...)
	{		{
Line 345:		Line 345:
	The only legal way to express the above code is:		The only legal way to express the above code is:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	#include <stdarg.h>		#include <stdarg.h>
	void somefunc(int messageid, ...)		void somefunc(int messageid, ...)
Line 366:		Line 366:
	Such a function still needs to access the parameters in a special way. The first argument (messageid in this example) still is passed in a register according to the ABI specs. The following fragment shows how to handle this case.		Such a function still needs to access the parameters in a special way. The first argument (messageid in this example) still is passed in a register according to the ABI specs. The following fragment shows how to handle this case.

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	#include <stdarg.h>		#include <stdarg.h>

Line 430:		Line 430:

	* Public data does not belong on the stack. If you want to send a message, allocate it with AllocSysObjectTags() using the ASOT_MESSAGE type. The following code is broken:		* Public data does not belong on the stack. If you want to send a message, allocate it with AllocSysObjectTags() using the ASOT_MESSAGE type. The following code is broken:
	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	void foo(void)		void foo(void)
	{		{

Frédéric Khannouf: /* Include Files */

2019-03-26T21:01:03Z

Include Files

← Older revision		Revision as of 21:01, 26 March 2019
Line 7:		Line 7:
	==== Include Files ====		==== Include Files ====

	Include files used to be a problematic issue under OS 3.x because there where a lot of different compilers, and most of them tended to use their own naming scheme and glue to bind to the operating system. The well-known SAS/C and StormC compiler systems used #pragma's for this purpose while gcc used inline functions or #define directives AmigaOS 4 at the moment supports two compiler systems (GNU GCC and the vbcc package) and both use the same scheme for include files.		Include files used to be a problematic issue under OS 3.x because there where a lot of different compilers, and most of them tended to use their own naming scheme and glue to bind to the operating system. The well-known SAS/C and StormC compiler systems used #pragma's for this purpose while gcc used inline functions or #define directives. AmigaOS 4 at the moment supports two compiler systems (GNU GCC and the vbcc package) and both use the same scheme for include files.

	To use a library under AmigaOS 4, you simply include its proto file, in addition to any other file that may be required. For example, to use Intuition Windows and Screens, you would add the following to your program:		To use a library under AmigaOS 4, you simply include its proto file, in addition to any other file that may be required. For example, to use Intuition Windows and Screens, you would add the following to your program:

Steven Solie: /* Known Incompatibilities */

2015-11-12T23:17:44Z

Known Incompatibilities

← Older revision		Revision as of 23:17, 12 November 2015
Line 429:		Line 429:
	* It has never been documented where and how (if at all) AllocVec stores the size of the block it has allocated. Therefore, it has always been illegal to try to access the four bytes before the actual allocation to find the size of the block. Code that will use this "feature" will no longer work, since AmigaOS 4's AllocVec does not necessarily put anything there.		* It has never been documented where and how (if at all) AllocVec stores the size of the block it has allocated. Therefore, it has always been illegal to try to access the four bytes before the actual allocation to find the size of the block. Code that will use this "feature" will no longer work, since AmigaOS 4's AllocVec does not necessarily put anything there.

	* Public data does not belong on the stack. If you want to send a message, allocate it with AllocSysObjectTags() using the ASOT_MESSAGE type. The following code is broken: ~~<syntaxhighlight>~~		* Public data does not belong on the stack. If you want to send a message, allocate it with AllocSysObjectTags() using the ASOT_MESSAGE type. The following code is broken:
			<syntaxhighlight>
	void foo(void)		void foo(void)
	{		{

Steven Solie: /* libauto Libraries */

2015-07-17T14:47:08Z

libauto Libraries

← Older revision		Revision as of 14:47, 17 July 2015
Line 501:		Line 501:
	\|-		\|-
	\| DOSBase		\| DOSBase
	\| IDOS		\| '''IDOS'''
	\|-		\|-
	\| DrawListBase		\| DrawListBase
Line 510:		Line 510:
	\|-		\|-
	\| ExecBase		\| ExecBase
	\| IExec, IDebug		\| '''IExec''', IDebug
	\|-		\|-
	\| ExpansionBase		\| ExpansionBase
Line 573:		Line 573:
	\|-		\|-
	\| LocaleBase		\| LocaleBase
	\| ILocale		\| '''ILocale'''
	\|-		\|-
	\| LowLevelBase		\| LowLevelBase
Line 645:		Line 645:
	\|-		\|-
	\| UtilityBase		\| UtilityBase
	\| IUtility		\| '''IUtility'''
	\|-		\|-
	\| VirtualBase		\| VirtualBase

Steven Solie: /* Known Incompatibilities */

2012-09-13T18:48:23Z

Known Incompatibilities

← Older revision		Revision as of 18:48, 13 September 2012
Line 429:		Line 429:
	* It has never been documented where and how (if at all) AllocVec stores the size of the block it has allocated. Therefore, it has always been illegal to try to access the four bytes before the actual allocation to find the size of the block. Code that will use this "feature" will no longer work, since AmigaOS 4's AllocVec does not necessarily put anything there.		* It has never been documented where and how (if at all) AllocVec stores the size of the block it has allocated. Therefore, it has always been illegal to try to access the four bytes before the actual allocation to find the size of the block. Code that will use this "feature" will no longer work, since AmigaOS 4's AllocVec does not necessarily put anything there.

	* Public data does not belong on the stack. If you want to send a message, allocate it with ~~MEMF_SHARED~~ (or ~~MEMF_PUBLIC~~ if ~~you~~ ~~intend to access it from an interrupt)~~. The following code is broken: <syntaxhighlight>		* Public data does not belong on the stack. If you want to send a message, allocate it with AllocSysObjectTags() using the ASOT_MESSAGE type. The following code is broken: <syntaxhighlight>
	void foo(void)		void foo(void)
	{		{

Steven Solie: /* Memory */

2012-09-13T18:46:18Z

Memory

← Older revision		Revision as of 18:46, 13 September 2012
Line 400:		Line 400:

	For more information about MEMF_PUBLIC see [[Obsolete_Exec_Memory_Allocation\|Obsolete Exec Memory Allocation]].		For more information about MEMF_PUBLIC see [[Obsolete_Exec_Memory_Allocation\|Obsolete Exec Memory Allocation]].

	For more information about how to properly allocate memory see [[Exec_Memory_Allocation\|Exec Memory Allocation]].

	==== Visible Changes in the Memory Subsystem ====		==== Visible Changes in the Memory Subsystem ====
Line 417:		Line 415:
	As we have already mentioned, there are some new memory flags for application programmers. MEMF_SHARED is one of them, the semantics of which have already been described above. Another one of these is MEMF_EXECUTABLE. Normally, executable code may not be placed into an arbitrary section of memory. If you intend to generate code dynamically, you must use MEMF_EXECUTABLE to allocate the memory. Also note that the code section of your program is write protected, so self-modifying is not possible unless you allocate a piece of MEMF_EXECUTABLE memory and generate your code there.		As we have already mentioned, there are some new memory flags for application programmers. MEMF_SHARED is one of them, the semantics of which have already been described above. Another one of these is MEMF_EXECUTABLE. Normally, executable code may not be placed into an arbitrary section of memory. If you intend to generate code dynamically, you must use MEMF_EXECUTABLE to allocate the memory. Also note that the code section of your program is write protected, so self-modifying is not possible unless you allocate a piece of MEMF_EXECUTABLE memory and generate your code there.

	Please refer to [[Exec_Memory_Allocation\|Exec Memory Allocation]] for more information ~~on memory flags~~.		Please refer to [[Exec_Memory_Allocation\|Exec Memory Allocation]] for more information.

	== Known Incompatibilities ==		== Known Incompatibilities ==

Steven Solie: /* The MEMF_PUBLIC flag */

2012-09-13T18:44:39Z

The MEMF_PUBLIC flag

← Older revision		Revision as of 18:44, 13 September 2012
Line 397:		Line 397:
	The memory subsystem of AmigaOS 4 has seen a radical overhaul. Although the API stays mostly the same, there are a few things to look out for when porting old code, as well as when writing new code.		The memory subsystem of AmigaOS 4 has seen a radical overhaul. Although the API stays mostly the same, there are a few things to look out for when porting old code, as well as when writing new code.

		⚫	A general rule of thumb is: Don't use it. There is usually no reason why you should be using MEMF_PUBLIC memory. On AmigaOS 3.9 and earlier you had to allocate e.g. Messages and Message Ports in public memory; this is no longer needed under AmigaOS 4 - instead use the MEMF_SHARED flag. The MEMF_SHARED flag shares a lot of the properties that its public counterpart has, but is much more "friendly" to the system.
	One of the most misused features of the past is the MEMF_PUBLIC flag. The MEMF_PUBLIC flag was severely under-documented in both the autodocs and the original Rom Kernel Reference Manuals. It was more or less described as "memory that will not go away, become remapped, or is made otherwise inaccessible".

			For more information about MEMF_PUBLIC see [[Obsolete_Exec_Memory_Allocation\|Obsolete Exec Memory Allocation]].
	MEMF_PUBLIC memory currently means that the memory area will not be unmapped/remapped/swapped out. MEMF_PUBLIC memory is mapped to MEMF_SHARED memory and is page locked so it cannot be swapped out.

			For more information about how to properly allocate memory see [[Exec_Memory_Allocation\|Exec Memory Allocation]].
⚫	A general rule of thumb is: Don't use it. There is usually no reason why you should be using ~~public~~ memory. On AmigaOS 3.9 and earlier you had to allocate e.g. Messages and Message Ports in public memory; this is no longer needed under AmigaOS 4 - instead use the MEMF_SHARED flag. The MEMF_SHARED flag shares a lot of the properties that its public counterpart has, but is much more "friendly" to the system. ~~Most notably, MEMF_SHARED memory:~~

	# is unlimited in size as far as address space and swap space is sufficient
	# can be read by all tasks in the system, but doesn't have too many strings attached
	# can be locked by a special API call to keep it from being swapped out.

	The only place where MEMF_PUBLIC should be used is when your memory needs to be accessible by an interrupt. In all other cases use MEMF_SHARED. If you are allocating private data, like storage for strings or other data, use MEMF_PRIVATE. This makes your memory inaccessible from other tasks, which is currently not enforced but will be so in the future.

	In general: Don't place unnecessary restrictions on your memory allocations. Always allow the system to pick the most appropriate memory. The more restrictions you place on your allocation, the more likely it is that your program has a negative impact on the system - be it by fragmenting the memory or by taking away resources that would have been better used elsewhere.

	==== Visible Changes in the Memory Subsystem ====		==== Visible Changes in the Memory Subsystem ====

Steven Solie: /* Manual Library Initialization */

2012-09-13T16:26:59Z

Manual Library Initialization

← Older revision		Revision as of 16:26, 13 September 2012
Line 139:		Line 139:
	==== Manual Library Initialization ====		==== Manual Library Initialization ====

	Libraries ca also be initialized by hand. As with the old system, the function to do this is exec.library's OpenLibrary function. However, as we have hinted above, the library base is not the only requirement for using a library - you need to retrieve the interface pointer (or rather, all interface pointers you need) from the library to make use of it. On the classic system, opening for example intuition.library looked like this:		Libraries can also be initialized by hand. As with the old system, the function to do this is exec.library's OpenLibrary function. However, as we have hinted above, the library base is not the only requirement for using a library - you need to retrieve the interface pointer (or rather, all interface pointers you need) from the library to make use of it. On the classic system, opening for example intuition.library looked like this:

	<syntaxhighlight>		<syntaxhighlight>

Steven Solie: /* Library Initialization using libauto */

2012-09-13T16:26:33Z

Library Initialization using libauto

← Older revision		Revision as of 16:26, 13 September 2012
Line 108:		Line 108:
	==== Library Initialization using libauto ====		==== Library Initialization using libauto ====

	~~The~~ ~~preferred~~ ~~method~~ ~~for~~ ~~initialization~~ ~~of system libraries~~ ~~is the usage of~~ the libauto link library. libauto can automatically open a number of system libraries (see ~~chapter~~ 8 for a list of these libraries) and also set up their interface pointers. If you include the proto file in your program and link with libauto, the appropriate library will be all set up. For example, including ~~<~~proto/intuition.h~~>~~ will set up IntuitionBase and IIntuition automatically so that they are all set up when your program enters the main() function. The following example program opens a simple window, waits a bit then closes it again:		System libraries may be opened automatically using the libauto link library. libauto can automatically open a number of system libraries (see [[#libauto_Libraries\|libauto Libraries]] for a list of these libraries) and also set up their interface pointers. If you include the proto file in your program and link with libauto, the appropriate library will be all set up. For example, including <proto/intuition.h> will set up IntuitionBase and IIntuition automatically so that they are all set up when your program enters the main() function. The following example program opens a simple window, waits a bit then closes it again:

	<syntaxhighlight>		<syntaxhighlight>
Line 118:		Line 118:
	{		{
	struct Window *win = IIntuition->OpenWindowTags(NULL,		struct Window *win = IIntuition->OpenWindowTags(NULL,
	WA_Title, "Example Window",		WA_Title, "Example Window",
	WA_Width, 640,		WA_Width, 640,
	WA_Height, 480,		WA_Height, 480,
	TAG_END);		TAG_END);

	IDOS->Delay(150);		IDOS->Delay(150);
Line 135:		Line 135:
	Save this program as windowtest.c and compile it with:		Save this program as windowtest.c and compile it with:

		⚫	gcc -o windowtest windowtest.c -lauto
	<pre>
⚫	gcc -o windowtest windowtest.c -lauto
	</pre>

	==== Manual Library Initialization ====		==== Manual Library Initialization ====

Steven Solie: /* Type Consistency */

2012-09-13T16:23:17Z

Type Consistency

← Older revision		Revision as of 16:23, 13 September 2012
Line 61:		Line 61:
	! Significance		! Significance
	\|-		\|-
	\| int8~~/uint8~~		\| int8
	\| BYTE~~/UBYTE~~		\| BYTE
	\| 8 bit signed~~/unsigned integer~~		\| 8 bit signed
	\|-		\|-
			\| uint8
⚫	\| ~~int16/~~uint16
			\| UBYTE
⚫	\| ~~WORD/~~UWORD
	\| 16 bit ~~signed/~~unsigned integer		\| 8 bit unsigned integer
	\|-		\|-
			\| int16
⚫	\| ~~int32/~~uint32
			\| WORD
⚫	\| ~~LONG/~~ULONG
	\| 32 bit signed~~/unsigned integer~~		\| 16 bit signed
	\|-		\|-
		⚫	\| uint16
⚫	\| ~~int64/~~uint64
		⚫	\| UWORD
			\| 16 bit unsigned integer
			\|-
			\| int32
			\| LONG
			\| 32 bit signed
			\|-
		⚫	\| uint32
		⚫	\| ULONG
			\| 32 bit unsigned integer
			\|-
			\| int64
			\| None existed
			\| 64 bit signed
			\|-
		⚫	\| uint64
	\| None existed		\| None existed
	\| 64 bit ~~signed/~~unsigned integer		\| 64 bit unsigned integer
	\|-		\|-
	\| float32		\| float32