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.

2. References and Terms

2.1. References

This standard shall be used in conjunction with the following publications. When the following standards are superseded by an approved revision, the revision shall apply.

[1]: IEEE Std 1275-1994 Standard for Boot (Initialization, Configuration) Firmware, Core Practices and Requirements.
[2]: PowerPC Architecture, published by Morgan Kaufmann Publishers, Inc. (ISBN 1-55960-316-6). Also available from IBM (Customer Reorder Number 52G7487). Updates to this document are available at http://www.austin.ibm.com/tech/ppc-chg.html

2.2. Terms

This standard uses technical terms as they are defined in the documents cited in "References" on page 7, plus the following terms:

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.

3. Data Formats and Representations

The cell size shall be 32 bits. Number ranges for n, u, and other cell-sized items are consistent with 32-bit, two's-complement number representation.

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.

4. Memory Management

5. Properties

This section describes the standard properties of a PowerPC Open Firmware implementation.

5.1. CPU properties

5.1.1. The Device Tree

Open Firmware requires that the multiple instances of any device that appears more than once in the device tree must be distinguishable by means of their "reg" properties. The "reg" property must express the "address" of each node relative to its parent "bus". Furthermore, the core specification says that the root node of the device tree usually represents the "main physical bus" of the system. Thus, if processors are not directly addressable on the main physical bus, as is expected to be the case on many/most PowerPC-based systems, the CPU nodes on such systems may not be children of the root node but must instead be children of a pseudo-device node. In this case, the name of the pseudo-device node, which will usually be a child of the root node, shall be "cpus".

The "cpus" node shall have one child node of device_type "cpu" for each processor.

5.1.2. Physical Address Formats and Representations for CPU Nodes

5.1.2.1. Numerical Representation

The numerical representation of a processor's "address" in a PowerPC system shall consist of one cell, encoded as follows (Bit# 0 refers to the least significant bit):

======================================================
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.

5.1.2.2. Text Representation

The text representation of a processor's "address" shall be an ASCII hexadecimal number in the range 0...FF.

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.

5.1.2.3. Unit Address Representation

A processor's "unit-number" (i.e. the first component of its "reg" value) is the interprocessor interrupt destination identifier used by the platform. For a uni-processor platform, the "unit-number" shall be zero.

5.1.3. CPUS Node Properties

The following properties shall be created within the "cpus" node.

"#address-cells"

Standard prop-name to define the number of cells required to represent the physical addresses for the "cpu" nodes (i.e., the children of the "cpus" node).

prop-encoded-array: Integer constant 1, encoded as with encode-int.

The value of "#address-cells" for the "cpus" node shall be 1.

"#size-cells"

Standard prop-name to define the number of cells necessary to represent the length of a physical address range.

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.

5.1.4. CPU Node Properties

For each CPU in the system, a cpu-node shall be defined as a child of "cpus." The following properties apply to each of these nodes. The "cpus" node shall not have "reg" or "ranges" properties.

"name"

Open Firmware standard property. The value of the is property shall be of the form: "PowerPC,<name>", where <name> is the name of the processor chip which may be displayed to the user.

"device_type"

Open Firmware standard property. The value of this property for CPU nodes shall be "cpu".

"reg"

Standard prop-name to define a cpu node's unit-address.

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.

"cpu-version"

Standard property, encoded as with encode-int, that represents the processor type. This shall be the value obtained by reading the Processor Version Register of the CPU.

"clock-frequency"

Standard property, encoded as with encode-int, that represents the internal processor speed (in hertz) of this node.

"timebase-frequency"

Standard property, encoded as with encode-int, that represents the rate (in hertz) at which the PowerPC TimeBase and Decrementer registers are updated.

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.

"64-bit"

prop-encoded-array: <none>

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

"603-translation"

prop-encoded-array: <none>

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.

"603-power-management"

prop-encoded-array: <none>

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.

"bus-frequency"

Standard property, encoded as with encode-int, that represents the speed (in hertz) of this processor's bus.

"32-64-bridge"

prop-encoded-array: <none>

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.

"emulation-assist-unit"

prop-encoded-array: <none>

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.

"external-control"

prop-encoded-array: <none>

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.

"general-purpose"

prop-encoded-array: <none>

This property, if present, indicates that the PowerPC microprocessor defined by this CPU node implements the floating point instructions fsqrt and fsqrts. The absence of this property indicates that the PowerPC microprocessor defined by this CPU node does not support the floating point instructions fsqrt and fsqrts.

"reservation-granule-size"

Standard property, encoded as with encode-int, that represents the reservation granule size (i.e., the minimum size of lock variables) supported by this processor, in bytes.

"graphics"

prop-encoded-array: <none>

This property, if present, indicates that the PowerPC microprocessor defined by this CPU node implements the floating point instructions stfiwx, 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 stfiwx, fres, frsqrte, and fsel.

"performance-monitor"

prop-encoded-array: <none>

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.

"tlbia"

prop-encoded-array: <none>

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.

5.1.5. TLB properties

Since the PowerPC architecture defines the MMU as being part of the processor, the properties defined by Section 3.6.5 of [1] and the following MMU-related properties shall be presented under "cpu" nodes.

"tlb-size"

Standard property, encoded as with encode-int, that represents the total number of TLB entries.

"tlb-sets"

Standard property, encoded as with encode-int, that represents the number of associativity sets of the TLB. A value of 1 indicates that the TLB is fully-associative.

"tlb-split"

This property, if present, shall indicate that the TLB has a split organization. The absence of this property shall indicate that the TLB has a unified organization.

"d-tlb-size"

Standard property, encoded as with encode-int, that represents the total number of d-TLB entries.

"d-tlb-sets"

Standard property, encoded as with encode-int, that represents the number of associativity sets of the d-TLB. A value of 1 indicates that the d-TLB is fully-associative.

"i-tlb-size"

Standard property, encoded as with encode-int, that represents the total number of i-TLB entries.

"i-tlb-sets"

Standard property, encoded as with encode-int, that represents the number of associativity sets of the i-TLB. A value of 1 indicates that the i-TLB is fully-associative.

5.1.6. Internal (L1) cache properties

The PowerPC architecture defines a Harvard-style cache architecture; however, unified caches are an implementation option. All of the PowerPC cache instructions act upon a cache "block" (also referred to as a cache "line"). The internal (also referred to as "L1") caches of PowerPC processors are represented in the Open Firmware device tree by the following properties contained under "cpu" nodes.

"cache-unified"

This property, if present, indicates that the internal cache has a unified organization. Absence of this property indicates that the internal caches are implemented as separate instruction and data caches.

"i-cache-size"

Standard property, encoded as with encode-int, that represents the total size (in bytes) of the internal instruction cache.

"i-cache-sets"

Standard property, encoded as with encode-int, that represents number of associativity sets of the internal instruction cache. A value of 1 signifies that the instruction cache is fully associative.

"i-cache-block-size"

Standard property, encoded as with encode-int, that represents the internal instruction cache's block size, in bytes.

"d-cache-size"

Standard property, encoded as with encode-int, that represents the total size (in bytes) of the internal data cache.

"d-cache-sets"

Standard property, encoded as with encode-int, that represents number of associativity sets of the internal data cache. A value of 1 signifies that the data cache is fully associative.

"d-cache-block-size"

Standard property, encoded as with encode-int, that represents the internal (L1) data cache's block size, in bytes.

"l2-cache"

Standard property, encoded as with encode-int, that represents the next level of cache in the memory hierarchy.

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.

"i-cache-line-size"

Standard property, encoded as with encode-int, that represents the internal instruction cache's line size, in bytes, if different than its block size.

"d-cache-line-size"

Standard property, encoded as with encode-int, that represents the internal data cache's line size, in bytes, if different than its block size.

Note: If this is a unified cache, the corresponding i- and d- sizes must be equal.

5.1.7. Memory Management Unit properties

To aid a client in "taking over" the translation mechanism and still interact with Open Firmware (via the client interface), the client needs to know what translations have been established by Open Firmware. The following standard property shall exist within the package to which the "mmu" property of the /chosen package refers.

"translations"

This property, consisting of sets of translations, defines the currently active translations that have been established by Open Firmware (e.g., using map). Each set has the following format:

(virt size phys mode )

Each value is encoded as with encode-int.

5.2. Ancillary (L2,L3...) cache node properties

Some systems might include secondary (L2) or tertiary (L3), etc. cache(s). As with the L1 caches, they can be implemented as either Harvard-style or unified. Unlike the L1 properties, that are contained within the "cpu" nodes, the properties of ancillary caches are contained within other device tree nodes.

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.

"device_type"

Open Firmware Standard property; the device_type of ancillary cache nodes shall be "cache".

"cache-unified"

This property, if present, indicates that the cache at this node has a unified organization. Absence of this property indicates that the caches at this node are implemented as separate instruction and data caches.

"i-cache-size"

Standard property, encoded as with encode-int, that represents the total size (in bytes) of the instruction cache at this node.

"i-cache-sets"

Standard property, encoded as with encode-int, that represents number of associativity sets of the instruction cache at this node. A value of 1 signifies that the instruction cache is fully associative.

"d-cache-size"

Standard property, encoded as with encode-int, that represents the total size (in bytes) of the data cache at this node.

"d-cache-sets"

"l2-cache"

Standard property, encoded as with encode-int, that represents the next level of cache in the memory hierarchy.

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.

"i-cache-line-size"

Standard property, encoded as with encode-int, that represents the internal instruction cache's line size, in bytes, if different than its block size.

"d-cache-line-size"

Standard property, encoded as with encode-int, that represents the internal data cache's line size, in bytes, if different than its block size.

Note: If this is a unified cache, the corresponding i- and d- sizes must be equal.

6. Methods

This section describes the additional standard methods required of a PowerPC Open Firmware implementation.

6.1. MMU related methods

The MMU methods defined by section 3.6.5. of [1] shall be implemented by CPU nodes. The value of the mode parameter for the relevant methods (e.g., map) shall be the value that is contained within PTEs that control Write-through, Cache-Inhibit, Memory-coherent, Guarded and the 2 protection bits; thus, its format is: WIMGxPP, where x is a reserved bit that shall be 0. In order for I/O accesses to be properly performed in a PowerPC system, address ranges that are mapped by map-in shall be marked as Cache-Inhibited, Guarded.

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.

7. Client Interface Requirements

A PowerPC Open Firmware implementation shall implement a client interface (as defined in chapter 6 of [1]) according to the specifications contained within this section.

7.1. Calling Conventions

To invoke a client interface service, a client program constructs a client interface argument array as specified in the core Open Firmware document, places its address in r3 and transfers to the client interface handler, with the return address in lr. (A typical way of accomplishing this is to copy the client interface handler's address into ctr and executing a bctrl.)

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. 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  
            |                                |                                  |      
=======================================================================================

Notes

1. 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.

8. Client Program Requirements

8.1. Load Address

The client's load address is specified by the value of the load-base Configuration Variable. The value of load-base defines the default load address for client programs when using the load method. Load-base shall be a real address in real mode or a virtual address in virtual mode. Note that this address represents the area into which the client program file will be read by load; it does not correspond to the addresses at which the program will be executed. All of physical memory from load-base to either the start of Open Firmware physical memory or the end of physical memory, whichever comes first, shall be available for loading the client program.

8.2. Initial Program State

This section defines the "initial program state", the execution environment that exists when the first machine instruction of a client program of the format specified above begins execution. Many aspects of the "initial program state" are established by init-program, which sets the saved program state so that subsequent execution of go will begin execution of the client program with the specified environment.

8.2.1. Initial Register Values

Upon entry to the client program, the following registers shall contain the following values:

Table 2. 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.

8.2.2. Initial Stack

Client programs shall be invoked with a valid stack pointer (r1) with at least 32K bytes of memory available for stack growth. The stack pointer shall be 16-byte aligned, reserving sufficient room for a linkage area (32 bytes above the address in r1). If the system is executing in Real-Mode, the value in r1 is a real address; if in Virtual-Mode, the address in r1 is a mapped virtual address.

8.2.3. Client Interface Handler Address

When client programs are invoked, r5 shall contain the address of the entry point of the client interface handler. If the system is executing in Real-Mode, the value in r5 is a real address; if in Virtual-Mode, the address in r5 is a mapped virtual address.

Note: this address points to the first instruction of the client interface handler, not to a procedure descriptor.

8.2.4. Client Program Arguments

The calling program may pass to the client an array of bytes of arbitrary content; if this array is present, its address and length shall be passed in registers r6 and r7, respectively. For programs booted directly by Open Firmware, the length of this array is zero. Secondary boot programs may use this argument array to pass information to the programs that they boot.

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.

8.3. Caching

The caches of the processor shall be enabled when the client program is called. The I-cache shall be consistent with the D-cache for all memory areas occupied by the client program. Memory areas allocated on behalf of the client program shall be marked as cacheable. Accesses to "I/O" devices (especially, to devices across "bridges") shall be made with the register access words (e.g., %rl@). All processors in a SMP system shall have the same consistent view of all memory areas (for data references). No more than one processor shall have a modified copy of the same data area in its cache when the client program is called.

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.

8.4. Interrupts

Open Firmware requires that interrupts be "vectored" to its handlers when it is in control of the processor; this will occur when the User Interface is running. Client Interface calls are considered to execute in the environment of the client, and hence, Open Firmware does not assume ownership of interrupts.

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...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.

8.5. Client callbacks

This section defines the callback mechanism that allows Open Firmware to access services exported to it by the client program. As described in section 6.3.2 and the glossary entries for callback and $callback in [1], the callback mechanism follows the same rules as those of Client interface calls. I.e., an argument array is constructed by Open Firmware and the address of that array is passed (via r3) to the client's callback routine; the address of the callback routine is supplied to Open Firmware by means of the set-callback client call.

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.

8.5.1. Real-Mode physical memory management assist callback

Once the control of physical memory is transferred to the client program, Open Firmware which is running in real-mode shall use the callback service provided by the client program to allocate physical memory. Client programs which expect Open Firmware to operate in read-mode must implement the following physical memory management client callback routines for Open Firmware:

alloc-real-mem

IN: [address] min_addr, [address] max_addr, size, mode

OUT: error, [address] real_addr

This routine allocates a contiguous physical memory of size bytes within the address range between min_addr and max_addr. The mode parameter contains the WIMGxPP bits as defined in section 6. A non-zero error code shall be returned if the mapping can not be performed. If error code is zero (i.e. allocation is succeeded) the routine returns the base address of the physical memory allocated for Open Firmware.

8.5.2. Virtual address translation assist callbacks

As mentioned in section 4.2.6., when Open Firmware is in Virtual-Mode, client programs that take over control of the system's memory management must provide a set of callbacks that implement MMU functions. This section defines the input arguments and return values for these callbacks. The notation follows the style used in chapter 6 of the Open Firmware specification [1].

map

IN: [address] phys, [address] virt, size, mode

OUT: throw-code, error

This routine creates system-specific translation information; this will typically include the addition of PTEs to the HTAB. If the mapping is successfully performed, a value of zero shall be placed in the error cell of the argument array; a non-zero error code shall be returned in error if the mapping can not be performed.

unmap

IN: [address] virt, size

OUT: throw-code

The system removes any data structures (e.g., PTEs) for the virtual address range.

translate

IN: [address] virt

OUT: throw-code, error, [address] real, mode

The system attempts to compute the real address (real) to which the virtual address (virt) is mapped. If the translation is successful, a PTE shall be placed into the HTAB for this translation, the number of return cells shall be four with the resulting real address returned in real and error shall be set to false (0). If the translation is not successful, the number of return cells shall be two and error shall be set to a non-zero error code.