3.4 Stand-alone code resources

Normally build-prc processes a bfd executable as a full-blown executable, converting its .data, .bss, and .text and any other code sections into the corresponding Palm OS resources, as appropriate.

However if the bfd executable contains certain sections that are special to build-prc, its .text section will be converted into a stand-alone code resource instead, and the other sections listed above will be discarded (producing warnings) if present.

These "special sections" are .disposn (which is an abbreviation of disposition) and .trap. They are interpreted as follows:

• The first two bytes of a .disposn section, if present, specify the generated resource's ID, while (if the section is at least six bytes in length) the next four bytes specify its type. If the .disposn section is only two bytes in length, the generated resource's type will be a suitable default dependent on the architecture of the bfd executable: code for 68000 or armc for ARM.

• The first two bytes of a .trap section, if present, are converted into a TRAP resource. If a .disposn section is also present, the TRAP resource will have the ID specified by that section; otherwise (when the project definition file specifies the Hack project kind), TRAP and code resources converted from successive bfd executables are numbered consecutively from 1000.

Note that these two-byte integer fields are interpreted according to the native endianness of the bfd executable in which they occur.

Producing a stand-alone code resource

There is nothing special about compiling code that is to become stand-alone, other than that you must not use global data or any extra code resources, because stand-alone code, by definition, cannot have such things.

There are considerations at link time, related to the lack of startup code:

• Stand-alone code needs to be called directly; in particular, the startup code for a Palm OS application or GLib shared library is certainly not appropriate. Hence you should link using GCC's -nostartfiles option (see section `Options for Linking' in Using and Porting GCC).

• If the bfd executable's entry point is not at offset 0 within its .text section, build-prc will insert an appropriate jump instruction at the start of the generated code resource. Thus a stand-alone code resource can always be jumped to by jumping to its beginning.

  You specify the entry point at link time: in short, it is a function named start() by default, or you can set it with the -e option (see section `Setting the entry point' in Using ld).

You can easily set up the special sections marking your code as stand-alone by using the following macros, provided in `Standalone.h':

STANDALONE_CODE_RESOURCE_ID (id)

Mark the executable as a stand-alone code resource with the specified id and a suitable resource type depending on the resulting compiled executable's architecture: `code' for 68000 or `armc' for ARM.

STANDALONE_CODE_RESOURCE_TYPE_ID (type, id)

STANDALONE_CODE_RESOURCE_TYPESTR_ID (type, id)

Mark the executable as a stand-alone code resource with the specified resource type and id. If you specify type with a multicharacter char constant (`'TYPE''), use the ...TYPE... macro; if you use a string (`"TYPE"'), use the ...TYPESTR... version.

HACKMASTER_TRAP (vector)

Mark the executable as a stand-alone code resource, and add a TRAP resource containing vector, which may be any C constant expression, for example, a numeric constant or even a sysTrapfoo constant as defined in a Palm OS SDK's `CoreTraps.h'.