Controls the organization of object code.

This pragma is compatible with the following platform targets:

68K

PowerPC

NEC V800

Intel x86

MIPS

Embedded 68K

For PowerPC:

For Embedded 68K:

This sophisticated and powerful pragma lets you arrange compiled object code into predefined sections and sections you define. This topic is organized into these parts:

• Parameters for PowerPC
• Section access permissions for PowerPC
• Predefined sections and default sections for PowerPC
• Forms for #pragma section for PowerPC
• Forcing individual objects into specific sections for PowerPC
• Using #pragma section with #pragma push and #pragma pop for PowerPC
• Parameters for Embedded 68K
• Using #pragma section with #pragma push and #pragma pop for Embedded 68K

The optional objecttype parameter specifies where types of object data are stored. It may be one or more of the following values:

• code_type-executable object code
• data_type-non-constant data of a size greater than the size specified in the small data threshold option in the PowerPC EABI Project settings panel
• sdata_type-non-constant data of a size less than or equal to the size specified in the small data threshold option in the PowerPC EABI Project settings panel
• const_type-constant data of a size greater than the size specified in the small const data threshold option in the PowerPC EABI Project settings panel
• sconst_type-constant data of a size less than or equal to the size specified in the small const data threshold option in the PowerPC EABI Project settings panel
• all_types-all data

CodeWarrior C/C++ generates some of its own data, such as exception and static initializer objects, which are not affected by #pragma section.

The optional permission parameter specifies access permission. It may be one or more of these values:

• R-read only permission
• W-write permission
• X-execute permission

The optional iname parameter is a quoted name that specifies the name of the section where the compiler stores initialized objects. Variables that are initialized at the time they are defined, functions, and character strings are examples of initialized objects. The iname parameter may be of the form ".abs.xxxxxxxx" where xxxxxxxx is an 8-digit hexadecimal number specifying the address of the section.

The optional uname parameter is a quoted name that specifies the name of the section where the compiler stores uninitialized objects. This parameter is required for sections that have data objects. The uname parameter may be a unique name or it may be the name of any previous iname or uname section. If the uname section is also an iname section then uninitialized data will be stored in the same section as initialized objects.

The special uname COMM specifies that uninitialized data will be stored in the common section. The linker will put all common section data into the ".bss" section. When the Use Common Section option is on in the PowerPC EABI Processor panel, COMM is the default uname for the ".data" section. When the Use Common Section option is off, COMM is the default uname for the ".bss" section.

The uname parameter may be changed. For example, you may want most uninitialized data to go into the ".bss" section while specific variables be stored in the COMM section. Listing 8.13 shows an example of specifying that specific uninitialized variables be stored in the COMM section.

// the Use Common Section option is off
#pragma push // save the current state
#pragma section ".data" "COMM"
int foo;
int bar;
#pragma pop // restore the previous state

You may not use any of the object types, data modes, or code modes as the names of sections. Also, you may not use pre-defined section names in the PowerPC EABI for your own section names.

The optional data_mode=datamode parameter tells the compiler what kind of addressing mode to use for referring to data objects for a section.

The permissible addressing modes for datamode are:

The sda_rel addressing mode may only be used with the ".sdata", ".sbss", ".sdata2", ".sbss2", ".EMB.PPC.sdata0", and ".EMB.PPC.sbss0" sections.

The default addressing mode for large data sections is far_abs. The default addressing mode for the predefined small data sections is sda_rel.

Specify one these addressing modes without quotes.

The optional code_mode=codemode parameter tells the compiler what kind of addressing mode to use for referring to executable routines for a section.

The permissible addressing modes for codemode are:

The default addressing mode for executable code sections is pc_rel.

Specify one these addressing modes without quotes.

When you define a section using #pragma section, its default access permission is read only. If you change the current section for a particular object type, the compiler adjusts the access permission to allow the storage of objects of that type while continuing to allow objects of previously-allowed object types. Associating code_type to a section adds execute permission to that section. Associating data_type, sdata_type, or sconst_type to a section adds write permission to that section.

Occasionally you might create a section without making it the current section for an object type. You might do so to force an object into a section with the __declspec keyword. In this case, the compiler will automatically update the access permission for that section to allow the object to be stored in the section, then issue a warning. To avoid such a warning, make sure to give the section the proper access permissions before storing object code or data into it. As with associating an object type to a section, passing a specific permission adds to the permissions that a section already has.

The predefined sections set with an object type become the default section for that type. After assigning a non-standard section to an object type, you may refer to the default section with one of the forms in "Forms for #pragma section for PowerPC."

The compiler predefines the sections in Listing 8.14.

#pragma section code_type ".text" data_mode=far_abs \
 code_mode=pc_rel
#pragma section data_type ".data" ".bss" data_mode=far_abs \
 code_mode=pc_rel
#pragma section const_type ".rodata" ".rodata" data_mode=far_abs \
 code_mode=pc_rel
#pragma section sdata_type ".sdata" ".sbss" data_mode=sda_rel \
 code_mode=pc_rel
#pragma section sconst_type ".sdata2" ".sbss2" data_mode=sda_rel \
 code_mode=pc_rel
#pragma section ".EMB.PPC.sdata0" ".EMB.PPC.sbss0" \
 data_mode=sda_rel code_mode=pc_rel

This pragma has these principal forms:

This form simply creates a section called ".name1" if it doesn't already exist. With this form, the compiler doesn't store objects in the section without an appropriate, subsequent #pragma section statement or an item defined with the __declspec keyword. If only one section name is specified, it is considered the name of the initialized object section, iname. If the section is already declared, you may also optionally specify the uninitialized object section, uname. If you know that the section is should have read and write permission, use #pragma section RW ".name1" instead, especially if you use the __declspec keyword.

With the addition of one or more object types, the compiler stores objects of the types specified in the section ".name2". If ".name2" doesn't exist, the compiler creates it with the appropriate access permissions. If only one section name is specified, it is considered the name of the initialized object section, iname. If the section is already declared, you may also optionally specify the uninitialized object section, uname. This feature is useful for temporarily circumventing the small data threshold.

When there is no iname parameter, the compiler resets the section for the object types specified to the default section. For information on predefined sections, see "Predefined sections and default sections for PowerPC." Resetting an object type's section doesn't reset its addressing modes. You must do so explicitly.

When declaring or setting sections, you may also add a uninitialized section to a section that didn't have one originally by specifying a uname parameter. However, you may not change the uninitialized section associated with an initialized section once an uninitialized section has already been associated to it. Remember that an initialized section's corresponding uninitialized section may be the same.

You may store a specific object of an object type into a section other than the current section for that type without changing the current section. Use the __declspec keyword with the name of the target section and put it next to the extern declaration or static definition of the item you want to store in the section. Listing 8.15 shows examples.

__declspec(".data") extern int myVar;
#pragma section "constants"
__declspec("constants") const int myvar = 0x12345678;

This pragma may be used with #pragma push and #pragma pop to ease complex or frequent changes to sections settings. See Listing 8.13 for an example. Note that #pragma pop doesn't restore any changes to the access permissions of sections that exists before or after the corresponding #pragma push.

The parameters for Embedded 68K are:

• sname -specifies the name of the section where the compiler stores initialized objects.
• begin, end-specify the start and the end of a #pragma section block. The code and data within the block is placed in the named section.

This pragma may be used with #pragma push and #pragma pop to ease complex or frequent changes to sections settings. However, #pragma section blocks do not nest. You must end the previous section block before you can switch to a new one.