AROS

The Amiga Research OS

(C) Copyright 1996 AROS - The Amiga Research OS

Chapter 3. Informations for Developers

3.1 Differences between AmigaOS and AROS

3.1.1 Pointer/Integer conversions

If you need a variable which can store a pointers as an integer, don't use ULONG but IPTR. AROS guarantees that LONG is 32bit on all systems, while IPTR is always large enough to contain a pointer. Most notable things which are affected by this: TagItems (the ti_Data field is now an IPTR instead of ULONG), BOOPSI classes (eg. the return value of DoMethod()), ReadArgs(), VPrintf(), VFPrintf() and more.

3.1.2 64bit variables

The type of 64bit variables is QUAD (unsigned: UQUAD). This is for example returned by the function SMult64() of utility.library. To access the high- and loworder 32bit values of the 64bit variable, use LOW32OF64() and HIGH32OF64() which are defined in AROS/include/aros/64bit.h.

3.1.3 Cloning RastPorts

AROS uses an external driver to access the graphics hardware. Since the nature of this driver is unknown to AROS, it is no longer valid to clone a RastPort by simply copying it. To be compatible, there are two new functions (in AROS) or macros (on Amiga): CreateRastPort(), CloneRastPort() and FreeRastPort(). You must call CloneRastPort() to create a copy or CreateRastPort() for an empty RastPort and FreeRastPort() after you´ve done your work with it.

This approach produces equivalent code on the Amiga but on AROS it can slow things down a bit. If you must preserve the original state of the RastPort, it's more safe to create a clone, work on it and then dispose of it again. It can also be faster if you would have to make a lot of changes to the RastPort to create two clones and set them to the two states you need. But your code should not depend on certain gains or losses of speed due to cloned RastPorts since the behaviour of the underlying graphics system is undefined.

3.1.4 Tag values

The original AmigaOS doesn't use the tags below USER_TAG (have a look at include:utility/tagitem.h if you don't belive me) which means, you shouldn't use tags at or near USER_TAG because then they might interfere with the OS's own tags. To solve this, AROS *does* use the tags *below* USER_TAG and the various implementators need not fear that their tags may overlap with the ones from the system. The file AROS/include/utility/tagitem.h now contains the basic offsets for the various parts of the OS. In the future, it might be possible for users to allocate ranges of tags for specific uses.

3.1.5 DoMethod() or the stack is all wrong

There are CPUs around which don't care that the rest of the world have stacks which grow from large to small adresses. HPPA is an example for this. While it might look neat to the engineers who did it, it breaks our code. Another thing which breaks the code are small data types (eg. WORD, UBYTE, etc), because most systems put only integers or longs and pointers on the stack. So if some Msg structure expects WORD (see include:intuition/gadgetclass.h), this fails on every system but the Amiga. Then there are rumours about CPUs which use 32bit numbers and 64bit pointers or the other way round. On these CPUs, SetAttrs() and all other function which pass TagLists over the stack will fail. To overcome this, we introduce this rule:

To solve special problems on certain CPUs, we try to get a compiler which gets it right or, if that is impossible, we write a small preprocessor which replaces the dubious code by calls to the array versions.

3.1.6 Registers and CPUs

AROS has put some effort in defining a way to write code which is hardware independant. To achieve this, a couple of macros have been definied.

 
AROS_ASMSYMNAME(n)
Use this macro to access the assembler symbol n from C.
AROS_CSYMNAME(n)
Use this macro to access the C symbol n from assembler.
AROS_CDEFNAME(n)
Use this macro to define the assembler symbol n in such a way that it can be accessed from C.
AROS_SLIB_ENTRY(n,l)
Use this macro to get the name of a function n which is part of the shared library l.
AROS_UFH#(...)
Use this macro to declare a function which needs its arguments passed in registers. # is the number of arguments the function expects. The parameters of the macro are the return type of the function, its name and the parameters in AROS_UFHA() macros. If the function is an assembler function, you must use the AROS_ASMSYMNAME() macro to get it's name.
AROS_UFHA(t,n,r)
Use this macro to declare a parameter for a function which is declared with the AROS_UFH*() macro. It takes three arguments: The type of the parameter, the name of the parameter and the register the parameter is expected in.
AROS_UFC#(...)
Call a function which needs its arguments in registers. Works the same way as AROS_UFH*().
AROS_LH#[I](...)
Use this macro to declare a function which is part of a shared library. # is the number of arguments the function expects. If the function doesn't need the library base passed, you can speed up things by appending "I" to the macros name. The parameters of the macro are the return type of the function, its name, the parameters in AROS_LHA() macros, the type of the library, the name of the variable the library base is passed in, the offset in the function table (1 is the first offset and 5 is the first offset for a user function) and the name of the library.
AROS_LHA(t,n,r)
Use this macro to declare a parameter for a function which is declared with the AROS_LH*() macro. It takes three arguments: The type of the parameter, the name of the parameter and the register the parameter is expected in.
AROS_LC#[I](...)
Call a function which is part of a shared library. Works the same way as AROS_LH*().
AROS_STACK_GROWS_DOWNWARDS
has the value 1 if it is true and 0 otherwise.
AROS_BIG_ENDIAN
has the value 1 if the machine is big endian (eg. Amiga) or little endian (eg. PCs). Endianess means the way a number is stored in memory. Amiga stores 0x11223344 as 0x11 0x22 0x33 0x44 in memory while a PC does it as 0x44 0x33 0x22 0x11.
AROS_SIZEOFULONG
The result of sizeof(ULONG).
AROS_WORDALIGN
The minimal alignment of 16bit numbers in the memory of computer ( WORD and UWORD).
AROS_LONGALIGN
The minimal alignment of 32bit numbers in the memory of computer ( LONG and ULONG).
AROS_PTRALIGN
The minimal alignment of pointers in the memory of computer (eg. char * or APTR).
AROS_DOUBLEALIGN
The minimal alignment of 64bit IEEE floating point numbers in the memory of computer ( double).
AROS_WORSTALIGN
The worst possible alignment of any data type in the memory of computer (mostly the same as AROS_DOUBLEALIGN).
AROS_ALIGN(x)
Get the next possible address where one can put any data type. This macro will return x if any data type can be put at x. Most of the time, this macro is used like this: Get a buffer, put some data in it and then use AROS_ALIGN() to find out where the next data can be put.
AROS_SLOWSTACKTAGS
is defined, if you must use GetTagsFromStack() and FreeTagsFromStack() instead of just passing the address of the tag of the first tagitem.
AROS_SLOWSTACKMETHODS
is defined, if you must use GetMsgFromStack() and FreeMsgFromStack() instead of just passing the address of the method ID.

3.2 One for all and all for one - CVS

CVS is a revision tool. It will maintain a database of the sources of a project and of the changes made to these sources. It will also merge any changes you make to the sources with the database.

CVS works with a server, called the repository (the main database), and clients, called the 'working directory', 'collection of sources' or 'private source directory'. Both the repository and the working directories can be on the same machine. AROS, however, uses a repository that is accessible over the internet, so that people all over the world can help make AROS.

CVS offers a list of commands to merge the most recent version of the project with the local sources and to publish changes one has made over the Internet.

3.2.1 CVS on Un*x

If you have Linux or any other Un*x, then all you need is CVS 1.9 or better. Note that versions of CVS between 1.9.16 and 1.10 don't work because the login protocol has changed. Versions after (and including) 1.10 work again.

If it's not already on your system (type cvs to find out), fetch CVS from one of the many GNU mirrors and install it in your $HOME.

If you want to get the sources only, you can use the anonymous access (see below). If you want to have full access to the database, then get the AROS developer archive from the AmiNET and compile crypt.c (just say make crypt or download crypt.c and follow the instructions in the file. Think of a good password and use crypt to encode it, like this:

Now skip the next section and read on in "How to get access to the AROS CVS server".

3.2.2 CVS on Amiga

First, you have to get CVS from ADE and install it. Then create a password as follows:

Get the demo for AmiTCP 4.0 ( AmiTCP-demo-40.lha in comm/tcp) from AmiNET (no need to install AmiTCP; just get the archive and extract the file AmiTCP from it). You also must have ixemul.library 45.0 (should come with ADE) and ixnet.library in LIBS:. Then you can create your password with crypt out of the AROS-crypt.lha archive from AmiNET (in dev/misc) like this:

(you must have the directory where crypt is stored in, in your path or you must do this in the same directory where crypt is).

CVS doesn't work with Miami. Miami uses a different routine for encrypting data than Un*x and therefore passwords generated with Miami won't work. Sorry. But you can use Miami with CVS to work on AROS after you have created a password with AmiTCP.

Versions of AmiTCP greater than 4.3 don't work either; they have changed the algorithm for encoding the password.

3.2.3 How to get access to the AROS CVS server

Mail the password you have created to me: digulla@aros.org. The subject must be Access to AROS CVS Server and with this text in the mail:

like this:

To check: You should get xx1LtbDbOY4/E if you call crypt with crypt test xx. If that doesn't work, download my public PGP key (Shift-Click on the link to download) and send me a PGP encoded mail with your password and I'll encrypt and add it.

Wait until I confirm this. While you wait, look for CVS 1.8 or better if you haven't already done so.

If you want read-only access, then your username is anon and your password is anon, too.

3.2.4 Logging into the server

Before you can use any CVS commands, you must log into the server. To do this, use the CVS command login:

where user is your login, eg. digulla:

On the Amiga, you must setenv HOME to a directory (eg. setenv HOME SYS:Home). Setting it to a device or assign doesn't work because CVS always adds a / after $HOME when it looks for it's files. And don't forget to copy it to ENVARC: ( copy ENV:HOME ENVARC:) to make it permanent.

This should ask you for your password. Type it in and if there is no error displayed, you are connected. If there is an error, try to omit the pserver. If this still doesn't work, double check for typos and if you really, really, really can't find anything, then you can send me an e-mail.

If the login has succeeded, then you can save you some typing by storing the argument to the -d option in the environment variable CVSROOT. Use

on Amiga or if you have a C shell (csh) and

for Bourne/Korn shells (bash, ksh).

On Amiga, you can make this permanent by copy env:CVSROOT envarc:, on Unix, you must add this to the shell's startup file ( .cshrc, .profile, .bashrc, .tcshrc, etc. Read the manual of your shell to find out). If you don't know what kind of shell you have, just try echo $SHELL or echo $shell. This should print the name of your shell.

If you haven't set this variable, you must add -d ... right after cvs in the following examples.

Now you can use any CVS command to get a copy of all AROS sources, update your sources or commit the changes you made.

3.2.5 How to get a copy of all AROS sources

Use the CVS checkout command for this:

This will create a directory called AROS and populate it with all sources.

3.2.6 How to update the sources

If you have some sources and just want to update them, you can use the CVS update command. Change to the AROS directory and do this:

This should merge any changes that other users have made into your sources and create all new directories and files. If you and someone else has changed the same file, then CVS will try to merge the changes. That is, if (s)he changed the first part and you the end of the file, CVS will do all the work for you. If there are changes which CVS can't resolve (eg. you said x--; and the other one x=x-1;), then CVS will put both versions in the file. Search for <<<< to find such problems.

You should do this before any commit in case this happens. So before you commit, do an update, call make if any changes were made, fix the problems and then commit.

3.2.7 Committing changes

If you have changed a file, then you of course want to share your work with the other guys. To do this, use the CVS commit command:

You can specify a list of files after the commit or just do that in the AROS directory to commit all changes. CVS will then ask you what you did and send the changes to the CVS server for inclusion. Before you do that, you should always make an update (see the previous section) to avoid problems.

3.2.8 Creating new files and directories

You can also add new files or directories with the CVS add command:

or

Note that cvs add dir/file doesn't work. You can only add files in the current directory.

3.2.9 More infos about CVS

Well, CVS has man pages and info files and here is a nice link.

3.3 The jobserver

3.3.1 What is this ?

Well, it's more a task server. Its purpose is to allow multiple people to work at the same project at the same time without any two persons doing the same work twice. This is accomplished by the jobserver. It has a database with all tasks that are still to do, tasks that are currently under construction and tasks which are finished.

3.3.2 How does it work ?

Just send an e-mail to

with the Subject: jobserv and in the body of the mail

It will list all commands that jobserv currently understands. Note that this is an automated service so the subject must match. jobserv ignores all lines in an email that it does not understand and stops reading at the first end or -- on a line of its own. jobserv will answer your e-mails telling you what it did, what commands it did understand, which it did execute and which not and if not, why not. jobserv will also remember your e-mail so others can see who added/requested/did which job - So don't worry about not getting credit for your work.

There is now a preliminary WWW interface for the jobserver:

3.3.3 Some commands the jobserver understands

 
add <id> <description>
Add a new job with the id <id> and the short text <description> as an explanation. <id> may contain any character except whitespace. Here is an example:

If the command was successful, the reply will tell you that a new job has been added to the database. If it wasn't successful, it will tell you why not (eg. because there is already a job with the same id).

req <id>
Allocate a task. This task will now be allocated by you. Your e-mail address will be stored with it so everyone can see who is working on that job and query you if you take too long or whatever.
done <id>
After you requested the job and finished it, you must tell jobserv that you're through.
show [free] [work] [done] [byme]
The most important command. It tells jobserv that you want to know what jobs are available and the like. All parameters are optional. "byme" is a flag which restricts the answer to jobs which match your e-mail. The other flags are additive and restrict the reply to jobs which are still open, currently in progress or finished. So to see the jobs which were added and finished by you, use

Note that jobserv doesn't remember that you added a task if someone else allocated it. The most useful variants will be:

which shows everything that's still open and

which shows what jobs you did allocate and haven't finished yet.