Difference between revisions of "MorphOS"

From Free Pascal wiki
Jump to navigationJump to search
(AmigaOS link added)
(Small layout changes)
Line 2: Line 2:
  
  
−
===Stack===
+
==Stack==
 
Under MorphOS, 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.
 
Under MorphOS, 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.
  
 
Note to classic Amiga programmers: Increasing stack size with the 'stack' utility provided with MorphOS '''will not work''' because it sets the size of the 68k stack for applications running in 68k emulation.
 
Note to classic Amiga programmers: Increasing stack size with the 'stack' utility provided with MorphOS '''will not work''' because it sets the size of the 68k stack for applications running in 68k emulation.
  
−
===SysCalls===
+
==SysCalls==
  
−
====Introduction to SysCalls====
+
===Introduction to SysCalls===
 
Since version 1.9.7 2005/01/06 Free Pascal supports ABox style legacy, and four new calling conventions based on SysV ABI on MorphOS. Before that, only ABox style calls were supported. 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:
 
Since version 1.9.7 2005/01/06 Free Pascal supports ABox style legacy, and four new calling conventions based on SysV ABI on MorphOS. Before that, only ABox style calls were supported. 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:
 
   
 
   
Line 42: Line 42:
 
If you don't want to specify SysCall method explicitly for every call, you can set a default SysCall method, using the {$SYSCALL} directive. {$SYSCALL LEGACY} (which is the built-in default) sets ABox-style, {$SYSCALL SYSV} sets SysV style calls as default. Other possible arguments for {$SYSCALL} directive are SYSVBASE, BASESYSV and R12BASE. Please note that the calling convention rules are not strict inside a library, so you might found different kinds of it inside a single library.
 
If you don't want to specify SysCall method explicitly for every call, you can set a default SysCall method, using the {$SYSCALL} directive. {$SYSCALL LEGACY} (which is the built-in default) sets ABox-style, {$SYSCALL SYSV} sets SysV style calls as default. Other possible arguments for {$SYSCALL} directive are SYSVBASE, BASESYSV and R12BASE. Please note that the calling convention rules are not strict inside a library, so you might found different kinds of it inside a single library.
  
−
====What different kinds of SysCalls do?====
+
===What different kinds of SysCalls do?===
  
 
Old libraries like exec and dos mostly using Legacy and SysV, newer PowerPC-native libs using SysV and BaseSysV, most current libs are using SysV and R12Base calls. SysVBase calls are rare, but do exist, so check for them when you create your own units for external libraries. If you want to figure out which calling convention a library uses, you can search it's SDK for some fd/*.fd files, where this information is stored.  
 
Old libraries like exec and dos mostly using Legacy and SysV, newer PowerPC-native libs using SysV and BaseSysV, most current libs are using SysV and R12Base calls. SysVBase calls are rare, but do exist, so check for them when you create your own units for external libraries. If you want to figure out which calling convention a library uses, you can search it's SDK for some fd/*.fd files, where this information is stored.  
  
−
=====Legacy=====
+
====Legacy====
 
Legacy calling convention puts arguments into the 68k emulation structure, which is pointed by register r2. 0(r2) equals to 68k register d0, 4(r2) to d1, and so on. It puts libbase into 56(r2) which equals to 68k register a6, then puts call offset into r3, and jumps to address stored at $64(r2), which is the emulation entry point. On return it returns arguments in register r3. This calling convention is used to provide compatibility with existing 68k and classic Amiga PowerPC apps.
 
Legacy calling convention puts arguments into the 68k emulation structure, which is pointed by register r2. 0(r2) equals to 68k register d0, 4(r2) to d1, and so on. It puts libbase into 56(r2) which equals to 68k register a6, then puts call offset into r3, and jumps to address stored at $64(r2), which is the emulation entry point. On return it returns arguments in register r3. This calling convention is used to provide compatibility with existing 68k and classic Amiga PowerPC apps.
  
−
=====SysV=====
+
====SysV====
 
SysV calling convention stores arguments according to SysV.4 ABI, then jumps to address stored at (LibBase - Offset). This calling convention is often used where no LibBase is needed.
 
SysV calling convention stores arguments according to SysV.4 ABI, then jumps to address stored at (LibBase - Offset). This calling convention is often used where no LibBase is needed.
  
−
=====BaseSysV=====
+
====BaseSysV====
 
BaseSysV is a variation of SysV. It stores LibBase as first argument according to SysV.4 ABI, then puts all other arguments, then jumps to address stored at (LibBase - Offset). This calling convention also can be considered as legacy, R12Base convention replaced it, but still many libraries using it.
 
BaseSysV is a variation of SysV. It stores LibBase as first argument according to SysV.4 ABI, then puts all other arguments, then jumps to address stored at (LibBase - Offset). This calling convention also can be considered as legacy, R12Base convention replaced it, but still many libraries using it.
  
−
=====SysVBase=====
+
====SysVBase====
 
SysVBase is a variation of SysV. It stores all arguments according to SysV.4 ABI, then stores LibBase as last argument, then jumps to address stored at (LibBase - Offset). This calling convention also can be considered as legacy, as R12Base convention replaced it. This one is rare, not many libraries using it.
 
SysVBase is a variation of SysV. It stores all arguments according to SysV.4 ABI, then stores LibBase as last argument, then jumps to address stored at (LibBase - Offset). This calling convention also can be considered as legacy, as R12Base convention replaced it. This one is rare, not many libraries using it.
  
−
=====R12Base=====
+
====R12Base====
 
R12Base is a variation of SysV. It stores all arguments according to SysV.4 ABI, then stores LibBase into register r12, then jumps to address stored at (LibBase - Offset). This calling convention superseeded BaseSysV and SysVBase, and should be used in new libraries.
 
R12Base is a variation of SysV. It stores all arguments according to SysV.4 ABI, then stores LibBase into register r12, then jumps to address stored at (LibBase - Offset). This calling convention superseeded BaseSysV and SysVBase, and should be used in new libraries.
  
−
====Other hints about libraries and Syscalls====
+
===Other hints about libraries and Syscalls===
 
'''MOST IMPORTANT:''' You must open the libraries you're going to use explicitly '''before''' using any function from them, because the compiler will not do it for you. Don't forget to close all libraries before you exit.  
 
'''MOST IMPORTANT:''' You must open the libraries you're going to use explicitly '''before''' using any function from them, because the compiler will not do it for you. Don't forget to close all libraries before you exit.  
  
 
Before declaring a SysCall function, please check the units provided with FPC, the function you want to use might already be declared in one of the units, ready to be used.
 
Before declaring a SysCall function, please check the units provided with FPC, the function you want to use might already be declared in one of the units, ready to be used.
  
−
===Naming conventions===
+
==Naming conventions==
 
This section describes the differences between the official MorphOS SDK, which is for C language, and MorphOS-specific units in FPC RTL.
 
This section describes the differences between the official MorphOS SDK, which is for C language, and MorphOS-specific units in FPC RTL.
  
−
====Constants====
+
===Constants===
 
System constants are named exactly like in MOS SDK.
 
System constants are named exactly like in MOS SDK.
  
−
====Structures====
+
===Structures===
 
System structures are named similar like in MOS 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:
 
System structures are named similar like in MOS 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 TTask
 
   struct Task * equals to PTask
 
   struct Task * equals to PTask
  
−
====Function calls====
+
===Function calls===
 
System calls are named like in MOS SDK, but there are a few exceptions. Unfortunately MOS legacy (Amiga compatible) API has some name conflicts with Free Pascal RTL functions, and this issue cannot be solved with function overloading. These calls are available with a name prefixed by their library's name. So for example, exec.library's FreeMem() is available under the name execFreeMem(), and FreeMem() means the FreeMem() call of FPC's own heap manager. The following functions are known to be affected:
 
System calls are named like in MOS SDK, but there are a few exceptions. Unfortunately MOS legacy (Amiga compatible) API has some name conflicts with Free Pascal RTL functions, and this issue cannot be solved with function overloading. These calls are available with a name prefixed by their library's name. So for example, exec.library's FreeMem() is available under the name execFreeMem(), and FreeMem() means the FreeMem() call of FPC's own heap manager. The following functions are known to be affected:
 
* exec.library
 
* exec.library
Line 99: Line 99:
 
Be prepared for more...
 
Be prepared for more...
  
−
===Alignment===
+
==Alignment==
 
Record elements are aligned to DWORD (4 bytes) under MorphOS by default. Use {$PACKRECORDS 2} if you need word aligned structures. For byte aligned records, use a packed record.
 
Record elements are aligned to DWORD (4 bytes) under MorphOS by default. Use {$PACKRECORDS 2} if you need word aligned structures. For byte aligned records, use a packed record.
  
−
===FPCMake===
+
==FPCMake==
 
[[Fpcmake|FPCMake]] is working on MorphOS, since 2005.01.11.
 
[[Fpcmake|FPCMake]] is working on MorphOS, since 2005.01.11.
  
−
===Things good to know===
+
==Things good to know==
 
Here are a few hints, which i think are good to remember, when using FPC on MorphOS.
 
Here are a few hints, which i think are good to remember, when using FPC on MorphOS.
 
* On program exit, System unit will close all files opened via it's own functions, so it's recommended to use them in most cases.
 
* On program exit, System unit will close all files opened via it's own functions, so it's recommended to use them in most cases.
Line 114: Line 114:
 
* If you need syntax highlight, consider using GoldEd, or the lite version MorphEd, which is available in the MorphOS Superbundle. A very nice Pascal syntax highlight addon was made for it by Rafal Zabdyr, and it's available here: http://pingu.ii.uj.edu.pl/~armo/amipascal/download/ged5morphed_pas075.lha
 
* If you need syntax highlight, consider using GoldEd, or the lite version MorphEd, which is available in the MorphOS Superbundle. A very nice Pascal syntax highlight addon was made for it by Rafal Zabdyr, and it's available here: http://pingu.ii.uj.edu.pl/~armo/amipascal/download/ged5morphed_pas075.lha
  
−
===To Do===
+
==To Do==
 
There are still many things on the To Do list. Currently, these are the most important ones.
 
There are still many things on the To Do list. Currently, these are the most important ones.
 
* <strike>Fix startup code to exit gracefully when stack cannot be allocated</strike>
 
* <strike>Fix startup code to exit gracefully when stack cannot be allocated</strike>
Line 149: Line 149:
 
* ... and more
 
* ... and more
  
−
===Thanks===
+
==Thanks==
 
The MorphOS http://www.morphos.net port of Free Pascal Compiler was possible, because Genesi S.a.r.l. http://www.genesi.lu provided a free Pegasos II/G4 http://www.pegasosppc.com machine to do the development on.
 
The MorphOS http://www.morphos.net port of Free Pascal Compiler was possible, because Genesi S.a.r.l. http://www.genesi.lu provided a free Pegasos II/G4 http://www.pegasosppc.com machine to do the development on.

Revision as of 16:28, 4 June 2005

This page contains platform specific notes about the MorphOS version. If you need information about AmigaOS version, read this page.


Stack

Under MorphOS, 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.

Note to classic Amiga programmers: Increasing stack size with the 'stack' utility provided with MorphOS will not work because it sets the size of the 68k stack for applications running in 68k emulation.

SysCalls

Introduction to SysCalls

Since version 1.9.7 2005/01/06 Free Pascal supports ABox style legacy, and four new calling conventions based on SysV ABI on MorphOS. Before that, only ABox style calls were supported. 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 Legacy my_LibBase 1234; { ABox-style call }

function my_SysVCall(param1: LongInt;
                     param2: LongInt): LongInt;
         SysCall SysV my_LibBase 1240; { SysV ABI call }

function my_BaseSysVCall(param1: LongInt;
                         param2: LongInt): LongInt;
         SysCall BaseSysV my_LibBase 1246; { Base,SysV ABI call }

function my_SysVBaseCall(param1: LongInt;
                         param2: LongInt): LongInt;
         SysCall SysVBase my_LibBase 1252; { SysV,Base ABI call }

function my_R12BaseCall(param1: LongInt;
                        param2: LongInt): LongInt;
         SysCall R12Base my_LibBase 1258; { SysV,r12Base ABI 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 MorphOS SDK. Since compiler version 2004/08/22, my_LibBase can be a typed pointer, beside a dword and a void pointer. It's recommended to use PLibrary or the library's own type if one exists or possible.

In case of ABox style calls, the value after location can be any 68k register from d0-d7/a0-a5. Register a6 is used internally to pass my_LibBase in it. Register a7/sp cannot be used. Register names are not case sensitive. In ABox-style SysCalls you must specify a location for every argument explicitly.

If you don't want to specify SysCall method explicitly for every call, you can set a default SysCall method, using the {$SYSCALL} directive. {$SYSCALL LEGACY} (which is the built-in default) sets ABox-style, {$SYSCALL SYSV} sets SysV style calls as default. Other possible arguments for {$SYSCALL} directive are SYSVBASE, BASESYSV and R12BASE. Please note that the calling convention rules are not strict inside a library, so you might found different kinds of it inside a single library.

What different kinds of SysCalls do?

Old libraries like exec and dos mostly using Legacy and SysV, newer PowerPC-native libs using SysV and BaseSysV, most current libs are using SysV and R12Base calls. SysVBase calls are rare, but do exist, so check for them when you create your own units for external libraries. If you want to figure out which calling convention a library uses, you can search it's SDK for some fd/*.fd files, where this information is stored.

Legacy

Legacy calling convention puts arguments into the 68k emulation structure, which is pointed by register r2. 0(r2) equals to 68k register d0, 4(r2) to d1, and so on. It puts libbase into 56(r2) which equals to 68k register a6, then puts call offset into r3, and jumps to address stored at $64(r2), which is the emulation entry point. On return it returns arguments in register r3. This calling convention is used to provide compatibility with existing 68k and classic Amiga PowerPC apps.

SysV

SysV calling convention stores arguments according to SysV.4 ABI, then jumps to address stored at (LibBase - Offset). This calling convention is often used where no LibBase is needed.

BaseSysV

BaseSysV is a variation of SysV. It stores LibBase as first argument according to SysV.4 ABI, then puts all other arguments, then jumps to address stored at (LibBase - Offset). This calling convention also can be considered as legacy, R12Base convention replaced it, but still many libraries using it.

SysVBase

SysVBase is a variation of SysV. It stores all arguments according to SysV.4 ABI, then stores LibBase as last argument, then jumps to address stored at (LibBase - Offset). This calling convention also can be considered as legacy, as R12Base convention replaced it. This one is rare, not many libraries using it.

R12Base

R12Base is a variation of SysV. It stores all arguments according to SysV.4 ABI, then stores LibBase into register r12, then jumps to address stored at (LibBase - Offset). This calling convention superseeded BaseSysV and SysVBase, and should be used in new libraries.

Other hints about libraries and Syscalls

MOST IMPORTANT: You must open the libraries you're going to use explicitly before using any function from them, because the compiler will not do it for you. Don't forget to close all libraries before you exit.

Before declaring a SysCall function, please check the units provided with FPC, the function you want to use might already be declared in one of the units, ready to be used.

Naming conventions

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

Constants

System constants are named exactly like in MOS SDK.

Structures

System structures are named similar like in MOS 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

Function calls

System calls are named like in MOS SDK, but there are a few exceptions. Unfortunately MOS legacy (Amiga compatible) API has some name conflicts with Free Pascal RTL functions, and this issue cannot be solved with function overloading. These calls are available with a name prefixed by their library's name. So for example, exec.library's FreeMem() is available under the name execFreeMem(), and FreeMem() means the FreeMem() call of FPC's own heap manager. The following functions are known to be affected:

  • exec.library
    • AllocMem() (only causes trouble inside System unit),
    • FreeMem()
    • Insert()
  • dos.library
    • Close()
    • Read()
    • Write()
    • Input()
    • Output()
    • Seek()
    • Rename()
    • Exit()
    • Flush()
    • System()
    • DeleteFile() (conflicts with SysUtils)
    • CreateDir() (conflicts with SysUtils)

Be prepared for more...

Alignment

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

FPCMake

FPCMake is working on MorphOS, since 2005.01.11.

Things good to know

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

  • On program exit, System unit will close all files opened via it's own functions, so it's recommended to use them in most cases.
  • Do not mix FPC's and the OS's 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 it's 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.

To Do

There are still many things on the To Do list. Currently, these are the most important ones.

  • Fix startup code to exit gracefully when stack cannot be allocated
  • Clean up some messy parts of System unit
  • Clean up DOS unit, and fix the bugs
    • (started, situation is much better now, worst bugs already fixed, in CVS)
  • Clean up and finish SysUtils and Classes unit
    • (started, with some great progress, eg. FPCMake now works, in CVS)
  • Start to implement MorphOS specific units:
    • Exec
    • DOSLib
    • Utility
    • Graphics
    • Hardware & Inputevent
    • Layers
    • Intuition
    • Clipboard
    • Get9 :)
    • ASL
    • CyberGraphX (started, not yet in CVS)
    • AHI
    • MUI (basic work done)
    • Timer
    • TinyGL (basic work done)
    • PowerSDL (basic work done)
    • ...and more
  • Release a snapshot
  • Implement SysV-style calls
  • Implement Array Of ... support in Legacy SysCalls
  • Migrate away from the (buggy) GNU LD to vlink
  • Migrate away from the (slow) GNU AS if possible
  • Make Lineinfo unit work
  • Make snapshot releases regular
  • ... and more

Thanks

The MorphOS http://www.morphos.net port of Free Pascal Compiler was possible, because Genesi S.a.r.l. http://www.genesi.lu provided a free Pegasos II/G4 http://www.pegasosppc.com machine to do the development on.

Retrieved from "http://wiki.freepascal.org/index.php?title=MorphOS&oldid=15879"