OS/2 Application Binary Interface for PowerPC (32-bit)

(Republishing Condition: IBM Copyright Permission #21953)

Introduction
This document describes the system interfaces for compiled application programs that will run on operating systems built on the IBM Microkernel technology for the PowerPC Architecture.

This document includes by reference other generally available documents as necessary. The reader may find the following documents of interest:
 * The PowerPC Architecture: A Specification for A New Family of RISC Processors, Second Edition, IBM Corporation (ISBN 1-55860-316-6)
 * PowerPC Microprocessor Family: The Programming Environments, IBM/Motorola (IBM order number MPRPPCFPE-01 or Motorola order number MPCFPE/AD)
 * PowerPC 603 RISC Microprocessor User's Manual, IBM/Motorola (IBM order number MPR603UMU-01 or Motorola order number MPC603UM/AD)
 * Executable and Linking Format (ELF), Tool Interface Standards Committee (Review Draft Version 1.1a)
 * Tool Interface Standards Portable Formats Specification, Tool Interface Standards Committee (Version 1.0)
 * System V Application Binary Interface, Third Edition, UNIX System Laboratories (ISBN 0-13-100439-5)
 * System V Application Binary Interface, PowerPC Processor Supplement, Sun Microsystems (Draft dated March, 1995)
 * Where possible, this ABI has maintained compatibility with System V Application Binary Interface, PowerPC Processor Supplement. Incompatibilities are noted in the document by "System V ABI Note" comments.


 * SOMObjects Developer Toolkit Programmer's Reference Manual, IBM Corporation

Revision Control
This material was compiled from a variety of sources and was edited by BJ Hargrave, IBM Personal Software Products. Comments can by sent to hargrave@austin.ibm.com.

All changes from the previous draft are marked with revision bars. This is the first Release of this document.
 * 1) Release 1 (December 8, 1995 7:31 pm)

Instruction Set
The PowerPC Architecture is defined in PowerPC Architecture, IBM Corporation. PowerPC Architecture describes both the 32-bit and 64-bit portions of the architecture. This ABI document only defines a 32-bit ABI for PowerPC-based operating systems. Also see PowerPC Microprocessor Family: The Programming Environments, IBM/Motorola, for details on a 32-bit implementation of the PowerPC Architecture.

ABI conforming programs containing machine instructions must use the 32-bit PowerPC instruction set including the instruction encodings and semantics as defined by the architecture.

A processor must implement the instruction set of the architecture, perform the operations indicated by the instructions and produce the expected results. No performance constraints are levied by the ABI. A software emulation of the processor architecture could be ABI conforming.


 * Note:The use of PowerPC 601 instructions which are not part of the PowerPC Architecture is not ABI conforming. Programs using these instructions will function on the PowerPC 601 but will not on other PowerPC implementations.

Restricted Instructions
An ABI conforming processor may implement the optional instructions from the PowerPC Architecture as well as instructions not in the architecture. However, programs that use these instructions will not be ABI conforming.

All instructions that are neither privileged nor optional can be assumed to exist and function properly and may be used by ABI conforming programs. However, the following instructions that handle non-scalar data are not ABI conforming and may not be used by ABI conforming programs.

These instructions all generate alignment exceptions when executed in the Little Endian mode of the processor.

Data Representation
The PowerPC Architecture supports the following operand sizes:
 * Note:An "b" indicates that the bit position can contain either 0 or 1.
 * Note:Although not permitted as storage operands by the PowerPC Architecture, quadwords are shown to demonstrate alignment and size.

Byte Ordering
Byte ordering defines how the bytes that make up the larger, multi-byte operands are ordered in memory. Big Endian ordering means that the most significant byte (msb) is located in the lowest addressed byte position in the operand (byte 0). Little Endian ordering means that the least significant byte (lsb) is located in the lowest addressed byte position in the operand (byte 0).

The PowerPC Architecture supports both Big Endian or Little Endian byte ordering. This document defines an ABI based upon the Little Endian byte ordering.

The following figures illustrate the bit and byte numbering within the various size operands. Little Endian byte numbers are in the upper right and Big Endian byte numbers are in the upper left. Bit numbers appear in the lower corners.

Scalar Types - Size and Alignment
This section describes the mapping of C/C++ scalar data types onto the PowerPC Architecture. The Size column indicates the size of the data type in bytes. The Alignment column indicates the preferred alignment for the data type. If the data type is not aligned to the preferred alignment then alignment exceptions may occur when accessing the data from memory. Scalar data types on the PowerPC are aligned on their "natural" boundaries. That is, their preferred alignment is equal to their size.

Aggregates and Unions - Alignment and Padding
Aggregates (structures and arrays) and unions are aligned using the alignment of the most strictly aligned component, i.e. the component with the largest alignment dictates the alignment of the aggregate or union in which it is contained. Each component is assigned the lowest available offset with the appropriate alignment. This may require internal padding, depending on the size of the previous component. The size of on aggregate or union is always a multiple of its alignment. Thus a structure or union may require "tail" padding to meet size and alignment constraints.

The following figures illustrate structure and union member alignment and packing for Little Endian byte ordering. Little Endian byte numbers are in the upper right.

Unaligned Data Access
Since PowerPC processors do not support unaligned data access in Little Endian mode without causing an alignment exception, compiler assistance is necessary to support existing code with poorly aligned data structures. Many legacy applications are from the Intel x86 which is very forgiving of unaligned data. Unaligned data accesses on the Intel x86 chips are penalized only cycles rather than the expensive alignment exceptions of the Little Endian mode of the PowerPC.

One of the key areas of legacy applications is OS/2, an operating system that originated on the Intel x86 architecture. In fact there are numerous system data structures that are not "naturally" aligned. For this reason, compiler support is critical to facilitate the porting of applications to OS/2 for the PowerPC and the sharing of persistent data between both platforms. While this compiler support is not required to produce ABI-compliant code, it is highly recommended. In short, the compiler support involves using multiple instructions to access an unaligned scalar quantity without causing an alignment exception. For example, in Figure 3-8, "Structure with Packing on 1 Byte Boundary", on page 13, member n in the structure is improperly aligned. Assuming that r3 points to the structure and the structure is aligned on a word boundary, the following code example would load the value of n into r4 without causing an alignment exception. Similar techniques can be used to access and update scalars with other misalignments. All multi-byte scalar data types listed in § 3.2, "Scalar Types - Size and Alignment", should be handled. The specific techniques are left to the compiler vendor.

The compiler can ensure that all automatic and global data are "naturally" aligned. The compiler can then determine, at compile time, the specific alignment problems of individual members of an aggregate and generate the appropriate code to avoid alignment exceptions when these members are accessed.

When dealing with pointers, however, the alignment of the data referenced by the pointer is unknown at compile time. Therefore one of the following choices must be made.
 * 1) Code is generated to assemble the data item by accessing only individual bytes. This choice makes no assumptions about the alignment of the data.
 * 2) Code is generated to determine at runtime if the data item being accessed is "naturally" aligned. If the data item is aligned it can be directly accessed. Otherwise it accessed by individual bytes.
 * 3) Code is generated accessing the data item assuming it is naturally aligned. If the data item is unaligned, an alignment exception will be generated and the alignment exception handler will be invoked. The exception handler will then complete the instruction, accessing the data item by individual bytes, and return control to the next instruction. This choice assumes that most pointers will point to naturally aligned data items.

It is recommended that compiler support for unaligned data access be activated by either
 * 1) The use of a structure packing pragma which causes a structure to have members which are not “naturally” aligned or to have the structure’s size not be a multiple of the "natural" alignment of the structure.
 * 2) The use of a new pragma that signifies that a structure may contain unaligned members or a pointer variable may point to unaligned data.

Bit Fields
Structure and unions may have bit fields which define integral objects with a specified number of bits.

UTF-8
UTF-8 is a transformation of Unicode characters such that there are no embedded null bytes in a character string. This allows Unicode character strings to be encoded in a way that they may be used in places that historically only support single-byte character strings which may use the null-byte as a string terminator. UTF-8 encoded character strings are specified in several places in this ABI.

Procedure Linkage Conventions
This chapter defines the standard system function calling convention. It is applicable to both procedural and object-oriented function calls. All system interfaces require this calling convention.


 * Note:The standard system function calling conventions apply only to global functions. Local functions that are not reachable from other compilation units may use other calling conventions.

Registers
The PowerPC Architecture provides 32 General Purpose Registers (GPRs). Each GPR is a word (32-bit) in size and is used for integer and address computations. There are also 32 Floating Point Registers (FPRs). Each FPR is a doubleword (64-bit) in size and is used for floating point computations. There are also other registers with specific purposes. All registers (GPR, FPR and other) are global to all functions in a thread of execution.

This table gives a description of the usage of the PowerPC registers in this ABI.

Stack Frames
In addition to the registers, each function can have a stack frame on the current thread's stack. Register r1 is the stack pointer and points to the current stack frame. A function must acquire a stack frame if the function calls another function or requires any of the optional stack frame components.

Parameter Passing
For the PowerPC Architecture, it is more efficient to pass parameters in registers (GPRs and FPRs) rather than build parameter lists in memory (or on the stack). Since all computations are performed on registers and there are a large number of registers available, it makes sense to pass parameters in registers where they can be used immediately by the called function. The number of parameters that can be directly passed in registers is limited by the register usage definition in the ABI.

Up to eight integer parameters, loaded sequentially in r3 through r10, and eight floating point parameters, loaded sequentially in f1 through f8, can be passed directly in registers. Only those parameter passing registers actually needed in a function call will be loaded with parameter values. The remaining unused parameter passing registers will contain undefined values.

Only when a parameter cannot be passed in a register (more than eight integer or more than eight floating point parameters or the parameter is too large to be passed in a register) must the parameter list area component of the stack frame be allocated. The parameter list area need only be allocated large enough to contain only those parameters not being passed by register. The parameter list area is partitioned into parameter words with the first parameter word (0) being at the low address of the parameter list area immediately adjacent to the stack frame header.

The following algorithm details how parameters are to be passed. For this algorithm, parameters are ordered from left (first parameter) to right and the evaluation order is unspecified. Let gr and fr be the number of the next available GPR and FPR, respectively and param be the address of the next available parameter word. Initialize gr to 3, fr to 1 and param to the address of lowest-addressed word in the parameter list area. For each parameter, proceeding left to right, select its type from the following table and take the indicated action.

Table 4-3: Parameter Passing Types and Actions

Return Values
The following table details how return values are to be handled.

System Object Model (SOM) Binary Interface
IBM's System Object Model (or SOM) provides a language-neutral binary interface for object-oriented (OO) class libraries. A SOM class library is a collection of one or more SOM classes whose functionality is accessible via interface descriptions expressed in OMG’s (Object Management Group, Inc.) Interface Definition Language (IDL). Every SOM class is implemented with a procedure that constructs and registers the class and a set of method procedures that implement the methods defined for the class. A SOM class library may be realized as a dynamically linked library (DLL) on platforms that provide dynamic linking, or a set of object files contained in a static library on platforms that do not. Programmers typically make use of SOM class libraries through language bindings that map the IDL interface descriptions into a particular programming language or through SOM-aware language compilers that produce code directly to the SOM binary interface.

The SOM Kernel is a distinguished class library that contains the SOM kernel classes and implements all of the basic mechanisms and general OO capabilities used in creating and manipulating all other SOM classes and their object instances. Except for the fact that all of the SOM Kernel functions and global variables are also included as part of this library, it is in most other respects no different from any other SOM class library.

All of the OO constructs provided by SOM are ultimately expressed in terms of a small number of function calls and data structures. Some of these are used to construct classes and exercise the method resolution mechanisms (among other things) and hence, in turn, permit the instantiation of objects and the invocation of methods on objects. The remainder of the SOM Kernel is made up of methods supplied with the three built-in classes (SOMObject, SOMClass, and SOMClassMgr). Generally speaking, most of SOM is implemented as methods (in preference to functions), to permit user specialization through normal OO subclassing, but some critical or heavily used constructs are implemented as ordinary functions.

The binary interface to SOM is the substrate upon which the language bindings are built. It consists of The remaining SOM Kernel functions and methods can be invoked and applied using this basic set of mechanisms.
 * Addressing, calling conventions, and register usage.
 * Class library organization.
 * The representation of objects and object references.
 * The data structures used for method resolution and basic operations.
 * The kernel functions used to perform class construction and method resolution.

Some of the functions included in IBM implementations of the SOM Kernel library are provided as a convenience for programmers doing SOM development on IBM platforms. These functions are not required to be available in conforming SOM implementations from other vendors. In this category are functions that provide debugging support and formatted stream output. A list of mandatory and optional kernel functions is given in § 5.8, "SOM Kernel Functions", on page 48.

Consult the SOMObjects Developer Toolkit Programmer’s Reference Manual for more detailed descriptions and specifications of particular kernel functions and methods.

System Object Exception Handling
This chapter will explain the model and interfaces to support system object exception handling. This chapter will be provided in a future release of this document.

Execution Model
This chapter discusses the execution model for programs conforming to this ABI. It also provides code examples demonstrating function tags and how fundamental operations such as function calls and data access can be performed.

Resource File Format
This chapter describes the format of resource files and resource collections. Resources are read-only data with the following usage restrictions. From the application view, resources are high-level language-independent, structured data that are used by applications, but are understood by the operating system. E.g. fonts, bitmaps, icons, dialogs. See OS/2 for an example of an operating system that uses resources.
 * Resources must be attached to valid load modules.
 * Resources can only be accessed via operating system-specific APIs.
 * Resources are only mapped into memory by the operating system-specific APIs.
 * Resource data may have no relocations and no code may have relocations that refer to the resource data.

Resource File
A resource file is a load module format-independent file created by a resource compiler. It can contain many uniquely named resource collections and can be converted in to a form suitable for attachment to a load module. This is typically an object file with one SHT_RES section per resource collection. The static linker will take this object file as input, along with the other object files that contribute to the load module, and place each resource collection in the resultant load module as a PT_RES segment.

Resource Collection
A resource collection is a collection of individual resource items each identified by a unique type and ordinal pair with an optional name (unique within type).

Resource collections are self-contained. All information about the individual resource items are contained within the resource collection. All offsets within a resource collection must be relative to the start of the resource collection. A resource collection includes the resource collection header, the locale information, the resource item array, the resource collection string table and all the resource data.

Resource Item
A resource collection contains an array of resource items, with one resource item for each resource in the collection. A resource item describes the resource and provides a pointer to it's data.

Object and Load Module File Format
This chapter describes the formats of the object files and load module files (including executables and dynamic link libraries) and debugging information for operating systems and development tools conforming to this ABI.

An object file (ET_REL) is the output of a language translator that is suitable for linking with other object files to create a load module. A load module is either an executable or a dynamic link library (also known as a shared library) and is suitable for loading into a process for execution. An executable (ET_EXEC) is a load module that is the basis for the creation of a process. It can be dynamically linked with zero or more dynamic link libraries (ET_DYN) by the system to complete the process image.

ELF
The format of the object and load module files is based upon the ELF specification, version 1. The reader is referred to the Tool Interface Standards Portable Formats Specification and Executable and Linking Format (ELF) for a general specification of the ELF format. (See also chapters 4 and 5 of System V Application Binary Interface.) Book I of Executable and Linking Format (ELF) along with the information in this section describe ELF as required to support this ABI.

ELF Operating System-specific Information
This section documents the non-processor-specific ELF information required for operating systems based upon this ABI. For PowerPC processor-specific information, see § 9.1.2, "ELF PowerPC Processor-specific Information", on page 104.

ELF PowerPC Processor-specific Information
This section documents the ELF information specific to the PowerPC processor.

DWARF
This section defines the information necessary to support the Debug With Arbitrary Record Format (DWARF) debugging information format on the PowerPC architecture. This ABI does not define a debugging information format, but all implementations of DWARF for this ABI shall use the definitions in this section. The reader is referred to Tool Interface Standards Portable Formats Specification for general information on the DWARF debugging information format.

DWARF PowerPC Processor-specific Information
This section documents the DWARF information specific to the PowerPC processor.

Register Numbers
The following register number mappings are specified for the PowerPC User Instruction Set Architecture (UISA) registers.

Object Library File Format
This chapter describes the format of object library files. Object library files are searched by the static linker to resolve undefined symbols. The ABI defines two object library file formats.

The Library File format is the preferred file format.

Archive File Format
This file format is the same as the Archive File format (AR) used in UNIX System V. See System V Application Binary Interface, Chapter 7, for details on the Archive File format.

Library File Format
The Library File format (LIB) is a modification of the AR file format. A LIB file contains only ELF object files.

Process Creation and Dynamic Loading
This chapter contains information about process creation and the initial runtime environment for a newly created process. It also contains information on the Global Offset Table and the Procedure Linkage Table and how they are initialized at process creation.

Process Virtual Address Space
The 4 GB virtual address space of a process is partitioned into four areas. When an executable or dynamic link library is loaded into a process, the various PT_LOAD segments are allocated to specific memory areas. All segments are coerced to the same virtual address in each process that contains the segment image.

Appendix A - Compiler Support Extensions
This appendix contains ABI extensions added to support additional compiler function. This appendix also includes the description of the recently adopted COMDAT extension to ELF.

Links

 * abippc32.pdf