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.

-mpcrel

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

-mdebug-labels

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

-mextralogues

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

-mown-gp

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

-palmosN

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

-palmos-none

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

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

1.3 Unsupported GCC features

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

-p

-pg

-a

-ax

-fprofile-arcs

-fbranch-probabilities

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

-ftest-coverage

A similar comment applies to the gcov data file.

-ffunction-sections

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.

-mbitfield

-m68020

-m68881

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

-mrtd

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:

• While describing the section attribute, the GCC manual suggests using the linker to split an executable into sections. Just like `-ffunction-sections', this doesn't work.

• The __complex__ extension doesn't work.

• The `-Wmultichar' warning is off by default, even if you use `-Wall'.

• If `-mpcrel' is on, as it always is, any `-fpic' or `-fPIC' options are ineffective: `-mpcrel' always implies `-fpic'.

• Because we care about code size (and don't have an instruction cache), too much of the following is probably counter-productive: `-ffunction-cse', `-funroll-loops', `-funroll-all-loops'. Hence these options are not implied by the `-O' flags, but must be selected explicitly.

• If you use 64K code resources, the linker `-r' option will not always work. Fortunately, these are both unnecessary.

• Changing the specs file with `-specs=file' or invoking m68k-palmos-as or m68k-palmos-ld directly should be done with caution: proper operation is quite dependent on options set in the default specs file.

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:

• The identifiers UInt8, Int8, UInt16, Int16, UInt32, Int32, MemPtr, and MemHandle are all typedeffed appropriately.

• The macro SDK_VERSION is defined to one of 10, 20, 30, 31, 35, 40, and so on, indicating the SDK version which is in use.

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.

• STANDALONE_CODE_RESOURCE_ID (res_id)
• STANDALONE_CODE_RESOURCE_TYPE_ID (res_type, res_id)
• STANDALONE_CODE_RESOURCE_TYPESTR_ID (res_type, res_id)
• HACKMASTER_TRAP (vector)