Amiga

From Lazarus wiki
Revision as of 15:21, 26 April 2014 by Chain-Q (talk | contribs) (alignment, good to know)
Jump to navigationJump to search

This page is about the so called 'classic Amiga' version of Free Pascal 2.x, which means Motorola 680x0 CPU based systems running AmigaOS 3.x and below. For MorphOS and AmigaOS4 versions, see the relevant pages.

Please note, that the information detailed here is specific to version Free Pascal 2.x and above, and does *not* apply to the old 0.99.x and 1.0.x versions of Free Pascal for Amiga, still available on various Amiga download sites.

Classic Amiga support is considered "working" since r27059 (v2.7.1, 2014-03-09) which marks the first working 'hello world!', compiled by a compiler also running on Amiga. However, we had no 'make cycle' run yet. (It would be possible to do so in emulators or on nextgen systems, due to memory constraints of most classic Amiga systems.)

Stack

Under Amiga, the default stack is set to 256 kB. Stack size can be set directly by the programmer with a compiler switch (-Cs), or with the {$MEMORY} directive. The memory area for the stack is dynamically allocated on program startup, so if you set this value too high, in low memory situations your program may exit immediately on startup without any further notice.

Please note that increasing stack size with the 'stack' utility will *NOT* work for your app, because the RTL startup code will replace the existing stack with the size specified by the directive, using the exec.library/StackSwap function.

SysCalls

Introduction to SysCalls

Free Pascal supports generating Amiga-style library calls. You don't need to use additional hand-written assembly to call any library function. However, you must declare every function you're going to use in the following way:

Var 
  my_LibBase: Pointer;

function my_OldCall(param1: LongInt location 'd0',
                    param2: LongInt location 'd1'): LongInt; 
         SysCall my_LibBase 1234; { Amiga-style call }

Where my_LibBase is the library base returned by exec's OpenLibrary() call, and 1234 is the call offset. Please note that offset values in Free Pascal must be specified as positive values, and not negative as shown in the Amiga SDK. my_LibBase can be a typed pointer, a dword or a void pointer. It's recommended to use PLibrary or the library's own type if one exists or possible.

Other hints about libraries and Syscalls

MOST IMPORTANT: While creating your own interface units for libraries, you must open the libraries you're going to use explicitly before using any function from them. Don't forget to close all libraries before you exit. The interface units bundled with the compiler will auto open and close the respective libraries (unless otherwise noted).

Naming conventions

This section describes the differences between the official Amiga SDK, which is for C and assembly language, and Amiga-specific units in FPC RTL.

Constants

System constants are named exactly like in Amiga SDK.

Structures

System structures are named similar like in Amiga SDK, but follows the Pascal convention about type naming, so structure names has a T before, and each type has a pointer to type with P before the name. The following example should make things trivial:

 struct Task equals to TTask
 struct Task * equals to PTask

Alignment

Record elements are aligned to WORD (2 bytes) under Amiga by default. Use {$PACKRECORDS 4} if you need dword aligned structures. For byte aligned records, use a packed record.

Things good to know

Here are a few hints, which I think are good to remember, when using FPC on Amiga.

  • On program exit, System unit will close all files opened via its own functions, so it's recommended to use them in most cases.
  • Do not mix FPC and OS file functions on a single file. It may work in some cases, but that's purely a coincidence. It's bad programming and can stop working anytime without notice.
  • On program exit, the heap manager will free all memory allocated via its own functions. It uses a memory pool to avoid fragmentation. It also makes debugging easier when using heaptrc unit. Using OS memory functions directly is not recommended, unless you explicitly require memory areas which should stay in memory after your process has exited (like pointers passed to other processes).
  • Do not mix FPC and OS memory functions on a pointer. It won't work and will only cause crashes and/or memory leaks.