Whole document tree

1.2 Function attributes

You specify a function attribute in the declaration of the function. In addition to the standard ones (see section `Declaring Attributes of Functions' in Using and Porting GCC), Palm OS defines the following function attributes:

callseq (insns)

A function with a callseq attribute is called using the assembly language instructions in insns, which may implement a Palm OS systrap or something more esoteric. The argument insns must be a string literal.

Generally you won't use the callseq attribute directly; instead, there are macros defined in `PalmTypes.h'.

systrap (vector)

The systrap attribute specifies that the function should be called using the Palm OS systrap mechanism. The integer vector may be either a literal such as `0xa000' or a constant value such as an enumeration constant. More complicated expressions are not permitted.

This attribute is deprecated and will be removed from a future version of prc-tools. New code should use callseq instead.

You shouldn't use the systrap attribute directly; instead, you should use the SYS_TRAP macro defined in `CoreTraps.h'.

owngp

When `-mown-gp' is used, the owngp attribute causes the function to save the A4 register on entry, and restore it on exit.

You shouldn't use owngp directly; instead, you should use the macros defined in `EntryPoints.h'.

extralogue (prologue, epilogue,...)

When `-mextralogues' is used, the extralogue attribute causes the function to add code to its prologue and epilogue according to the arguments given. See section 2.3 The extralogue attribute and entry points, for details.

You shouldn't use extralogue directly; instead, you should use the macros defined in `EntryPoints.h'.

section (section-name)

This attribute is a standard one, and is used on Palm OS to indicate functions which should be placed in a code resource other than the default `code #1'.

In theory, the commonly used attributes differ in their "required visibilities":

• A systrap or callseq attribute is only important to anyone calling the function. (You don't usually define such functions yourself anyway.)

• Callers don't care that a function has an extralogue or saves its owngp; these really only have effects when the code for that function is generated.

• On Palm OS, a function's section is important both to itself (it determines what section the code is put in) and to other functions calling it (it can cause a special cross-section calling sequence to be emitted).

In practice, probably the best policy is to have exactly one declaration for each function that needs one, in a header file somewhere, and to use `-Wimplicit' (which is implied by `-Wall'), and possibly also `-Wmissing-declarations', to ensure that the declaration is visible when it needs to be (see section `Options to Request or Suppress Warnings' in Using and Porting GCC).