[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

1. Palm OS-specific GCC features

The modifications to GCC to support Palm OS programming add several new command line options and function attributes to GCC. Additionally, a few standard GCC features are not supported.

1.1 Palm OS-specific GCC options  
1.2 Function attributes  
1.3 Unsupported GCC features  
1.4 Include files  

1.1 Palm OS-specific GCC options

GCC for Palm OS supports the following options, in addition to all the usual target-independent and M68K-specific options.

Activate Palm OS-specific code generation patterns. This is turned on by default in the specs file; don't ever turn it off!

Put each function's name into the text section immediately after the function's code, in MacsBug format.

Activate extralogue attributes. See section 2.3 The extralogue attribute and entry points.

Access global data via the A4 register, and activate owngp attributes. By default, global data are accessed via A5, and owngp attributes have no effect. See section 2. Global data.

This option implies `-mextralogues'.

Select system header files and libraries for Palm OS SDK version N. By default, the SDK selected as the default SDK the last time palmdev-prep was run will be used (see section 6.5 palmdev-prep).

Don't add any Palm OS SDK directories or other directories from any PalmDev trees to the include and library search paths.

There is also a `-mno-X' option corresponding to each of the `-mX' options, but you shouldn't ever need to use them.

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'.

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":

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).

1.3 Unsupported GCC features

The following GCC options are not currently supported on Palm OS:

Probably profiling is unsupported. Certainly the support functions in `libgcc' aren't being included, because they depend on non-existent stdio support.

A similar comment applies to the gcov data file.

This option sets each function's section after function calls are generated. This is too late to be effective because we need to emit special code for cross-section function calls.

These and other M68K hardware selection options will cause your programs to fail horribly.

This selects code generation patterns which disagree with the conventions used by the Palm OS API functions, so will fail horribly.

There are also the following caveats:

1.4 Include files

1.4.1 NewTypes.h

With Palm OS SDKs prior to the 3.5 SDK, programmers were encouraged to use typedefs such as DWord and VoidHand rather than the built-in types. In the 3.5 SDK, the names of these typedefs have been changed to the somewhat more mnemonic UInt32 (etc) and the rather more functional MemHandle. (Previously there were two "handle" datatypes, VoidHand and Handle, with no real reason for a distinction between them, and programmers were continually casting between them. MemHandle corrects this historical accident.)

People wanting to write library header files capable of interacting with any SDK have a dilemma: which to use, old- or new-style type names?

You can use old-style names by instructing developers to include `PalmCompatibility.h' before including your header file if they are using the 3.5 SDK. But this is not very satisfactory: the onus shouldn't be on developers to get this right, and you might prefer to use new-style names.

You can ensure new-style names are available simply by including `NewTypes.h' at the top of your header file, and instructing developers to include at least `Common.h'/`PalmTypes.h' before your header. (They are probably including `Pilot.h'/`PalmOS.h' anyway.)

Including `NewTypes.h' provides the following:

1.4.2 Standalone.h

Including `Standalone.h' provides the macros listed below, which facilitate building stand-alone code resources. See section 3.4 Stand-alone code resources.

[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]