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

{{IBM-Reprint}}
(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.
#Release 1 (December 8, 1995 7:31 pm)<br />This is the first Release of this document.

==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.
{|class="wikitable"
|+Table 2-1: Load/Store String Instructions
!width=20%|Mnemonic||width=40%|Description
|-
|lswiload||string word immediate
|-
|lswxload||string word indexed
|-
|stswistore||string word immediate
|-
|stswxstore||string word indexed
|}
{|class="wikitable"
|+Table 2-2: Load/Store Multiple Instructions
!width=20%|Mnemonic||width=40%|Description
|-
|lmwload||multiple word
|-
|stmwstore||multiple word
|}

==Data Representation==
The PowerPC Architecture supports the following operand sizes:
{|class="wikitable"
|+Table 3-1: Operand types and sizes
!Operand||Length||Addr<sub>28:31</sub>if aligned
|-
|Byte||8 bits||bbbb
|-
|Halfword||16 bits||bbb0
|-
|Word||32 bits||bb00
|-
|Doubleword||64 bits||b000
|-
|Quadword||128 bits||0000
|}
;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.
<code>
 lwz   %r4,12(%r3) ;load bytes 1,2,3 into r4
 lbz   %r5,11(%r3) ;load byte 4 into r5
 slwi  %r4,%r4,8   ;shift bytes 1,2,3 left one byte
 or    %r4,%r4,%r5 ;or all bytes together in r4
</code>
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.
#Code is generated to assemble the data item by accessing only individual bytes. This choice makes no assumptions about the alignment of the data.
#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.
#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
#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.
#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.

==Links==
* [http://archive.org/download/OS2PowerPCBinaryInterface/1995-12-08%20-%20OS2%20APPLICATION%20BINARY%20INTERFACE%20FOR%20POWERPC%20(32-BIT)%20-%20abippc32.pdf abippc32.pdf]

[[Category:IBM Publications]]