This document specifies the application of Open Firmware to a PowerPC Processor, including requirements and practices to support unique firmware specific to a PowerPC Processor. The core requirements and practices specified by Open Firmware must be augmented by processor-specific requirements to form a complete specification for the firmware implementation for a PowerPC Processor. This document establishes such additional requirements pertaining to the processor and the support required by Open Firmware.
Task Group Members
The PowerPC Processor binding team members were the following:
Mitch Bradley, FirmWorks
Jordan Brown, SunSoft
Bob Coffin, IBM
David Kahn, Sun Microsystems, Inc.
John Kingman(editor), IBM
Luan Nguyen, Dr., IBM
Mike Segapeli, IBM
Lilian Walter, FirePower
Trademarks
The following terms, denoted by a registration symbol (\xa8 ) or trademark symbol(\xaa ) on the first occurrence in this publication, are registered trademarks or trademarks of the companies as shown in the list below:
------------------------------------------------------ Trademark Company ------------------------------------------------------ PowerPC International Business Machines Corporation ------------------------------------------------------Revision History
------------------------------------------------------------------------------------------
Revision Date Changes
------------------------------------------------------------------------------------------
1.01 April 18,1995 Included changes from Open Firmware Working Group Meeting
of 01/25/9
1.02 May 5,1995 Applied proposals 222, 223, 252, 253, 254, 258, 260, 261 and
263.
1.03 July 3,1995 Edited IP description in Initial Program State Section.
Applied proposals 255 and 267.
1.4 Aug. 11,1995 Include changes from Open Firmware Working Group Meeting
of 07/19/95.
Add SMP Binding to document. Rearrange Section 1.
Applied Proposals 276, 277, 278.
Removed "Openprom" Section (Moved to Platform Bindings).
Changed name of "64-bit-addressing" property to "64-bit".
1.5 Sept. 14,1995 Fixed bad cross-references. Minor editorial changes.
1.6 Oct. 27,1995 Included changes from Open Firmware Working Group Meeting
of 09/20/95. Fixed errata. Added new ELF Section. Corrected
format of MP Section (CIS Calls).
1.7 Jan. 12,1996 Review Draft. Not formally released.
1.8 Feb. 8,1996 Included changes from Open Firmware Working Group Meeting
of 01/16/96.
Added new section (6.2.2) describing physical address formats
and representations for CPU nodes.
Applied proposal 291.
Changed the two notes in Section 12.2 to regular text since they
both contained requirements.
1.9 Feb. 9,1996 Included changes from Open Firmware Working Group Binding
Committee Meeting review of Revision 1.7 on 01/17/96 and Pro
posal #306. Editor is now John Kingman.
1.10 Mar. 12,1996 Included changes from Open Firmware Working Group Binding
Committee Meeting review of Revision 1.9 DRAFT on 03/05/96
and Proposal #317.
2.0 , (Approved Version) Included changes from the Open Firmware
Working Group Subcommittee review of Revision 1.10 DRAFT
on 06/25/96 and Proposal #363.
------------------------------------------------------------------------------------------
While this document addresses the official PowerPC architecture [2], the name "PowerPC" only requires compliance to Book I. The descriptions that follow, and the relevant sections describing translation features for this binding, assume that the system's PowerPC processor(s) implement the entire set of Books I-III. Some "PowerPC" processors may implement different Book II-III features; such processors may need a variant of this binding describing the differences to the mapping functions, etc.
core, core specification: refers to IEEE Std 1275-1994 Standard for Boot (Initialization, Configuration) Firmware, Core Practices and Requirements
effective address: The 64- or 32-bit address computed by the processor when executing a Storage Access or Branch instruction, or when fetching the next sequential instruction. If address translation is disabled, the real address is the same as the effective address. If address translation is enabled, the real address is determined by, but not necessarily identical to, the effective address.
linkage area: An area within the stack that is reserved for saving certain registers across procedure calls in PowerPC run-time models. This area is reserved by the caller and is allocated above the current stack pointer (%r1).
Open Firmware: The firmware architecture defined by the core specification or, when used as an adjective, a software component compliant with the core specification.
procedure descriptor: a data structure used by some PowerPC run-time models to represent a C "pointer to procedure". The first word of this structure contains the actual address of the procedure.
real address: An address that the processor presents on the processor bus.
Real-Mode: The mode in which all addresses passed between the client and Open Firmware are real addresses.
processor bus: The bus that connects the CPU chip to the system.
segmented address translation: The process whereby an Effective Address (EA) is translated into a Virtual Address (VA) and the virtual address is translated into a Real Address (RA). (See "Segmented Address Translation" on page 9. and Section 4.3 of Book III of [2] for more detail.)
Table of Contents (TOC): A data structure used by some PowerPC run-time models that is used for access to global variables and for inter-module linkage. When a TOC is used, %r2 contains its base address.
virtual address (in IEEE 1275 parlance): the address that a program uses to access a memory location or memory-mapped device register. Depending on the presence or absence of memory mapping hardware in the system, and whether or not that mapping hardware is enabled, a virtual address may or may not be the same as the physical (real) address that appears on an external bus. The IEEE 1275 definition of "virtual address" corresponds to The PowerPC Architecture's definition of "effective addres." Except as noted, this document uses the IEEE 1275 definition of virtual address.
Virtual Address (in PowerPC parlance): An internal address within the PowerPC address translation mechanism, used as in intermediate term in the translation of an effective address to the corresponding real address.
Virtual-Mode: The mode in which Open Firmware and its client share a single virtual address space, and address translation is enabled; all addresses passed between the client and Open Firmware are virtual (translated) addresses.
The required alignment for items accessed with a-addr addresses shall be four-byte aligned (i.e., a multiple of 4).
Each operation involving a qaddr address shall be performed with a single 32-bit access to the addressed location; similarly, each waddr access shall be performed with a single 16-bit access. This implies four-byte alignment for qaddrs and two-byte alignment for waddrs.
The following overview of translation is provided so that the issues relevant to Open Firmware for PowerPC can be discussed. Details that are not relevant to Open Firmware issues (e.g., protection) are not described in detail; the PowerPC architecture [2], particularly Book III, should be consulted for the details. For the scope of this section, terms will be used as defined in [2].
An Effective Address (EA) of a PowerPC processor is 64{32} bits wide. Each EA is translated into an 80{52}-bit Virtual Address (VA) by prepending a 52{24}-bit Virtual Segment Id (VSID) to the 28 LSbs of the effective address. On 32-bit implementations, the VSID is obtained by indexing into a set of 16 Segment Registers (SRs) using the 4 MSbs of the EA. On 64-bit implementations, the VSID is looked up in a Segment Table using the 36 MSbs of the EA. Finally, the virtual address is translated into a Real Address (RA). This is done by mapping the Virtual Page-Number (VPN) (bits 0-67{39} of the VA) into a Real Page Number (RPN) and concatenating this RPN with the byte offset (12 LSbs of the VA). The mapping of VPN to RPN involves a hashing algorithm within a Hashed Page Table (HTAB) to locate a Page Table Entry (PTE) that matches the VPN and using that entry's RPN component. If a valid entry is not found, a Data Storage Interrupt (DSI) or Instruction Storage Interrupt (ISI) is signalled, depending upon the source of the access.
This process is not performed for every translation! Processors will typically have a Translation Look-aside Buffer (TLB) that caches the most recent translations, thus exploiting the natural spatial locality of programs to reduce the overhead of address translation. 64-bit implementations may also implement a Segment Lookaside Buffer (SLB) for the same reasons. On most PowerPC processors, the TLB updates are performed in hardware. However, the architecture allows an implementation to use a software-assisted mechanism to perform the TLB updates. Such schemes must not affect the architected state of the processor unless the translation fails; i.e., the HTAB does not contain a valid PTE for the VA and a DSI/ISI is signalled.
Note: one unusual feature of this translation mechanism is that valid translations might not be found in the HTAB; the HTAB might be too small to contain all of the currently valid translations. This introduces a level of complexity in the use of address translation by Open Firmware, as discussed below.
Block Address Translation is done my matching a number of upper bits of the EA (specified by the BL value) against each of the BAT entries. If a match is found, the corresponding BRPN bits replace the matched bits in the EA to produce the RA.
Block Address Translation takes precedence over Segmented Address Translation; i.e., if a mapping for a storage location is present in both a BAT entry and a Page Table Entry or HTAB, the Block Address Translation will be used.
If the client program has specific requirements for physical memory or address space usage, it may establish requirements for Open Firmware's physical and/or virtual address space usage by means of its program header. When Open Firmware loads the client program, it inspects the program header, and if its current usage of physical memory or virtual address space conflicts with that specified in the program header, Open Firmware shall set the real-base, real-size, virt-base, and virt-size to the configuration variables as specified in the header and restart itself. Real-base, real-size, virt-base, and virt-size may be specified as -1, in which case the firmware is permitted to choose appropriate values for the variables specified as -1.
If the values of the real-size and/or virt-size configuration variables do not provide sufficient memory and/or virtual address space for the firmware's own use, then the firmware shall not attempt to load a client program and the condition should be reported to the user. The possibility of not being able to comply with limitations on firmware's size should be tested as the firmware is coming up in order to handle the possibility that a user established an unworkable limitation on the size. Clients can minimize this exposure by setting size to -1 and allowing Open Firmware to choose the size.
A PowerPC Open Firmware binding shall support two different addressing models, depending upon the setting of the real-mode? Configuration Variable. This variable indicates the Open Firmware addressing mode that a client program expects; false (0) indicates Virtual-Mode, true (-1) indicates Real-Mode; the default value of real-mode? is implementation dependent.
The management of real-mode? is analogous to little-endian?. Open Firmware determines its addressing mode using the value of real-mode?. If the current state of real-mode? (and hence, the current state of Open Firmware) is incorrect, it shall set real-mode? appropriately and reset itself, possibly by executing reset-all.
Memory that cannot be allocated for general purpose use, for example physical memory on PowerPC systems used for interrupt vectors and implementation specific areas, shall not appear in the "available" property of the memory node. A Client Program that needs to use such memory for its architected purpose must not claim that area prior to use.
In the following two sections, some of conventions in Real-Mode and Virtual-Mode address translations are described. Remaining sections describe the assumptions that Open Firmware makes about the state and control of the system in regard to Open Firmware's use of system resources for three Open Firmware interfaces (e.g. Device, User and Client interfaces).
Note: in particular, that the address of the Client interface handler, that is passed to the client, has to be a real address.
The Configuration Variables real-base and real-size should indicate the physical memory base and size in which Open Firmware must locate itself. In Real-Mode, the Configuration Variables virt-base and virt-size do not have meaning and should be set to -1.
The Configuration Variables virt-base and virt-size should indicate the virtual address space base address and size that Open Firmware should use. The Configuration Variables real-base and real-size should indicate the physical memory base and size in which Open Firmware must locate itself.
Note: in Real-Mode, all translations will be virt=real; the primary reason for translation is to allow appropriate I/O accesses.
Note: Since these virtual addresses will be used by the Client and/or User Interfaces (e.g., for pointers to its code, device-tree, etc.), their translations must be preserved until the client OS decides that it no longer requires the services of Open Firmware.
Open Firmware will typically have to maintain its translations in order to perform I/O. Since the client may be running with translation enabled (except for the Client interface call), Open Firmware shall save the state of all relevant translation resources (e.g., SDR1, BATs) and restore them before returning to the client. Likewise, it may take over interrupts for its own use (e.g., for doing "lazy" allocation of BATs); it shall preserve the state of any interrupt vectors for its client.
Since the state of the address translation system is not predictable to any interrupts, the client shall ensure that interrupts are disabled before calling the Client Interface handler and call the handler from only one CPU at a time. The client shall also ensure that other processors do not generate translation exceptions for the duration of the call.
Client programs are not required to assume responsibility for physical memory management. The client program must use the Open Firmware claim client interface service to allocate physical memory while physical memory is managed by Open Firmware. Physical memory shall remain managed by Open Firmware until the client program defines the real-mode physical memory management assist callbacks. Physical memory must be managed by the client program once the client program defines the real-mode physical memory management assist callbacks. Open Firmware shall use the client program's real-mode physical memory management assist callbacks to allocate physical memory after the client program has assumed physical memory management.
In Real-Mode, claim methods shall not allocate more pages than are necessary to satisfy the request.
Note: addresses that the Open Firmware internal use will be those that were established by the Device interface (or, by subsequent actions of the Client or User interface). Thus, the client must preserve these Open Firmware translations if it takes over the virtual memory management function.
In addition to using existing translations, the Client Interface might require the establishment of new translations (e.g., due to map-in calls during open time), or the removal of old translations (e.g., during map-out calls during close time). Since this requires altering the Client's translation resources (e.g., Page Tables), possibly handling spill conditions, Open Firmware can not know how to perform these updates.
Hence, there shall be callback services provided by the client for use by Open Firmware for such actions; see section 8.5.2.
In order to let clients (i.e., target operating systems) know where Open Firmware lives in the address space, the following rules shall be followed by an Open Firmware implementation for PowerPC and by client programs.
Open Firmware:
Client Programs:
Hence, this binding defines callback services that the client provides for use by Open Firmware; see section 8.5.2..
The "cpus" node shall have one child node of device_type "cpu" for each processor.
-----------------------------------------------------
Bit# 33222222 22221111 11111100 00000000
10987654 32109876 54321098 76543210
-----------------------------------------------------
phys.lo cell: 00000000 00000000 00000000 pppppppp
-----------------------------------------------------
where: pppppppp is an 8-bit integer representing the interprocessor interrupt identifier used by the platform.
Conversion of the hexadecimal number from text representation to numeric representation shall be case insensitive, and leading zeros shall be permitted but not required.
Conversion from numeric representation to text representation shall use the lower case forms of the hexadecimal digits in the range a..f, suppressing leading zeros.
prop-encoded-array: Integer constant 1, encoded as with encode-int.
The value of "#address-cells" for the "cpus" node shall be 1.
prop-encoded-array: Integer constant 0, encoded as with encode-int.
The value of "#size-cells" for the "cpus" pseudo-device node is 0 because the processors that are represented by the cpu nodes do not consume any physical address space.
prop-encoded-array: an integer encoded as with encode-int.
For a cpu node, the first and only value of the "reg" property shall be the number of the per-processor interrupt line assigned to the processor represented by the node. For a uni-processor platform, the value of the "reg" property shall be zero.
Note: The 601 PowerPC does not have a timebase frequency, therefore on a 601 PowerPC the value reported in this property shall be 1 billion (1 x 109) which represents the logical rate of the real time clock.
This property, if present, indicates that the PowerPC microprocessor defined by this CPU node is a 64-bit implementation of the PowerPC architecture. The absence of this property indicates that the microprocessor defined by this CPU node is a 32 bit implementation of the PowerPC architecture
This property, if present, indicates that the PowerPC microprocessor defined by this CPU node supports the 64-bit virtual address subset of the 80-bit virtual address as defined by the PowerPC architecture. The absence of this property indicates that the PowerPC microprocessor defined by this CPU node supports the full 80-bit virtual address defined by the PowerPC architecture. This property is only valid for 64-bit implementations.
This property, if present, indicates that the PowerPC microprocessor defined by this CPU node uses the PowerPC 603 defined mechanism to update its Translation Lookaside Buffers (TLBs). The absence of this property indicates that the PowerPC microprocessor defined by this CPU node does not use the PowerPC 603 defined mechanism to update its TLBs.
This property, if present, indicates that the PowerPC microprocessor defined by this CPU node implements the PowerPC 603 defined power management states. The absence of this property indicates that the PowerPC microprocessor defined by this CPU node does not support the PowerPC 603 defined power management states.
This property, if present, indicates that the PowerPC microprocessor defined by this CPU node implements the "Bridge Facilities and Instructions for 64-bit Implementations" as described in an appendix of Book III of [2]. The absence of this property indicates that the PowerPC microprocessor defined by this CPU node does not support these facilities and instructions.
This property, if present, indicates that the PowerPC microprocessor defined by this CPU node implements the emulation assist unit (EAU). The absence of this property indicates that the PowerPC microprocessor defined by this CPU node does not implement the EAU.
This property, if present, indicates that the PowerPC microprocessor defined by this CPU node implements the External Control Facility as described in the "Optional Facilities and Instructions" appendix of Book II of [2]. The absence of his property indicates that the PowerPC microprocessor defined by this CPU node does not support the External Control Facility.
This property, if present, indicates that the PowerPC microprocessor defined by this CPU node implements the floating point instructions fsqrt, fsqrts and stfiwx. The absence of this property indicates that the PowerPC microprocessor defined by this CPU node does not support the floating point instructions fsqrt, fsqrts and stfiwx.
This property, if present, indicates that the PowerPC microprocessor defined by this CPU node implements the floating point instructions fres, frsqrte, and fsel. The absence of this property indicates that the PowerPC microprocessor defined by this CPU node does not support the floating point instructions fres, frsqrte, and fsel.
This property, if present, indicates that the PowerPC microprocessor defined by this CPU node implements the performance monitor functionality. The absence of this property indicates that the PowerPC microprocessor defined by this CPU node does not support this performance monitor functionality.
This property, if present, indicates that the PowerPC microprocessor defined by this CPU node implements the tlbia instruction. The absence of this property indicates that the PowerPC microprocessor defined by this CPU node does not support the tlbia instruction.
Absence of this property indicates that no further levels of cache are present. If present, its value is the phandle of the device node that represents the next level of cache.
Note: If this is a unified cache, the corresponding i- and d- sizes must be equal.
(virt size phys mode )
Each value is encoded as with encode-int.
The following properties define the characteristics of such ancillary caches. These properties shall be contained as a child node of one of the CPU nodes; this is to allow path-name access to the node. All "cpu" nodes that share the same ancillary cache (including the cpu node under which the ancillary cache node is contained) shall contain an "l2-cache" property whose value is the phandle of that ancillary cache node.
Note: The "l2-cache" property shall be used in one level of the cache hierarchy to represent the next level. The device node for a subsequent level shall appear as a child of one of the caches in the hierarchy to allow path-name traversal.
Absence of this property indicates that no further levels of cache are present. If present, its value is the phandle of the device node that represents the cache at the next level.
Note: If this is a unified cache, the corresponding i- and d- sizes must be equal.
The default mode (i.e., the mode specified when the value of the mode argument is -1) for the map-in and modify MMU methods of CPU nodes is defined as follows:
If the beginning of the physical address range affected by the operation refers to system memory, the values for WIMGxPP shall be W=0, I=0, M=0, G=1, PP=10.
If the beginning of the physical address range affected by the operation refers to an I/O address, the values for WIMGxPP shall be W=1, I=1, M=0, G=1, PP=10.
The term "preserved" below shall mean that the register has the same value when returning as it did when the call was made.
Table 1.\x14 Register usage conventions
--------------------------------------------------------------------------------------
Register(s) Value -- real-mode Value -- virt-mode Notes
--------------------------------------------------------------------------------------
msr client interface shall preserve client interface shall not modify
cr client interface shall preserve same as real-mode 1
r1-r2 client interface shall preserve same as real-mode
r3 argument array address on cli same as real-mode 2
ent interface entry
result value (true or false) same as real-mode 2
on client interface return
r13-r31 client interface shall preserve same as real-mode
sprg0- client interface shall preserve client interface shall not modify
sprg3
fpscr client interface shall preserve same as real-mode
f0-f31 client interface shall preserve same as real-mode
lr, undefined same as real-mode
ctr,
xer
sr0-sr15 client interface shall preserve client interface shall not modify
Other SPRs client interface shall preserve same as real-mode 3
--------------------------------------------------------------------------------------
Notes1. Only the non-volatile fields (cr2-cr4) need to be preserved.
2. As defined by section 6.3.1. of [1].
3. Other special purpose registers
The client interface handler shall perform the service specified by the contents of the argument array that begins at the address in r3, place the return value (indicating success or failure of the attempt to invoke the client interface service) back into r3, and return to the client program. This is typically done by a Branch to Link Register (blr).
The client interface handler shall preserve the contents of the Stack Pointer (r1), TOC Pointer (r2), Condition Register (cr) all non-volatile registers (r13-r31) and all special purpose registers except lr, ctr and xer.
The preservation of r2 allows TOC-based client programs to function correctly. Open Firmware shall not depend upon whether its client is TOC-based or not. If the client interface handler, itself, is TOC-based, it must provide for the appropriate initialization of its r2.
Table 2.\x14 Initial Register Values
-----------------------------------------------------------------
Register(s) Value Notes
-----------------------------------------------------------------
msr EE=0, interrupts disabled 1
PR=0, supervisor state
FP=1, floating point enabled
ME=1, machine checks enabled
FE0,FE1=0, floating point exceptions disabled
IP, see section 8.4.
IR,DR, see section 4.2.1.
SF=0, 32-bit mode
ILE,LE, little endian support 2
r1 see section 8.2.2.
r2 0 3
r3 reserved for platform binding 4
r4 reserved for platform binding 4
r5 see section 8.2.3.
r6,r7 see section 8.2.4.
Other 0
user mode
registers
-----------------------------------------------------------------
Notes:1. Open Firmware will typically require the use of external interrupts for its user interface. However, when a client program is invoked, external interrupts shall be disabled. If a client program causes the invocation of the user interface, external interrupts may be re-enabled.
2. The 601 processor uses a different mechanism for controlling the endian-mode of the processor. On the 601, the LE bit is contained in the HID0 register; this bit controls the endian-mode of both program and privileged states.
3. Open Firmware does not make any assumptions about whether a client program is TOC-based or not. It is the responsibility of the client program to set r2 to its TOC, if necessary.
4. As defined in the relevant section of the platform binding.
Note: this address points to the first instruction of the client interface handler, not to a procedure descriptor.
Note: The Open Firmware standard makes no provision for specifying such an array or its contents. Therefore, in the absence of implementation-dependent extensions, a client program executed directly from an Open Firmware implementation will not be passed such an array. However, intermediate boot programs that simulate or propagate the Open Firmware client interface to the programs that they load can provide such an array for their clients.
Note: boot command line arguments, typically consisting of the name of a file to be loaded by a secondary boot program followed by flags selecting various secondary boot and operating system options, are provided to client programs via the "bootargs" and "bootpath" properties of the "/chosen" node.
Note: If firmware makes cachable M=0 data references from different processors on a SMP system, it may have to perform additional cache management to meet this requirement.
In order for Open Firmware to process interrupts in an efficient manner, an area of memory for the exclusive use by Open Firmware shall be reserved by the client program at (real) memory locations 0x1E0\xc9 0x1FF.
Open Firmware shall save and restore the first location of each interrupt that it wants to "take over". I.e., whenever Open Firmware needs the use of an interrupt, it shall save the current contents of the corresponding entry point and replace that location with a branch to its entry point. When Open Firmware returns control, it shall restore the RAM location to its original contents.
If the system is running in Real-Mode, the address of the client callback routine shall be a real address; if it is running in Virtual-Mode, the client callback routine address shall be a mapped virtual address.
alloc-real-mem
map
The following command displays the PowerPC CPU's saved program state.
.registers
prop-encode-array: An integer, encoded as with encode-int, which contains the i-handle of the CPU node that is associated with the "running" CPU.
Client programs shall use the Open firmware start-cpu client interface service to start all processors before it reclaims the Open Firmware memory
On machines in which a machine check on one processor is broadcast to all processors, the processors which are either in the idle or stopped state shall not change their states due to a machine check on another processor: Open Firmware shall not depend on the contents of the low vector (IP=0) in the event of a machine check.
The following State Diagram depicts the relationship of the Running, Stopped and Idle States to each other. The Client Interface Service Calls are shown as how to move between the states.
FIGURE 1 State Diagram
Note: Open Firmware's memory cannot be reclaimed by a client if a CPU is in the "stopped" or "idle" state.
start-cpu
stop-self
idle-self
resume-cpu
Note: The results are undefined if the client program invokes client interface services including breakpoint traps (other than the enter/exit stop-self/idle-self case listed above) simultaneously on more than a single CPU.
Note: Since locking mechanisms are subject to client program policy, the client program is responsible for implementing any necessary mechanism to insure that it adheres to this policy. Further, the client program should disable any pre-emption mechanism before calling a client interface service to avoid rescheduling a thread of execution in the firmware on a different CPU if such a mechanism exists in the client program.