systemsoftware
/
Linux-Architecture-Reference
30
1
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
master
papr_2.9+
papr_2.7
lopar-2.9
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'master'
${ noResults }
Linux-Architecture-Reference/LoPAR/app_papr_binding.xml

12243 lines
593 KiB
XML
Raw Permalink Blame History Unescape Escape

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2016, 2020 OpenPOWER Foundation
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<appendix xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xl="http://www.w3.org/1999/xlink"
version="5.0"
xml:lang="en"
xml:id="dbdoclet.50569368_91814">
<title>System Binding</title>
<para>This appendix specifies the application of OF to a PAPR System, including
requirements and practices to support unique hardware and firmware specific to the
platform implementation. The core requirements and practices specified by OF must
be augmented by system-specific requirements to form a complete specification for
the firmware implementation of a PAPR System. This appendix establishes such
additional requirements pertaining to the platform and the support required by OF.</para>
<section>
<title>Overview</title>
<para>This appendix specifies the application of
<emphasis>IEEE Std 1275-1994 Standard for Boot (Initialization,
Configuration) Firmware, Core Practices and Requirements</emphasis>,
<emphasis>Core Errata, IEEE P1275.7</emphasis> and appropriate OF Standards
for LoPAR computer systems, including practices for client program
interface and data formats.</para>
<section>
<title>General Requirements for OF</title>
<para>An OF implementation for an LoPAR platform shall implement the
core requirements as defined in
<xref linkend="dbdoclet.50569387_45524" />, core errata
<xref linkend="dbdoclet.50569387_14175" />, the PA Processor-specific
extensions described in
<xref linkend="dbdoclet.50569374_59715" />, other appropriate bindings
and/or recommended practices contained in the references (see
<xref linkend="dbdoclet.50569387_27251" />), and the LoPAR Binding
specific extensions described in this appendix.</para>
<para>In addition, an OF implementation for an LoPAR platform shall
implement the
<emphasis>Device Interface</emphasis>,
<emphasis>Client Interface</emphasis> and
<emphasis>User Interface</emphasis> as defined in
<xref linkend="dbdoclet.50569387_45524" />.</para>
<para>Some LoPAR Binding property names exceed the OF Base specification
limit of 31 characters. LoPAR OF implementations shall support property
names of at least 47 characters.</para>
</section>
</section>
<xi:include href="sec_papr_binding_terms.xml"/>
<section>
<title>LoPAR Boot Flow</title>
<para>This section gives a system boot process overview and defines the
enhancements to the standard OF boot process that are present in the boot
process for an LoPAR platform.</para>
<section>
<title>Boot Overview</title>
<para>The platform performs a normal OF boot (see
<xref linkend="dbdoclet.50569387_45524" />, as stated in the Core
Practice Document, Section 4.2.3, Start-up script evaluation. LoPAR
platforms provide an additional capability to assist the user in choosing
which of several OSs to boot. A key sequence can be used to interrupt the
normal boot flow and present the user with a
<emphasis>multiboot menu</emphasis>, which can be either graphical or
text-based at the discretion of the platform&#8217;s firmware, from which
the user can choose one of the installed or installable OSs. Presenting
the user with this choice can also be made the default mode of operation
at platform boot time, by means of the
<emphasis role="bold"><literal>auto-boot?</literal></emphasis> and
<emphasis role="bold"><literal>menu?</literal></emphasis> configuration variables.</para>
<para>An overview of a platform boot sequence and the additions of the
<emphasis>multiboot menu</emphasis> are given below:</para>
<informalfigure>
<mediaobject>
<imageobject role="html">
<imagedata fileref="figures/PAPR-60.gif" format="GIF"
scalefit="1" />
</imageobject>
<imageobject role="fo">
<imagedata contentdepth="100%" fileref="figures/PAPR-60.gif"
format="GIF" scalefit="1" width="100%" />
</imageobject>
</mediaobject>
</informalfigure>
<para>The boot flow described above occurs after all of the devices have
been probed (i.e., by the execution of
<emphasis role="bold"><literal>probe-all</literal></emphasis>); see
<xref linkend="dbdoclet.50569368_23032" /> additional requirements for
<emphasis role="bold"><literal>probe-all</literal></emphasis> method.</para>
<para>The boot sequence defaults to a normal boot if the boolean variable
<emphasis role="bold"><literal>auto-boot?</literal></emphasis> is true and
<emphasis role="bold"><literal>diagnostic-mode?</literal></emphasis> is false. In this situation, the
system shall then boot from information contained in the configuration
variables
<emphasis role="bold"><literal>boot-device</literal></emphasis> and
<emphasis role="bold"><literal>boot-file</literal></emphasis>.</para>
<para>From the boot sequence above, entry to the
<emphasis>multiboot menu</emphasis> may occur anywhere after step &#8216;f&#8217;,
<emphasis role="bold"><literal>banner</literal></emphasis>, if the platform key
sequence (<emphasis>multiboot menu</emphasis>) has been depressed or in step
&#8216;i&#8217; if the boolean variable
<emphasis role="bold"><literal>menu?</literal></emphasis> is true.</para>
<section xml:id="dbdoclet.50569368_23032">
<title>Additional Requirements for probe-all Method</title>
<para>Before probing for plug-in devices, OF shall execute the
<emphasis role="bold"><literal>probe</literal></emphasis> method, as with
<emphasis role="bold"><literal>execute-device-method</literal></emphasis>, of any built-in device nodes.
The order of evaluation shall ensure that the
<emphasis role="bold"><literal>probe</literal></emphasis> method of a parent device node is executed
before the
<emphasis role="bold"><literal>probe</literal></emphasis> method of any of its children.</para>
<para>
<emphasis role="bold">Note:</emphasis> During this built-in probing, /rom nodes will
locate ROM based OSs. The FCode for these devices can publish their
<emphasis role="bold"><literal>&#8220;bootinfo&#8221;</literal></emphasis> properties that are used
during the multiboot scenario as described below.</para>
</section>
<section>
<title>LoPAR Multiboot</title>
<para>The boot choices identified to the user are defined by
<emphasis>bootinfo objects</emphasis> hich are located on various system
media. Each
<emphasis>bootinfo object</emphasis> contains information about one OS,
such as its name and description, an icon depicting it, and an OF command
sequence to load and execute it. The locations where
<emphasis>bootinfo objects</emphasis> can be found are specified by OF
<emphasis>device-specifiers</emphasis> that are the values of
configuration variables, the names of which are of the form
<emphasis role="bold"><literal>&#8220;bootinfo-nnnnn&#8221;</literal></emphasis>, where
<emphasis role="bold"><literal>&#8220;nnnnn&#8221;</literal></emphasis> is OS-specific. These
<emphasis>configuration variables</emphasis> are stored in the System
Partition in NVRAM and are published in the
<emphasis>device tree</emphasis> as properties under the
<emphasis role="bold"><literal>/options</literal></emphasis> node. The
<emphasis>multiboot menu</emphasis> will use these
<emphasis>configuration variables</emphasis> to locate and parse
<emphasis>bootinfo</emphasis> to obtain the OS icon, description,
etc.</para>
<para>In addition to the
<emphasis role="bold"><literal>bootinfo-nnnnn</literal></emphasis> configuration variables, the
<emphasis>multiboot menu</emphasis> will search the device tree for nodes
containing
<emphasis role="bold"><literal>&#8220;bootinfo&#8221;</literal></emphasis> properties, which specify that
the node can supply a
<emphasis>bootinfo object</emphasis>. This is particularly useful for OSs
contained in ROMs.</para>
<para>
<emphasis role="bold">Note:</emphasis> The order prescribed by probe-all guarantees
that these properties be created before the
<emphasis>multiboot menu</emphasis> has been invoked.</para>
<para>Different versions of the same OS may each have their own
<emphasis>bootinfo</emphasis> and associated
<emphasis>configuration variables</emphasis>. Although it is possible to
put
<emphasis>bootinfo</emphasis> in any media location that OF can read, this
specification defines standard locations for various types of media, to
allow the firmware to establish the
<emphasis>bootinfo configuration variables</emphasis> automatically in
many cases.</para>
</section>
<section xml:id="dbdoclet.50569368_65183">
<title>Bootinfo Configuration Variables</title>
<para>A
<emphasis>bootinfo configuration variable</emphasis> is any
<emphasis>configuration variable</emphasis> that meets the following
requirements:</para>
<itemizedlist>
<listitem>
<para>Its name is of the form
<emphasis role="bold"><literal>&#8220;bootinfo-nnnnn&#8221;</literal></emphasis>, where
<emphasis>nnnnn</emphasis> is a string of at most 22 characters from the
set of valid characters for OF configuration variable names. The exact
value of
<emphasis role="bold"><literal>&#8220;nnnnn&#8221;</literal></emphasis> for a particular OS may be chosen
by that OS. The naming convention for the OS should be chosen to avoid
possible naming conflicts between OS vendors.</para>
</listitem>
<listitem>
<para>Its value is an OF
<emphasis>device-specifier</emphasis> that identifies an object (e.g. disk
file, tape file, disk partition or
<emphasis role="bold"><literal>/rom</literal></emphasis> child node) whose contents are a
<emphasis role="bold"><literal>&#8220;bootinfo object&#8221;</literal></emphasis> as defined
below.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Bootinfo Properties</title>
<para>Any node in the device tree can have a
<emphasis role="bold"><literal>&#8220;bootinfo&#8221;</literal></emphasis> property whose value specifies
the arguments to use in opening that device in order to access its
<emphasis>bootinfo object</emphasis>.</para>
<para>
<emphasis role="bold"><literal>&#8220;bootinfo&#8221;</literal></emphasis> S</para>
<para>
<emphasis>property name</emphasis> locates the node&#8217;s
<emphasis>bootinfo object</emphasis></para>
<para>
<emphasis>prop-encoded-array</emphasis>: A string, encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis></para>
<para>The presence of this property signifies that the device has an
associated
<emphasis>bootinfo object</emphasis>. The value is a text string such
that when this device&#8217;s node
<emphasis role="bold"><literal>open</literal></emphasis> method is called, the value of text string that
is passed to the device&#8217;s node
<emphasis role="bold"><literal>open</literal></emphasis> method is
<emphasis role="bold"><literal>&#8220;my-args&#8221;</literal></emphasis>. When so opened, subsequent
calls to the node&#8217;s
<emphasis role="bold"><literal>&#8220;read&#8221;</literal></emphasis> method will yield the contents of
the node&#8217;s
<emphasis>bootinfo object</emphasis>.</para>
</section>
<section>
<title>Standard Locations for Bootinfo Objects</title>
<para>The standard locations for
<emphasis>bootinfo objects</emphasis> on various LoPAR media and
partition types is shown in the table below. An OS must put its
<emphasis>bootinfo object</emphasis> in the standard location in order to
guarantee interoperability with the LoPAR
<emphasis>multiboot menu</emphasis> mechanism.</para>
<table frame="all" pgwide="1">
<title>Standard Pathnames for
<emphasis>bootinfo.txt</emphasis> File
</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="33*" />
<colspec colname="c2" colwidth="33*" />
<colspec colname="c3" colwidth="33*" />
<thead>
<row>
<entry align="center">
<para>
<emphasis role="bold">Name</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Device/Partition</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Notes</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<row>
<entry>
<para>Installation Media:</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>Any block device:</para>
</entry>
<entry>
<para>device:partition,\ppc\bootinfo.txt</para>
</entry>
<entry>
<para>Any file system format</para>
</entry>
</row>
<row>
<entry>
<para>Tape:</para>
</entry>
<entry>
<para>device:0 (Note 1)</para>
</entry>
<entry>
<para>Presence of bootinfo.txt is optional</para>
</entry>
</row>
<row>
<entry>
<para>ROM:</para>
</entry>
<entry>
<para>device:bootinfo</para>
</entry>
<entry>
<para>bootinfo is the value of the
<emphasis role="bold"><literal>&#8220;bootinfo&#8221;</literal></emphasis> property in a
<emphasis role="bold">/rom</emphasis> child node</para>
</entry>
</row>
<row>
<entry>
<para>Network:</para>
</entry>
<entry>
<para>Could specify bootinfo.txt or some other file from the
Bootp server</para>
</entry>
<entry>
<para>Specifying bootinfo.txt from the Bootp server is
optional</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>
<emphasis role="bold">Note 1:</emphasis> If bootinfo.txt file is not present, file 0
should contain a program image file for a bootable tape.</para>
<para>Example of installed (
<emphasis role="bold"><literal>&#8220;bootinfo-nnnnn&#8221;</literal></emphasis>) block device
(disk):</para>
<para>ALIAS EXAMPLE:</para>
<para>bootinfo-aix-4.3=disk:2 (The contents of partition 2, which is
probably a &#8220;0x41&#8221; partition, on the default disk, is the
<emphasis>bootinfo.txt</emphasis> file for a version of the AIX
OS.)</para>
<para>bootinfo-nt-4.0=disk:\os\winnt\bootinfo.txt</para>
<para>NON-ALIAS EXAMPLE:</para>
<para>bootinfo-aix-4.4=/pci@ff500000/pci3,1000@10/sd0,0:3 (The contents
of partition 3, which is probably a &#8220;0x41&#8221; partition, on the
SCSI disk at target 0 unit 0, is the
<emphasis>bootinfo.txt</emphasis> file for a version of the AIX
OS.)</para>
</section>
<section xml:id="dbdoclet.50569368_26165">
<title>Bootinfo Objects</title>
<para>The information used by OF to display information in the
<emphasis>multiboot menu</emphasis> and to
locate and process an OS load image is contained
within a sequence of text that is called a
<emphasis>bootinfo object</emphasis>. The text comprising the bootinfo
object uses SGML syntax, as defined in
<xref linkend="dbdoclet.50569387_11453" />, with tags identifying the
subordinate elements.</para>
<para>The following outline is a summary of the organization of the
<emphasis>bootinfo object</emphasis>. Elements at the same level do not
have any required order. The tags are illustrated in upper case, but
shall be processed in a case-insensitive manner.
<programlisting><![CDATA[<CHRP-BOOT>
<DESCRIPTION>
....
</DESCRIPTION>
<OS-NAME>
....
</OS-NAME>
<BOOT-SCRIPT>
....
</BOOT-SCRIPT>
<ICON
SIZE=ww,hh
COLOR-SPACE=r,g,b
>
<BITMAP>
hh hh hh hh . . .
</BITMAP>
</ICON>
</CHRP-BOOT>]]></programlisting></para>
<para>
<emphasis role="bold">Notes:</emphasis>
</para>
<orderedlist>
<listitem>
<para>If &#8216;SIZE&#8217; is not present, assume default of 64,64.
If &#8216;COLOR-SPACE&#8217; is not present, assume default of
3,3,2.</para>
</listitem>
<listitem>
<para>Another <emphasis role="bold"><literal>&lt;chrp-boot&gt;</literal></emphasis> tag sequence could define a different
boot selection</para>
</listitem>
<listitem>
<para>LoPAR platforms will recognize only the tags between the
beginning <emphasis role="bold"><literal>&lt;chrp-boot&gt;</literal></emphasis> tag until the end &lt;/chrp-boot&gt; tag. If
a tag is unrecognized, the material will be ignored until the end tag.
Other non-<emphasis role="bold"><literal>&lt;chrp-boot&gt;</literal></emphasis> tags may be supported in the future. These
additional selections would also be presented to the user as boot
options.</para>
</listitem>
</orderedlist>
<section>
<title>Bootinfo Entities</title>
<para>SGML provides &#8220;entities&#8221; that provide symbolic names
for text. When the entity names are contained within &amp; and
&#8216;;&#8217;, the entity is replaced with text as defined by the
entity; i.e., entities provide a &#8220;macro&#8221; substitution
capability. The
<emphasis>bootinfo object</emphasis> may use entities to supply pathname
components that depend upon the location of the file. Also, entities have
been defined for the standard SMGL Tags for the presence of the
&#8216;&lt;&#8216;, &#8216;&amp;&#8217; and &#8216;&gt;&#8217; characters
in the text as &amp;lt;, &amp;amp; and &amp;gt;. Within the
&lt;BOOT-SCRIPT&gt; element, the following entities are defined with
respect to the fully qualified pathname of the
<emphasis>bootinfo object</emphasis>:</para>
<variablelist>
<varlistentry>
<term>device</term>
<listitem>
<para>the device component.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>partition</term>
<listitem>
<para>the partition component.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>directory</term>
<listitem>
<para>the directory component.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>filename</term>
<listitem>
<para>the filename component.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>full-path</term>
<listitem>
<para>the entire fully qualified pathname.</para>
</listitem>
</varlistentry>
</variablelist>
<para>The fully qualified pathname could be represented by the following
text:
<programlisting><![CDATA[&device;:[&partition;][,]&directory;&filename;]]></programlisting></para>
<para>
<emphasis role="bold">Note:</emphasis> Underlined portions illustrate where entities
are positioned within the full pathname.</para>
</section>
<section>
<title>Bootinfo Character Sets</title>
<para>The character set used by the bootinfo.txt file is ISO-8859-1
(Latin-1). Element tags and entity names are not case sensitive; all
other text is case sensitive.</para>
</section>
<section>
<title>Element Tag Descriptions</title>
<para>The following sections describe each of the element tags and how
they are used.</para>
</section>
<section>
<title>CHRP-BOOT Element</title>
<para>This element provides the grouping for each OS that is represented
within a single bootinfo.txt file. Multiple CHRP-BOOT sections are
allowed within a single bootinfo.txt file.</para>
</section>
<section>
<title>OS-NAME element</title>
<para>This element contains the complete name of the OS.</para>
</section>
<section>
<title>BOOT-SCRIPT element</title>
<para>This element contains an OF script that is executed when the OS
defined by this CHRP-BOOT section is selected to be loaded. Each line of
this element is processed as if it were entered from the input device of
the user interface. Typically, the last line of this script would contain
a
<emphasis role="bold"><literal>boot</literal></emphasis> command; the pathname of the OS&#8217;s load
image can be constructed with the entities described above.</para>
</section>
<section>
<title>ICON element</title>
<para>This element describes the OS icon that can be displayed by the
multi-boot process. The icon should be designed to be pleasant against a
light background.</para>
<para>The SIZE parameter consists of a two decimal numbers, separated by
a comma, that represent the width and height (in pixels) of the icon,
respectively. The default value is &#8220;64,64&#8221;</para>
<para>The COLOR-SPACE parameter consists of three decimal numbers,
separated by commas, that represent the number of bits for the red,
green, and blue components of each pixel. The default value is
&#8220;3,3,2&#8221;<superscript>1</superscript>.</para>
<para>
<emphasis role="bold">Note 1:</emphasis> This version of LoPAR supports only a 3,3,2
icon color-space and 64,64 icon size. Other icon size&#8217;s and
color-space&#8217;s are reserved for future implementations.</para>
<para>If an icon is not stated, the platform will display a generic
system icon that is platform dependent.</para>
<section>
<title>BITMAP element</title>
<para>This element specifies the bitmap. It consists of a sequence of hex
digit pairs, each of which defines a pixel; white spaces is allowed
between pixel values. The number of hex digit pairs is defined by the
product of the width and height values of the SIZE parameter.</para>
<variablelist>
<varlistentry>
<term><emphasis>icon string example:</emphasis></term>
<listitem>
<para><emphasis role="bold"><literal>&lt;icon size=64,64
color-space=3,3,2&gt;&lt;bitmap&gt;hh hh...</literal></emphasis></para>
<para><emphasis role="bold"><literal>hh<superscript>2</superscript>&lt;/bitmap&gt;&lt;/icon&gt;</literal></emphasis></para>
</listitem>
</varlistentry>
</variablelist>
<para>
<emphasis role="bold">Note 2:</emphasis> Hex string would be 8192 characters for a
size=64,64 in the above example.</para>
<para>For the two examples below, the tags have been indented and
separated by line feeds for each start/end tag pair to make a more
readable script style.</para>
<para>
<emphasis role="bold">AIX Bootinfo Object Example:</emphasis>
<programlisting><![CDATA[<chrp-boot>
<description>AIX 4.2.D.0</description>
<os-name>AIX 4.2.D.0</os-name>
<boot-script>boot &device;:2</boot-script>
<icon size=64,64 color-space=3,3,2><bitmap>hh ... hh1</bitmap></icon>
</chrp-boot>]]></programlisting></para>
<para><emphasis role="bold">AIX Diagnostics Bootinfo Object Example:</emphasis>
<programlisting><![CDATA[<chrp-boot>
<description>AIX 4.2.D.0 Diagnostics</description>
<os-name>AIX 4.2.D.0 Diagnostics</os-name>
<boot-script>boot &device;:2 diag</boot-script>
<icon size=64,64 color-space=3,3,2><bitmap>hh ... hh</bitmap></icon>
</chrp-boot>]]></programlisting></para>
<para>
<emphasis role="bold">Note:</emphasis> 64x64 icon size would have 8192 hex string
characters in the "hh ... hh" field above.</para>
</section>
</section>
</section>
<section>
<title>Multiboot Menu</title>
<para>If the boot sequence is interrupted by the multiboot key sequence,
then the firmware shall present a
<emphasis>multiboot menu</emphasis> that provides at least the functions
listed below. The form of the menu (e.g. graphical or text-oriented) and
the selection mechanism (e.g. numbered choices, arrow keys, or mouse) are
platform-dependent.</para>
<para>Multiboot Required Functions:</para>
<itemizedlist>
<listitem>
<para>Locate all bootinfo objects specified by bootinfo configuration
variables and device node
<emphasis role="bold"><literal>&#8220;bootinfo&#8221;</literal></emphasis> properties. For each
<emphasis>bootinfo object</emphasis>, present a choice corresponding to
each valid <emphasis role="bold"><literal>&lt;chrp-boot&gt;</literal></emphasis> section contained therein. For each such
choice, allow the user to either:</para>
<itemizedlist>
<listitem>
<para>Execute the contents of that
<emphasis>bootinfo object&#8217;s</emphasis> <emphasis role="bold"><literal>&lt;boot-script&gt;</literal></emphasis>
element.</para>
</listitem>
<listitem>
<para>Set the
<emphasis role="bold"><literal>boot-command</literal></emphasis> configuration variable to the contents
of that
<emphasis>bootinfo object&#8217;s</emphasis> <emphasis role="bold"><literal>&lt;boot-script&gt;</literal></emphasis>
element.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Present a choice corresponding to each install device, which,
when invoked, will attempt to locate a bootinfo object at the
device&#8217;s standard location (see Table 1).</para>
</listitem>
<listitem>
<para>Allow the user to manage configuration variables</para>
</listitem>
<listitem>
<para>Allow the user to invoke the OF user interface</para>
</listitem>
</itemizedlist>
<para>Additional options that could be implemented would be to provide a
means to get to diagnostics or specific platform options.</para>
<para>There shall be at least one key sequence to enter the multi-boot
platform function for an LoPAR platform.</para>
<para>
<emphasis role="bold">Note:</emphasis> OS have the responsibility to update the NVRAM
System Partition Variable to reflect a change where the
<emphasis>bootinfo.txt</emphasis> file is located; e.g., moving to a
different disk device. Also, the OS is responsible for maintaining the
contents of the
<emphasis>bootinfo.txt</emphasis> file.</para>
</section>
</section>
<section xml:id="dbdoclet.50569368_25080">
<title>Reboot-Command Variable Description</title>
<para>The OS can cause OF to execute a specified sequence of commands at
the next boot by setting the value of the
<emphasis role="bold"><literal>reboot-command</literal></emphasis> configuration variable. LoPAR
firmware implementations shall implement the following configuration
variable.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">reboot-command(-- addr len)</emphasis> [N]</term>
<listitem>
<para>One time or temporary reboot command.</para>
<para>The value of this configuration variable is a string consisting of
zero or more lines of text, with lines separated by either
&lt;return&gt;, &lt;linefeed&gt;, or
&lt;return&gt;&lt;linefeed&gt;.</para>
<para>During firmware start-up, just prior to checking the
<emphasis role="bold"><literal>auto-boot?</literal></emphasis> configuration variable for automatic
booting, the firmware shall check the value of
<emphasis role="bold"><literal>reboot-command</literal></emphasis>. If the value is not the empty
string, the firmware shall save the value to a temporary location, set
<emphasis role="bold"><literal>reboot-command</literal></emphasis> to the empty string, and evaluate the
saved value as though it were a series of user interface command
lines.</para>
<para>If the evaluation of
<emphasis role="bold"><literal>reboot-command</literal></emphasis> returns without executing, the
firmware shall proceed with its normal start-up sequence. In typical
usage, however, the value of
<emphasis role="bold"><literal>reboot-command</literal></emphasis> will include a
<emphasis role="bold"><literal>boot</literal></emphasis> command that starts a client program and does
not return.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
</section>
<section>
<title>LoPAR Processor</title>
<para>OF defines a minimum cell size of 32 bits; therefore, only one cell
is necessary to represent addresses up to 4GB (32 bits). Two cells are
necessary to represent addresses above 4GB and within 64 bits. Also, two
cells are necessary to represent sizes greater than 4GB.</para>
<section>
<title>Processor Endian-ness Support</title>
<para>LoPAR requires the use of PA processors that support Big-Endian
storage format. LoPAR allows for the use of PA processors that support
Little-Endian storage format in addition to Big-Endian storage
format.</para>
</section>
<section>
<title>Multi-Threading Support</title>
<para>The processors used in some platforms support multiple threads of
execution. This processor model differs from Symmetric Multi-Processors
in that the multiple threads of execution share the processor hardware to
such an extent that operations on one thread can significantly affect the
performance of another tread of the same processor. Therefore, the
processor is represented with a single processor node having multiple
interrupt server numbers. The OS is then free to start and stop
multi-threading as the processing environment dictates. The client
interface call
<emphasis role="bold"><literal>start-cpu</literal></emphasis>, operates on the full CPU as presented in
the device tree, upon successful completion, the started CPU is running
in single threaded mode, the active thread being the one associated with
the first interrupt server number in the
<emphasis role="bold"><literal>&#8220;ibm,ppc-interrupt-server#s&#8221;</literal></emphasis> property.
The client interface calls:
<emphasis role="bold"><literal>stop-self, idle-self, resume-cpu</literal></emphasis> are all defined to
operate on the full CPU when called in single threaded mode, the behavior
of these calls if called with multiple threads active is implementation
dependent, it is suggested that the implementation deactivate all but one
thread before performing the call&#8217;s standard function.</para>
</section>
</section>
<section>
<title>OF Platform Extensions</title>
<para>This section defines OF properties, methods, device tree structure
and Client Interface Service requirements for LoPAR platforms.</para>
<para>The naming conventions for IBM unique OF properties and devices are
as follows:</para>
<itemizedlist>
<listitem>
<para>Properties created for use only by IBM compatible implementations
must have the string
<emphasis role="bold"><literal>&#8220;ibm,&#8221;</literal></emphasis> as a prefix to the property
name.</para>
</listitem>
<listitem>
<para>Property names prefixed with the string
<emphasis role="bold"><literal>&#8220;ibm,fw-&#8221;</literal></emphasis> are reserved for and must be
controlled by the Firmware Area.</para>
</listitem>
<listitem>
<para>An IBM property name which does not have the firmware or AIX prefix
must be defined in this document unless documented elsewhere.</para>
</listitem>
<listitem>
<para>The value of a device
<emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis> whether reported through the
compatible property or name property for a device implemented by IBM must
contain the string
<emphasis role="bold"><literal>&#8220;IBM,&#8221;</literal></emphasis> as a prefix unless it conforms to a
binding which specifies otherwise.</para>
</listitem>
</itemizedlist>
<section xml:id="dbdoclet.50569368_13582">
<title>Properties for Dynamic Reconfiguration</title>
<para>The following property, when present, replaces the following four properties:
<emphasis role="bold"><literal>&#8220;ibm,drc-indexes&#8221;</literal></emphasis>,
<emphasis role="bold"><literal>&#8220;ibm,drc-names&#8221;</literal></emphasis>,
<emphasis role="bold"><literal>&#8220;ibm,drc-types&#8221;</literal></emphasis> and
<emphasis role="bold"><literal>&#8220;ibm,drc-power-domains&#8221;</literal></emphasis>.
This property is defined for all dynamically reconfigurable platform nodes.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,drc-info&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> that defines all required DR information in a new format</para>
<para><emphasis>prop-encoded-array</emphasis>: The first element of the array is the number of drc-info entries,
encoded with
<emphasis role="bold"><literal>encode-int</literal></emphasis></para>
<para>The drc-info entry consists of the following elements:</para>
<itemizedlist mark="none">
<listitem>
<para>The <emphasis>drc-type</emphasis> encoded with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.
Examples include “MEM” “PHB” and “CPU”</para>
</listitem>
<listitem>
<para>The <emphasis>drc-name-prefix</emphasis> encoded with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.
Examples include “LMB” “PHB “ “CPU “ and “U8233.E8B.1000C9P-V1-C”</para>
</listitem>
<listitem>
<para>The <emphasis>drc-index-start</emphasis> encoded with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.
The first drc-index of the first entity in the sequence of
entities described by this <emphasis>ibm,drc-info entry</emphasis>.</para>
</listitem>
<listitem>
<para>The <emphasis>drc-name-suffix-start</emphasis> encoded with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.
The integer value that is to be converted to asci and appended to the
drc-name-prefix to create the complete
drc-name of the first entity in the sequence of entities
described by this <emphasis>ibm,drc-info entry</emphasis>.</para>
</listitem>
<listitem>
<para>The <emphasis>number-sequential-elements</emphasis> encoded with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.
The number of sequential entities described by this
<emphasis>ibm,drc-info entry</emphasis>.</para>
</listitem>
<listitem>
<para>The <emphasis>sequential-increment</emphasis> encoded with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.
The number by which to increment the drc-index and the name-suffix
for each sequential entity.</para>
</listitem>
<listitem>
<para>The <emphasis>drc-power-domain</emphasis> encoded with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
</variablelist>
<para>The following properties have been replaced by the
<emphasis role="bold"><literal>&#8220;ibm,drc-info&#8221;</literal></emphasis> but are documented
here for legacy purposes:</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,drc-indexes&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>property name</emphasis> denotes an integer index to be used to
communicate to the firmware what connector is to be operated upon for the
various RTAS calls used for DR.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: An integer encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>, followed by a list of integers also
encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
<para>For each DR connector, a unique integer index is provided which
uniquely identifies the DR connector for purposes of the
<emphasis>ibm,configure-connector</emphasis>,
<emphasis>set-indicator,</emphasis> and
<emphasis>get-sensor</emphasis> RTAS calls. The first element of the array
is the number of connectors associated with the node. The second element
of the array is the index which represents the first connector associated
with the node, the third element the second connector, and so on until
all of the node&#8217;s DR connectors are specified.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,my-drc-index&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>property name</emphasis> denotes an integer index (value of the
entry in the
<emphasis role="bold"><literal>&#8220;ibm,drc-indexes&#8221;</literal></emphasis> property) for the
connector between the node and the node&#8217;s parent.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: An array of integers encoded as
with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,drc-names&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>property name</emphasis> describes the external labeling of the
DR connectors.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: An integer encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>, followed by a list of strings each
encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.</para>
<para>For each DR connector, a unique human-readable name for a
connector. The first element of the array is the number of connectors
associated with the node. The second element of the array is the
human-readable name which represents the first connector associated with
the node, the third element the second connector, and so on until all of
the node&#8217;s DR connectors are specified.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,drc-power-domains&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>property name</emphasis> gives the power domain number for each
connector associated with the node, which is the domain number to be used
in the
<emphasis role="bold"><literal>set-power-level</literal></emphasis> RTAS call, if necessary.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: An integer encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>, followed by a list of integers also
encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
<para>For each DR connector, the power domain which will be controlled
for DR operations (the power domain in which the DRC resides), and which
will be used, if not -1, in the
<emphasis role="bold"><literal>set-power-level</literal></emphasis> RTAS call for the connector. The
power domain number of -1 denotes a live-insertion power domain (in which
case, the
<emphasis role="bold"><literal>set-power-level</literal></emphasis> RTAS call is not used). The first
element of the array is the number of connectors associated with this
node. The second element represents the domain number for the first
connector. The element following this is the domain number for the second
connector, and so on until all of the node&#8217;s DR connectors are
specified.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,drc-types&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>property name</emphasis>, describes the type of each connector
associated with the node, in a human-readable form.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: An integer encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>, followed by a list of strings each
encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.</para>
<para>The first element of the array is the number of connectors
associated with this node. The second element of the array is the
connector type of the first connector associated with the node, the third
element the second connector, and so on until all the node&#8217;s DR
connectors are specified, and these elements will be one of the currently
defined connector types specified in
<xref linkend="dbdoclet.50569368_97022" />.</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569368_97022">
<title>Currently Defined DR Connector Types</title>
<tgroup cols="2">
<colspec colname="c1" colwidth="15*" align="center"/>
<colspec colname="c2" colwidth="85*"/>
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Connector Type(character
string)</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<row>
<entry>
<para>1</para>
</entry>
<entry>
<para>A 32-bit, 5 Volt conventional PCI slot which accommodates
cards that operate up to 33 MHz Only.</para>
</entry>
</row>
<row>
<entry>
<para>2</para>
</entry>
<entry>
<para>A 32-bit, 5 Volt conventional PCI slot which accommodates
cards that operate up to 33 MHz.</para>
</entry>
</row>
<row>
<entry>
<para>3</para>
</entry>
<entry>
<para>A 32-bit, 3.3 Volt conventional PCI slot which
accommodates cards that operate up to 33 MHz Only.</para>
</entry>
</row>
<row>
<entry>
<para>4</para>
</entry>
<entry>
<para>A 64-bit, 5 Volt conventional PCI slot which accommodates
cards that operate up to 33 MHz Only.</para>
</entry>
</row>
<row>
<entry>
<para>5</para>
</entry>
<entry>
<para>A 64-bit, 5 Volt conventional PCI slot which accommodates
cards that operate up to 33 MHz.</para>
</entry>
</row>
<row>
<entry>
<para>6</para>
</entry>
<entry>
<para>A 64-bit, 3.3 Volt conventional PCI slot which
accommodates cards that operate up to 33 MHz Only.</para>
</entry>
</row>
<row>
<entry>
<para>7</para>
</entry>
<entry>
<para>A 32-bit, 3.3 Volt conventional PCI slot which
accommodates cards that operate up to 66 MHz. IOAs that operate
up to 66 MHz will only operate at frequencies above 33 MHz if
there are no 33 MHz IOAs on the same bus.</para>
</entry>
</row>
<row>
<entry>
<para>8</para>
</entry>
<entry>
<para>A 64-bit, 3.3 Volt conventional PCI slot which
accommodates cards that operate up to 66 MHz. IOAs that operate
up to 66 MHz will only operate at frequencies above 33 MHz if
there are no 33 MHz IOAs on the same bus.</para>
</entry>
</row>
<row>
<entry>
<para>9</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
</row>
<row>
<entry>
<para>10</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
</row>
<row>
<entry>
<para>11</para>
</entry>
<entry>
<para>A 32-bit PCI-X capable slot which accommodates cards that
operate up to 66 MHz</para>
</entry>
</row>
<row>
<entry>
<para>12</para>
</entry>
<entry>
<para>A 32-bit PCI-X capable slot which accommodates cards that
operate up to 100 MHz</para>
</entry>
</row>
<row>
<entry>
<para>13</para>
</entry>
<entry>
<para>A 32-bit PCI-X capable slot which accommodates cards that
operate up to 133 MHz</para>
</entry>
</row>
<row>
<entry>
<para>14</para>
</entry>
<entry>
<para>A 64-bit PCI-X capable slot which accommodates cards that
operate up to 66 MHz</para>
</entry>
</row>
<row>
<entry>
<para>15</para>
</entry>
<entry>
<para>A 64-bit PCI-X capable slot which accommodates cards that
operate up to 100 MHz</para>
</entry>
</row>
<row>
<entry>
<para>16</para>
</entry>
<entry>
<para>A 64-bit PCI-X capable slot which accommodates cards that
operate up to 133 MHz</para>
</entry>
</row>
<row>
<entry>
<para>17</para>
</entry>
<entry>
<para>A 64-bit PCI-X capable slot which accommodates cards that
operate up to 266 MHz</para>
</entry>
</row>
<row>
<entry>
<para>18</para>
</entry>
<entry>
<para>A 64-bit PCI-X capable slot which accommodates cards that
operate up to 533 MHz</para>
</entry>
</row>
<row>
<entry>
<para>19</para>
</entry>
<entry>
<para>A PCI Express Rev 1 slot with 1x lanes.</para>
</entry>
</row>
<row>
<entry>
<para>20</para>
</entry>
<entry>
<para>A PCI Express Rev 1 slot with 2x lanes.</para>
</entry>
</row>
<row>
<entry>
<para>21</para>
</entry>
<entry>
<para>A PCI Express Rev 1 slot with 4x lanes.</para>
</entry>
</row>
<row>
<entry>
<para>22</para>
</entry>
<entry>
<para>A PCI Express Rev 1 slot with 8x lanes.</para>
</entry>
</row>
<row>
<entry>
<para>23</para>
</entry>
<entry>
<para>A PCI Express Rev 1 slot with 16x lanes.</para>
</entry>
</row>
<row>
<entry>
<para>24</para>
</entry>
<entry>
<para>A PCI Express Rev 1 slot with 32x lanes.</para>
</entry>
</row>
<row>
<entry>
<para>25</para>
</entry>
<entry>
<para>A PCI Express Rev 2 slot with 1x lanes.</para>
</entry>
</row>
<row>
<entry>
<para>26</para>
</entry>
<entry>
<para>A PCI Express Rev 2 slot with 2x lanes.</para>
</entry>
</row>
<row>
<entry>
<para>27</para>
</entry>
<entry>
<para>A PCI Express Rev 2 slot with 4x lanes.</para>
</entry>
</row>
<row>
<entry>
<para>28</para>
</entry>
<entry>
<para>A PCI Express Rev 2 slot with 8x lanes.</para>
</entry>
</row>
<row>
<entry>
<para>29</para>
</entry>
<entry>
<para>A PCI Express Rev 2 slot with 16x lanes.</para>
</entry>
</row>
<row>
<entry>
<para>30</para>
</entry>
<entry>
<para>A PCI Express Rev 2 slot with 32x lanes.</para>
</entry>
</row>
<row>
<entry>
<para>CPU</para>
</entry>
<entry>
<para>Logical CPU</para>
</entry>
</row>
<row>
<entry>
<para>MEM</para>
</entry>
<entry>
<para>Logical Memory Region</para>
</entry>
</row>
<row>
<entry>
<para>MEM-n</para>
<para>(where n is a</para>
<para>non-zero integer)</para>
</entry>
<entry>
<para>Extended Logical Memory Region(s). Used with the Reserved
Memory option.</para>
</entry>
</row>
<row>
<entry>
<para>PHB</para>
</entry>
<entry>
<para>Logical PCI Host Bridge</para>
</entry>
</row>
<row>
<entry>
<para>SLOT</para>
</entry>
<entry>
<para>Logical I/O slot</para>
</entry>
</row>
<row>
<entry>
<para>PORT</para>
</entry>
<entry>
<para>Logical Port</para>
</entry>
</row>
<row>
<entry>
<para>COPLATFAC</para>
</entry>
<entry>
<para>Coherent Platform Facility</para>
</entry>
</row>
<row>
<entry>
<para>COPLATFUN</para>
</entry>
<entry>
<para>Coherent Platform Function</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,phandle&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>property name</emphasis>, defines the phandle for the
node.</para>
<para>
<emphasis>prop-encode-array</emphasis>: An integer encoded with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section>
<title>OF Root Node</title>
<para>This section defines additional properties and methods associated
with LoPAR platforms that OSs expect to find in the root node. Unit
addresses in an LoPAR system are limited to 60 bits in length
corresponding to the maximum real address supported by the POWER
processor architecture. The unit address of all non-system nodes that are
children of the root node shall have the same value each time the
platform is booted; i.e., shall be invariant for each boot
process.</para>
<para>
<emphasis role="bold">Notes:</emphasis>
</para>
<orderedlist>
<listitem>
<para>This requirement ensures that the PHB would have a stable unit
address. Violations of this rule may require reinstallation of an
OS.</para>
</listitem>
<listitem>
<para>The recommended practice is to generate a virtual unit address
for PHB nodes. This is done by giving a zero length to its first reg
property with an address that is selected such that it remains constant.
In single bridge platforms, the value is chosen based upon historical
precedent of the predecessor product. In multi-enclosure platforms, the
virtual unit address is based upon the manufacturing serial number to
insure uniqueness.</para>
</listitem>
</orderedlist>
<section xml:id="dbdoclet.50569368_54493">
<title>Root Node Properties</title>
<para>This section defines the additional properties or values which
shall be present in the root node unless otherwise specified.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;#address-cells&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis>, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>, that specifies the number of cells
required to represent physical addresses on the processor bus. The value
of
<emphasis role="bold"><literal>&#8220;#address-cells&#8221;</literal></emphasis> for the processor bus
shall be 1 or 2 depending on whether there is any memory addressable at
or above 4GB&#8217;s.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;#size-cells&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis>, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>, that specifies the size of cells
required to represent physical addresses on the processor bus. The value
of
<emphasis role="bold"><literal>&#8220;#size-cells&#8221;</literal></emphasis> for the processor bus shall
be 1 or 2 depending on whether there is any memory addressable at or
above 4GB&#8217;s.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;clock-frequency&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis>, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>, that represents the primary system bus
speed (in hertz).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,extended-clock-frequency&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>property name</emphasis>: Property that represents the primary
system bus speed in hertz of this node. This property allows the encoding
of multi-giga-hertz quantities.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: Consisting of two cells
(freq-hi, freq-lo) each encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>, such that their combined value is
(freq-hi || freq-lo).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;system-id&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis>, encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>, that contains the identification of
the computer system (Reference the
<emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis> property in
<xref linkend="dbdoclet.50569387_45524" />). This string should be unique
across all systems and all manufacturers. An example of an address of
this form is &#8220;0nnnnnnmmmmmm&#8221; where nnnnnn is a sequence of 6
uppercase hexadecimal digits representing a 24-bit value that identifies
manufacturer and mmmmmm is a sequence of 6 uppercase hexadecimal digits
representing a 24-bit binary number assigned by the manufacturer to
assure uniqueness.</para>
<para>
<emphasis role="bold">Note:</emphasis> For platforms with built-in ethernet or other
IEEE 802-style interfaces, the 6-byte MAC address assigned to that
interface meets the requirements and could be used as the
system-id.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;model&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> that is a printable string identifying
the manufacturer and model number of the platform.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: Text string, encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.</para>
<para>The value of this property is a vendor dependent string which
identifies this platform via its manufacturer and model number.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;device_type&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> that is a printable string identifying
the platform as LoPAR Compliant.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: Text string, encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.</para>
<para>The value of this property is a string,
<emphasis role="bold"><literal>&#8220;chrp&#8221;</literal></emphasis> which identifies the platform is
LoPAR Compliant.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,lpar-capable&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>property name</emphasis> indicates that the platform is capable
of supporting logical partitioning and is only present on such systems.
This property is, however, present even if the platform is not currently
configured for logical partition operation.</para>
<para><emphasis>prop-encoded-array</emphasis>: &lt;NULL&gt;</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,converged-loc-codes&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>property name</emphasis> indicates that the platform supports
the &#8220;Converged Location Code&#8221; option. This property shall be
present only on platforms that support the &#8220;Converged Location
Code&#8221; option.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: &lt;NULL&gt;</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,max-boot-devices&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>property name</emphasis> indicates the maximum number of
boot-device entries that the OF automatic boot code will process (entries
after this number are ignored). Platforms that do not present this
property default to process a maximum of 5 entries.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: an integer encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,aix-diagnostics&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>property name</emphasis> indicates that the platform is capable
running AIX diagnostics.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: &lt;NULL&gt;</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,diagnostic-lic&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>property name</emphasis>, presented to partitions authorized to
perform diagnostic operations, that indicates that the platform is
designed to use the specified license internal code package for
diagnostic services.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: one or more encapsulated package
handles encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,io-server-lic&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>property name</emphasis> indicates that the platform is designed
to use the specified license internal code package for I/O
services.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: one or more encapsulated package
handles encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,plat-res-int-priorities&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>property name</emphasis> that designates to the client program
that the platform has reserved one or more interrupt priorities for its
own use.</para>
<para>
<emphasis>prop-encoded-value</emphasis>: one or more (
<emphasis>interrupt priority, range</emphasis>) pairs, where
<emphasis>interrupt priority</emphasis> is a single cell hexidecimal
number between 0x00 and 0xFF, and
<emphasis>range</emphasis> is an integer encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis> that represents the number of contiguous
interrupt priorities that have been reserved by the platform for its
internal use.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,eeh-default&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>property name</emphasis> indicates the platform&#8217;s default
setting for the EEH option.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: An integer encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis> that represents the platform&#8217;s
default setting for the EEH option. The defined states are:</para>
<para>0= The platform boots up with the EEH option disabled.</para>
<para>1= The platform boots up with the EEH option enabled.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,model-class&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> to indicate the platform class.</para>
<para><emphasis>prop-encoded-array</emphasis>: string encoded as defined in
<xref linkend="dbdoclet.50569368_33018" />.</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569368_33018">
<title>Example Encoding Strings</title>
<?dbhtml table-width="50%" ?>
<?dbfo table-width="50%" ?>
<tgroup cols="2">
<colspec colname="c1" colwidth="50*" align="center" />
<colspec colname="c2" colwidth="50*" align="center" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Encoded String</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Platform Class</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<row>
<entry>
<para>C5</para>
</entry>
<entry>
<para>Blade/Entry</para>
</entry>
</row>
<row>
<entry>
<para>D5</para>
</entry>
<entry>
<para>Entry</para>
</entry>
</row>
<row>
<entry>
<para>E5</para>
</entry>
<entry>
<para>Entry</para>
</entry>
</row>
<row>
<entry>
<para>F5</para>
</entry>
<entry>
<para>Mid-range</para>
</entry>
</row>
<row>
<entry>
<para>G5</para>
</entry>
<entry>
<para>High-end</para>
</entry>
</row>
<row>
<entry>
<para>H5</para>
</entry>
<entry>
<para>High-end</para>
</entry>
</row>
<row>
<entry>
<para>P5</para>
</entry>
<entry>
<para>obsolete</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,partition-no&#8221; [S]</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> to define the partition number of this particular
logical partition as established by the Hardware Management
Console.</para>
<para><emphasis>prop-encoded-array</emphasis>: The logical partition number is a one cell
integer encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,partition-name&#8221; [S]</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> to define the partition name of this particular
logical partition as established by the Hardware Management
Console.</para>
<para><emphasis>prop-encoded-array</emphasis>: A NULL terminated string.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,partition-uuid&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>property name</emphasis> specifies a universally unique identifier for this partition.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: A string of data as described below, encoded as with
<emphasis role="bold">encode-string</emphasis></para>
<para>The Universally Unique IDentifier (UUID) option provides each partition with a
Universally Unique Identifier that is persisted by the platform across partition
reboots, reconfigurations, OS reinstalls, partition migration, hibernation etc.
The UUID is a 16 byte string of format fields and random bits as defined in
<xref linkend="dbdoclet.50569332_20419"/>.</para>
<para>The random bits are generated in an implementation-dependent manner to
achieve a projected probability of collision of not greater than one in 2<superscript>60</superscript>.</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_20419">
<title>UUID Format</title>
<tgroup cols="4">
<colspec colname="c1" colwidth="25*" />
<colspec colname="c2" colwidth="25*" />
<colspec colname="c3" colwidth="25*" />
<colspec colname="c4" colwidth="25*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Field</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Byte:Bit</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Size (Bits)</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Values</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<row>
<entry>
<para>Version</para>
</entry>
<entry>
<para>0:0</para>
</entry>
<entry>
<para>1</para>
</entry>
<entry>
<para>0: Initial Version</para>
<para>1: Reserved</para>
</entry>
</row>
<row>
<entry>
<para>Random Bits</para>
</entry>
<entry>
<para>0:1 thru 5:7</para>
</entry>
<entry>
<para>47</para>
</entry>
<entry>
<para>Random Bits</para>
</entry>
</row>
<row>
<entry>
<para>Generation Method</para>
</entry>
<entry>
<para>6:0-3</para>
</entry>
<entry>
<para>4</para>
</entry>
<entry>
<para>0b0000 Never Used</para>
<para>0b0100 Random Generated</para>
<para>All other values are reserved</para>
</entry>
</row>
<row>
<entry>
<para>Random Bits</para>
</entry>
<entry>
<para>6:4 - 7:7</para>
</entry>
<entry>
<para>12</para>
</entry>
<entry>
<para>Random Bits</para>
</entry>
</row>
<row>
<entry>
<para>Variant</para>
</entry>
<entry>
<para>8:0-1</para>
</entry>
<entry>
<para>2</para>
</entry>
<entry>
<para>0b10 DCE Variant UUID</para>
<para>All other values are reserved</para>
</entry>
</row>
<row>
<entry>
<para>Random Bits</para>
</entry>
<entry>
<para>8:2 - 15:7</para>
</entry>
<entry>
<para>62</para>
</entry>
<entry>
<para>Random Bits</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>For the GET_PARTNER_UUID subfunction (See <xref linkend="dbdoclet.50569348_62564"/>), the data is
represented as 16 bytes as described in <xref linkend="dbdoclet.50569332_20419"/>.</para>
<para>For the ibm,partition-uuid property, the data is represented as a string of
hexadecimal characters, with hyphens added for readability.
Hexadecimal values a through f are lower case. An example of the string
representation of the UUID is 648a9ca6-1fb4-4f7e-9436-14d015f3dd74</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,platform-hardware-notification&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>property name</emphasis> indicating to the OS the presence of
hardware for which the OS may need to take action. This property exists
to notify the OS of hardware elements on the platform which may require
special handling by the OS, such as in response to a hardware
errata.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: An integer encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis> followed by a list of strings encoded as
with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.</para>
<para>The first element represents the number of strings to follow in the
property. Each string in the array names a hardware element that may
require the OS to take specific action. The intention is that the string
is to name the hardware element being reported. It is not the intention
to define (or even hint at) the action that the OS must take. It is
expected that some source outside this document will contain a cross
reference between these strings and documentation such as hardware errata
notes which define the action the OS must take.</para>
<para>If the
<emphasis role="bold"><literal>&#8220;ibm,platform-hardware-notification&#8221;</literal></emphasis>
property is provided and a string begins with the &lt;name&gt; field of the
<emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis> (see
<xref linkend="dbdoclet.50569374_59715" />) property in the
<emphasis>CPU</emphasis> nodes followed by an underscore, the characters
following the underscore are a hexadecimal representation of the contents
of a Processor Version Register that the platform may contain.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,fault-behavior&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>property name</emphasis> to define the behavior of the Error Log
indicator relative to FRU faults.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: An integer encoded as with
encode-int that represents how the Error Log indicator should be handled
when a FRU fault is detected.</para>
<para>Property non-existent -- The OS may set FRU Fault and Error Log
indicators for all errors (those it detected and those that the platform
reports to the OS).</para>
<para>Property exists with a value of 1 -- The OS only sets FRU Fault and
Error Log indicators for errors it detects.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,fru-9006-deactivate&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>property name</emphasis> to define whether or not the OS should
deactivate 9006 indicators that it has activated.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: An integer encoded as with
encode-int that represents how the OS should behave relative to FRU Fault
indicator deactivation.</para>
<para>Property non-existent -- The OS is responsible for deactivating FRU
level 9006 indicators that it has activated.</para>
<para>Property exists with a value of 1 -- The OS should not deactivate
FRU level 9006 indicators that it has activated, but is allowed to do so
(firmware does not block). The deactivation of the FRU level 9006
indicators is platform and service procedure dependent.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;compatible&#8221; [S]</literal></emphasis></term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> that conveys the platform architecture
identifiers.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: The concatenation, with
<emphasis role="bold"><literal>encode+</literal></emphasis>, of an arbitrary number of text strings,
each encoded with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.</para>
<para>Specifies a list of platform architectures with which this platform
is compatible. This is used by a client program when it is trying to
determine the appropriate support for this platform. This property shall
include the substring &#8220;LoPAR-&lt;LoPAR
version&gt;-&lt;Manufacturer&gt;-&lt;Manufacturer Version&gt;&#8221;
where &lt;LoPAR version&gt; is the text (without blanks) after the word
&#8220;Version&#8221; on the cover page of the LoPAR specification that
the platform adheres to, &lt;Manufacturer&gt; is a unique string
identifying the manufacturer of the platform (see the OF standard
description of the
<emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis> property for suggestions), and
&lt;Manufacturer_Version&gt; is defined by the manufacturer of the
platform.</para>
<para>
<emphasis role="bold">Note:</emphasis> In order to comply with the OF Standard
description of the
<emphasis role="bold"><literal>&#8220;compatible&#8221;</literal></emphasis> property, implementations
should place the &#8220;LoPAR-&lt;LoPPR
version&gt;-&lt;Manufacturer&gt;-&lt;Manufacturer Version&gt;&#8221;
substring after values that were present in the
<emphasis role="bold"><literal>&#8220;compatible&#8221;</literal></emphasis> property prior to the
inclusion of the &#8220;LoPAR-&lt;LoPAR
version&gt;-&lt;Manufacturer&gt;-&lt;Manufacturer Version&gt;&#8221;
substring.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,max-vios-function-level&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>property name</emphasis> to define the maximum vios function
level that a client shall permit.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: An integer encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis> that represents the maximum VIOS level
that the client shall negotiate. See
<xref linkend="dbdoclet.50569379_75285" /> for the definition of the
values of this property.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,partition-performance-parameters-level&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>property name</emphasis> to define the level of partition
performance parameter reporting supported by the platform.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: An integer encoded as with
encode-int that represents the level of partition performance parameter
reporting supported by the platform (See
<xref linkend="dbdoclet.50569368_69425" />).</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569368_69425">
<title>Level of Partition Performance Parameter Reporting
Supported</title>
<?dbhtml table-width="75%" ?>
<?dbfo table-width="75%" ?>
<tgroup cols="2">
<colspec colname="c1" colwidth="30*" align="center" />
<colspec colname="c2" colwidth="70*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Partition Performance Parameter
Level</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<row>
<entry>
<para>0</para>
</entry>
<entry>
<para>Base Level</para>
</entry>
</row>
<row>
<entry>
<para>1</para>
</entry>
<entry>
<para>Addition of Processor Virtualization Resource Allocations
to H_GET_PPP and Virtualization Processor idle count to
H_PIC</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,preconfigure-usb-kvm&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>property name</emphasis> the presence of which indicates that
the platform requires the operating system to force configuration of the
USB keyboard/mouse nodes during its configuration phase.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: &lt;NULL&gt;</para>
<para>This property, when present in the root node, indicates that the
platform requires the operating system to force pre-configuration of USB
keyboard/mouse nodes internally during its configuration phase. This
property is presented only by platforms with a KVM switch that desire to
force configuration by one or more target operating systems that do not
fully support dynamic addition of USB keyboard and mouse unless the USB
keyboard and mouse are actually seen during the operating system
configuration phase, but may be present even if the KVM switch is not
present when the device tree is inspected. Forced pre-configuration is
needed since the operating system may not actually see the USB keyboard
and mouse during its configuration phase due to the KVM switch that the
platform uses only shows USB keyboard and mouse when those devices are
actually switched to the appropriate KVM switch port.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,enable-ci64-capable&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>property name</emphasis> to define the platform supports the
<emphasis role="bold"><literal>&#8220;ibm,enable-ci64&#8221;</literal></emphasis> method in the Client
Interface.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: None, this is a name only
property.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,migratable-partition&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>property name</emphasis> indicating that the platform supports
the potential migration of this partition.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: &lt;NULL&gt;</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,extended-address&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>
<emphasis>property name</emphasis> indicates this platform supports
Peripheral Memory Spaces, Peripheral I/O Spaces, and SCA spaces above 4
GB.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: &lt;none&gt;</para>
<para>This property must be present.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,ignore-hp-po-fails-for-dlpar&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>property name</emphasis> to define that the OS may ignore
failures of Hot Plug power off and isolate operations during a DLPAR
remove operation. See also Note 2 in
<xref linkend="dbdoclet.50569342_17600" />.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: None, this is a name only
property.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,managed-address-types&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>property name</emphasis> that conveys the platform's supported
types of external addresses that are reprogrammable.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: The concatenation, with
<emphasis role="bold"><literal>encode+</literal></emphasis>, of an arbitrary number of text strings as
described in
<xref linkend="dbdoclet.50569368_71702" />, each encoded with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569368_71702">
<title>Address types supported in
<emphasis role="bold"><literal>&#8220;ibm,managed-address-types&#8221;</literal></emphasis>
property</title>
<?dbhtml table-width="75%" ?>
<?dbfo table-width="75%" ?>
<tgroup cols="2">
<colspec colname="c1" colwidth="40*" align="center" />
<colspec colname="c2" colwidth="60*" align="center" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Text String</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<row>
<entry>
<para>ethernet_mac</para>
</entry>
<entry>
<para>Ethernet MAC address</para>
</entry>
</row>
<row>
<entry>
<para>ethernet_vlan</para>
</entry>
<entry>
<para>Ethernet VLAN ID (for default traffic)</para>
</entry>
</row>
<row>
<entry>
<para>san_wwn</para>
</entry>
<entry>
<para>Fibre Channel World Wide Name (covers both Port &amp;
Node names)</para>
</entry>
</row>
<row>
<entry>
<para>sas_wwid</para>
</entry>
<entry>
<para>SAS IOA's WWID value</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,service-indicator-mode&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>property name</emphasis> indicates in which service indicator
mode the platform is operating.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: an integer encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis> that represents the mode. Defined values
are:</para>
<itemizedlist>
<listitem>
<para>0 = Platform is operating in the Guiding Light mode.</para>
</listitem>
<listitem>
<para>1 = Platform is operating in the Lightpath mode.</para>
</listitem>
</itemizedlist>
<para>
<emphasis role="bold">Implementation Notes:</emphasis>
</para>
<orderedlist>
<listitem>
<para>In the absence of this property, the determination of how the OS
is to behave is made by the platform presenting or not presenting FRU
Fault indicators to the OS see chapter
<xref linkend="dbdoclet.50569347_31867" />. In the case where there are
no FRUs owned by the partition, the OS will not observe any FRU Fault
indicators assigned, even when the platform is operating in the Lightpath
mode.</para>
</listitem>
<listitem>
<para>Presenting this property does not imply any relaxation of the
requirements specified in chapter
<xref linkend="dbdoclet.50569347_31867" />.</para>
</listitem>
</orderedlist>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,guid-partition-table&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>property name</emphasis> indicates that the partition supports disks
with the GUID Partition Table.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: &lt;NULL&gt;</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,linux-le-capable&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>property name</emphasis> indicates that the partition is capable of
supporting boot of Little Endian Linux.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: &lt;NULL&gt;</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="dbdoclet.50569368_10192">
<title>Properties of the Children of Root</title>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,9009-domain&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>property name</emphasis> that defines the index for a 9009 reset
component indicator, and if it exists, the corresponding 9009 sensor, for
the node in which the property exists. Multiple nodes may have the same
index, indicating that they belong to the same reset domain; including
nodes which are not descendents of the node which contains this property.
Descendents of a node containing this property will be in the same reset
domain.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: An integer encoded as with
<emphasis role="bold"><literal>encode-phys</literal></emphasis> that represents the index for the
indicator, and if it exists, for the corresponding sensor.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,associativity&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> to define the associativity domains for this
resource.</para>
<para><emphasis>prop-encoded-array</emphasis>: One or more associativity lists. Each
associativity list consisting of a number of entries integer (N) encoded
as with
<emphasis role="bold"><literal>encode-int</literal></emphasis> followed by N integers encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis> each representing an associativity domain
number.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="dbdoclet.50569368_13649">
<title>Root Node Methods</title>
<para>This section defines methods associated with the platform via
&#8220;/&#8221; (the
<emphasis>root</emphasis> node).</para>
<para>
<emphasis role="bold">Boot Loader Note:</emphasis> The suggested behavior for boot
loader client programs:</para>
<orderedlist>
<listitem>
<para>Check the <emphasis role="bold"><literal>&#8220;ibm,rpa-client-config&#8221;</literal></emphasis>
property to see if
the platform recognized the &#8220;ignore-my-settings&#8221; bit in the
boot loader image i.e. YABOOT for LINUX.</para>
</listitem>
<listitem>
<para>If recognized, check for existence of
<emphasis role="bold"><literal>&#8220;ibm,client-architecture-support&#8221;</literal></emphasis>
and invoke that method with the
<!-- TODO: complete/correct this sentence -->
<emphasis role="bold"><literal>>ibm,???</literal></emphasis> compatible with the Real Base and Real Size constraints of the
kernel being loaded.</para>
</listitem>
<listitem>
<para>If that method did not exist, invoke
&#8220;PROCESS-ELF-HEADER&#8221; from /packages/elf-loader with a
simulated ELF-header that the Linux kernel is compatible with.</para>
</listitem>
</orderedlist>
<para>
<emphasis role="bold"><literal>ibm,client-architecture-support (ibm,architecture.vec --
err?</literal></emphasis>)</para>
<para>This method is called via the call-method
<emphasis>Client Interface Service</emphasis>, prior to starting other
partition processors or threads, to communicate to the platform, via the
<emphasis role="bold"><literal>ibm,architecture.vec</literal></emphasis> structure, the architecture
options that are supported by the client program. Based upon this
knowledge the platform configures itself and the device tree to represent
the most functional programming environment supported by the combination
of the platform, client program and user specified constraints. If
multiple partition processors or threads are active at the time of the
<emphasis role="bold"><literal>ibm,client-architecture-support</literal></emphasis> method call, or an
error is detected in the format of the
<emphasis role="bold"><literal>ibm,architecture.vec</literal></emphasis> structure, the
<emphasis role="bold"><literal>err?</literal></emphasis> boolean shall be
<emphasis>TRUE;</emphasis> else
<emphasis role="bold"><literal>FALSE</literal></emphasis>. The
<emphasis role="bold"><literal>ibm,architecture.vec</literal></emphasis> input parameter is the starting
address of a self defining structure in contiguous memory. Some bits
within the
<emphasis role="bold"><literal>ibm,architecture.vec</literal></emphasis> structure option vectors
represent policies. When set, and an associated condition is detected,
the
<emphasis role="bold"><literal>ibm,client-architecture-support</literal></emphasis> method does not
return and processing continues as with a boot failure of the client
program. The LoPAR architecture options that are selected by this method
are communicated in the value of the
<emphasis role="bold"><literal>&#8220;ibm,architecture-vec-5&#8221;</literal></emphasis> property of the
<emphasis role="bold"><literal>/chosen</literal></emphasis> node.</para>
<para>To ensure the greatest level of interoperability, the client
program should constrain itself to using the set of instructions and
environment specified for first level interrupt handlers, see Book III of
the
<xref linkend="dbdoclet.50569387_99718" />, while not attempting access
to potentially optional SPRs or the MSR prior to invoking the
<emphasis role="bold"><literal>ibm,client-architecture-support</literal></emphasis> root node
method.</para>
<para>
<emphasis role="bold">Architecture and Implementation Notes:</emphasis>
</para>
<itemizedlist>
<listitem>
<para>Most of the
<emphasis role="bold"><literal>IBM,RPA-Client-Config</literal></emphasis> ELF header functionality is
subsumed by the
<emphasis role="bold"><literal>ibm,client-architecture-support</literal></emphasis> root method. However,
the
<emphasis role="bold"><literal>ibm,client-architecture-support</literal></emphasis> root method does not
support the functionality specified through the ns.min-load field of the
<emphasis role="bold"><literal>IBM,RPA-Client-Config</literal></emphasis> ELF header. Supporting firmware
implementations are prepared to move themselves out of the way when
loading client programs.</para>
</listitem>
<listitem>
<para>When booting a client program, firmware processes an
<emphasis>IBM,RPA-Client-Config</emphasis> ELF header if present; a
subsequent call of the
<emphasis role="bold"><literal>ibm,client-architecture-support</literal></emphasis> root method with
conflicting values in the
<emphasis role="bold"><literal>ibm,architecture.vec</literal></emphasis> structure, overrides the
configuration variables set by the ELF header.</para>
</listitem>
</itemizedlist>
<para>
<emphasis role="bold"><literal>Formal definition of ibm,architecture.vec:</literal></emphasis>
</para>
<para>
<emphasis role="bold"><literal>ibm,architecture.vec =</literal></emphasis> a
<emphasis role="bold"><literal>PVR-list</literal></emphasis>:
<emphasis role="bold"><literal>Number-of-option-vectors</literal></emphasis>:
<emphasis role="bold"><literal>option-vectors</literal></emphasis>[Number-of-option-vectors + 1]</para>
<para>
<emphasis role="bold"><literal>PVR-list</literal></emphasis> =
<emphasis role="bold"><literal>Terminator-list-entry</literal></emphasis> |
<emphasis role="bold"><literal>Non-terminator-list: Terminator-list-entry</literal></emphasis></para>
<para>
<emphasis role="bold"><literal>Non-terminator-list = Non-terminal-list-entry |
Non-terminal-list-entry : Non-terminator-list</literal></emphasis>
</para>
<para>
<emphasis role="bold"><literal>List-entry</literal></emphasis> =
<emphasis role="bold"><literal>4-byte-mask</literal></emphasis>:
<emphasis role="bold"><literal>4-byte-PVR-value</literal></emphasis></para>
<para>
<emphasis role="bold"><literal>Terminator-list-entry</literal></emphasis> =
<emphasis role="bold"><literal>List-entry</literal></emphasis> such that !
<emphasis role="bold"><literal>4-byte-mask</literal></emphasis> &amp;
<emphasis role="bold"><literal>4-byte-PVR-value != 0x00000000</literal></emphasis></para>
<para>
<emphasis role="bold"><literal>Non-terminator-list-entry = List-entry</literal></emphasis> such that !
<emphasis role="bold"><literal>4-byte-mask &amp; 4-byte-PVR-value ==
0x00000000</literal></emphasis></para>
<para>
<emphasis role="bold"><literal>Number-of-option-vectors =</literal></emphasis> The number of option
vectors is n+1 where n is the numeric value of the byte (byte value of
0x00 represents one option vector)</para>
<para>
<emphasis role="bold"><literal>option-vector</literal></emphasis> (option-vectors number 1-255): 1 byte
length of the option vector where the number of bytes in the option
vector (including the first byte of length) is n+2 where n is the numeric
value of the byte (byte value of 0x00 represents a two byte option vector
-- one length byte and one bit-vector byte) followed by 1-256 bytes of
<emphasis role="bold"><literal>bit-vector</literal></emphasis>.</para>
<para>
<emphasis role="bold"><literal>option-vector</literal></emphasis> (option-vector number 256): is special
in that it is reserved for expansion. The first byte is again the number
of option vectors in the vector expansion (see definition of
<emphasis role="bold"><literal>Number-of-option-vectors</literal></emphasis> above). This is followed by
1-255
<emphasis role="bold"><literal>option-vectors</literal></emphasis> (see definition above) and potentially
a 256th
<emphasis role="bold"><literal>option-vector</literal></emphasis> which is again an expansion option
vector, and so on.</para>
<para>
<emphasis role="bold"><literal>bit-vector</literal></emphasis>: The structure of a bit vector is vector
specific, in general support for most options are indicated by setting a
specific bit to a 1, see
<xref linkend="dbdoclet.50569368_10077" />.</para>
<para>The
<emphasis role="bold"><literal>PVR-list</literal></emphasis> of the
<emphasis role="bold"><literal>ibm,architecture.vec</literal></emphasis> structure is processed for the
PVR value of each processor that the client program may be exposed to
until either a
<emphasis role="bold"><literal>List-entry</literal></emphasis> allows the process to continue, or the
<emphasis role="bold"><literal>Terminator-list-entry</literal></emphasis> has been processed. If no
<emphasis role="bold"><literal>List-entry</literal></emphasis> allows the process to continue, then the
<emphasis role="bold"><literal>ibm,client-architecture-support</literal></emphasis> method terminates
partition operation as with a boot failure. A
<emphasis role="bold"><literal>List-entry</literal></emphasis> allows the process to continue if either
of the two following conditions hold.</para>
<orderedlist>
<listitem>
<para>(Processor-PVR-value &amp;
<emphasis role="bold"><literal>List-entry[4-byte-mask]) == (List-entry[4-byte-PVR-value] &amp;
List-entry[4-byte-mask])</literal></emphasis> /*The client program explicitly
supports the processor implementation */</para>
</listitem>
<listitem>
<para>If (the processor requires no client support for errata)
&amp;&amp;
<emphasis role="bold"><literal>(Logical-Processor-PVR-value &amp; List-entry[4-byte-mask]) ==
(List-entry[4-byte-PVR-value] &amp; List-entry[4-byte-mask])</literal></emphasis> /*
Client program specifies support for this level of architecturally
compliant processors */</para>
</listitem>
</orderedlist>
<para>
<emphasis role="bold"><literal>List-entry</literal></emphasis> values of special interest (these are
<emphasis role="bold"><literal>Terminator-list-entry</literal></emphasis> values):</para>
<itemizedlist>
<listitem>
<para>0x00000000 0xFFFFFFFF Single entry list that matches any PVR
value</para>
</listitem>
<listitem>
<para>0xFF000000 0x0FFFFFFF Single entry list that matches all
architecturally compliant processors.</para>
</listitem>
</itemizedlist>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569368_10077">
<title>ibm,architecture.vec option vectors</title>
<tgroup cols="5">
<colspec colname="c1" colwidth="10*" align="center" />
<colspec colname="c2" colwidth="10*" align="center" />
<colspec colname="c3" colwidth="10*" align="center" />
<colspec colname="c4" colwidth="10*" align="center" />
<colspec colname="c5" colwidth="60*" align="center" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Option Array</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Option Vector</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Byte Number</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Bit Number</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<row>
<entry morerows="18">
<para>Base</para>
</entry>
<entry morerows="18">
<para>1</para>
<para>PowerPC Server Processor Architecture Level 6</para>
</entry>
<entry morerows="7">
<para>1</para>
</entry>
<entry>
<para>0</para>
</entry>
<entry>
<para>Ignore<superscript><xref linkend="note.ignore" xrefstyle="select: nopage" /></superscript></para>
</entry>
</row>
<row>
<entry>
<para>1</para>
</entry>
<entry>
<para>Cessation Policy<superscript><xref linkend="note.cessation" xrefstyle="select: nopage" /></superscript></para>
</entry>
</row>
<row>
<entry>
<para>2</para>
</entry>
<entry morerows="5">
<para>Reserved for Expansion (0b0)</para>
</entry>
</row>
<row>
<entry>
<para>3</para>
</entry>
</row>
<row>
<entry>
<para>4</para>
</entry>
</row>
<row>
<entry>
<para>5</para>
</entry>
</row>
<row>
<entry>
<para>6</para>
</entry>
</row>
<row>
<entry>
<para>7</para>
</entry>
</row>
<row>
<entry morerows="7">
<para>2</para>
</entry>
<entry>
<para>0</para>
</entry>
<entry>
<para>2.00</para>
</entry>
</row>
<row>
<entry>
<para>1</para>
</entry>
<entry>
<para>2.01</para>
</entry>
</row>
<row>
<entry>
<para>2</para>
</entry>
<entry>
<para>2.02</para>
</entry>
</row>
<row>
<entry>
<para>3</para>
</entry>
<entry>
<para>2.03</para>
</entry>
</row>
<row>
<entry>
<para>4</para>
</entry>
<entry>
<para>2.04</para>
</entry>
</row>
<row>
<entry>
<para>5</para>
</entry>
<entry>
<para>2.05</para>
</entry>
</row>
<row>
<entry>
<para>6</para>
</entry>
<entry>
<para>2.06</para>
</entry>
</row>
<row>
<entry>
<para>7</para>
</entry>
<entry>
<para>2.07</para>
</entry>
</row>
<row>
<entry morerows="1">
<para>3</para>
</entry>
<entry>
<para>0</para>
</entry>
<entry>
<para>2.08</para>
</entry>
</row>
<row>
<entry>
<para>1-7</para>
</entry>
<entry>
<para>Reserved for Expansion (0b0)</para>
</entry>
</row>
<row>
<entry>
<para>4-256</para>
</entry>
<entry nameend="c5" namest="c4">
<para>Reserved for Expansion</para>
</entry>
</row>
<row>
<entry morerows="18">
<para>Base</para>
</entry>
<entry morerows="18">
<para>2</para>
<para>Open Firmware</para>
</entry>
<entry morerows="7">
<para>1</para>
</entry>
<entry>
<para>0</para>
</entry>
<entry>
<para>Ignore<superscript><xref linkend="note.ignore" xrefstyle="select: nopage" /></superscript></para>
</entry>
</row>
<row>
<entry>
<para>1</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
</row>
<row>
<entry>
<para>2</para>
</entry>
<entry>
<para>real-mode</para>
</entry>
</row>
<row>
<entry>
<para>3</para>
</entry>
<entry morerows="4">
<para>Reserved for Expansion (0b0)</para>
</entry>
</row>
<row>
<entry>
<para>4</para>
</entry>
</row>
<row>
<entry>
<para>5</para>
</entry>
</row>
<row>
<entry>
<para>6</para>
</entry>
</row>
<row>
<entry>
<para>7</para>
</entry>
</row>
<row>
<entry>
<para>2-3</para>
</entry>
<entry>
<para>0-15</para>
</entry>
<entry>
<para>Reserved for Expansion (0x0000)</para>
</entry>
</row>
<row>
<entry>
<para>4-7</para>
<para>real-base</para>
</entry>
<entry>
<para>0-31</para>
</entry>
<entry>
<para>OF real starting address or -1 for platform
default</para>
</entry>
</row>
<row>
<entry>
<para>8-11</para>
<para>real-size</para>
</entry>
<entry>
<para>0-31</para>
</entry>
<entry>
<para>Maximum OF size or -1 for platform default</para>
</entry>
</row>
<row>
<entry>
<para>12-15</para>
<para>virt-base</para>
</entry>
<entry>
<para>0-31</para>
</entry>
<entry>
<para>OF starting virtual address or -1 for platform default
(valid for real-mode = 0)</para>
</entry>
</row>
<row>
<entry>
<para>16-19</para>
<para>virt-size</para>
</entry>
<entry>
<para>0-31</para>
</entry>
<entry>
<para>Maximum OF virtual size or -1 for platform default (valid
for real-mode = 0)</para>
</entry>
</row>
<row>
<entry>
<para>20-23</para>
<para>load-base</para>
</entry>
<entry>
<para>0-31</para>
</entry>
<entry>
<para>Starting address of the client program load or -1 for
platform default</para>
</entry>
</row>
<row>
<entry>
<para>24-27</para>
<para>min-rma-size</para>
</entry>
<entry>
<para>0-31</para>
</entry>
<entry>
<para>Minimum size of RMA in MB<superscript><xref linkend="dbdoclet.50569368_24293" xrefstyle="select: nopage" /></superscript></para>
<para>(total bytes = N*(2**20))</para>
</entry>
</row>
<row>
<entry>
<para>28-31</para>
<para>min-load</para>
</entry>
<entry>
<para>0-31</para>
</entry>
<entry>
<para>Minimum client code to load at load-base or -1 for full
client program at load base</para>
</entry>
</row>
<row>
<entry>
<para>32</para>
<para>min-rma%</para>
</entry>
<entry>
<para>0-8</para>
</entry>
<entry>
<para>RMA size =&gt; M% * Partition_memory_size where M is the
value of this 8 bit field<superscript><xref linkend="dbdoclet.50569368_24293" xrefstyle="select: nopage" /></superscript></para>
</entry>
</row>
<row>
<entry>
<para>33</para>
<para>max-pft-size</para>
</entry>
<entry>
<para>0-8</para>
</entry>
<entry>
<para>The maximum size of the hash page table as 2**n
17&lt;n&lt;46</para>
</entry>
</row>
<row>
<entry>
<para>34-256</para>
</entry>
<entry>
<para>Reserved for Expansion</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry morerows="16">
<para>Base</para>
</entry>
<entry morerows="16">
<para>3</para>
<para>IBM PowerPC Server Processor Options<superscript><xref linkend="note.opt6" xrefstyle="select: nopage" /></superscript></para>
</entry>
<entry morerows="7">
<para>1</para>
</entry>
<entry>
<para>0</para>
</entry>
<entry>
<para>Ignore<superscript><xref linkend="note.ignore" xrefstyle="select: nopage" /></superscript></para>
</entry>
</row>
<row>
<entry>
<para>1</para>
</entry>
<entry>
<para>Cessation Policy<superscript><xref linkend="note.cessation" xrefstyle="select: nopage" /></superscript></para>
</entry>
</row>
<row>
<entry>
<para>2</para>
</entry>
<entry morerows="5">
<para>Reserved for Expansion (0b0)</para>
</entry>
</row>
<row>
<entry>
<para>3</para>
</entry>
</row>
<row>
<entry>
<para>4</para>
</entry>
</row>
<row>
<entry>
<para>5</para>
</entry>
</row>
<row>
<entry>
<para>6</para>
</entry>
</row>
<row>
<entry>
<para>7</para>
</entry>
</row>
<row>
<entry morerows="7">
<para>2</para>
</entry>
<entry>
<para>0</para>
</entry>
<entry>
<para>Floating Point</para>
</entry>
</row>
<row>
<entry>
<para>1</para>
</entry>
<entry>
<para>VMX</para>
</entry>
</row>
<row>
<entry>
<para>2</para>
</entry>
<entry>
<para>Decimal Floating Point</para>
</entry>
</row>
<row>
<entry>
<para>3</para>
</entry>
<entry>
<para>Decimal Floating Point Facility (The value of the ibm,dfp
property indicates the architecture level of the
facility.)</para>
</entry>
</row>
<row>
<entry>
<para>4</para>
</entry>
<entry morerows="3">
<para>Reserved for Expansion (0b0)</para>
</entry>
</row>
<row>
<entry>
<para>5</para>
</entry>
</row>
<row>
<entry>
<para>6</para>
</entry>
</row>
<row>
<entry>
<para>7</para>
</entry>
</row>
<row>
<entry>
<para>3-256</para>
</entry>
<entry nameend="c5" namest="c4">
<para>Reserved for Expansion</para>
</entry>
</row>
<row>
<entry morerows="9">
<para>Base</para>
</entry>
<entry morerows="9">
<para>4</para>
<para>LoPAR Implementation</para>
</entry>
<entry morerows="7">
<para>1</para>
</entry>
<entry>
<para>0</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
<row>
<entry>
<para>1</para>
</entry>
<entry>
<para>Cessation Policy<superscript><xref linkend="note.cessation" xrefstyle="select: nopage" /></superscript></para>
</entry>
</row>
<row>
<entry>
<para>2</para>
</entry>
<entry>
<para>ibm,change-msi busy: If set, the client program supports RTAS
ibm,change-msi returning a -2 (Call again) or 990x (Extended delay)</para>
</entry>
</row>
<row>
<entry>
<para>3</para>
</entry>
<entry morerows="4">
<para>Reserved for Expansion (0b0)</para>
</entry>
</row>
<row>
<entry>
<para>4</para>
</entry>
</row>
<row>
<entry>
<para>5</para>
</entry>
</row>
<row>
<entry>
<para>6</para>
</entry>
</row>
<row>
<entry>
<para>7</para>
</entry>
</row>
<row>
<entry>
<para>2</para>
</entry>
<entry>
<para>0-7</para>
</entry>
<entry>
<para>Minimum VP entitled capacity percentage * 100 (if absent
assume 10%)</para>
</entry>
</row>
<row>
<entry>
<para>2-256</para>
</entry>
<entry nameend="c5" namest="c4">
<para>Reserved for Expansion</para>
</entry>
</row>
<row>
<entry morerows="18">
<para>Base</para>
</entry>
<entry morerows="18">
<para>5</para>
<para>LoPAR or OF Options<superscript><xref linkend="note.opt5" xrefstyle="select: nopage" /></superscript></para>
</entry>
<entry morerows="7">
<para>1</para>
</entry>
<entry>
<para>0</para>
</entry>
<entry>
<para>Ignore<superscript><xref linkend="note.ignore" xrefstyle="select: nopage" /></superscript></para>
</entry>
</row>
<row>
<entry>
<para>1</para>
</entry>
<entry>
<para>Cessation Policy<superscript><xref linkend="note.cessation" xrefstyle="select: nopage" /></superscript></para>
</entry>
</row>
<row>
<entry>
<para>2</para>
</entry>
<entry>
<para>64 bit PE TCEs : If set, the client program supports <emphasis>ibm,query-pe-dma-window</emphasis>
returning a 64-bit value for PE TCEs</para>
</entry>
</row>
<row>
<entry>
<para>3</para>
</entry>
<entry morerows="4">
<para>Reserved for Expansion (0b0)</para>
</entry>
</row>
<row>
<entry>
<para>4</para>
</entry>
</row>
<row>
<entry>
<para>5</para>
</entry>
</row>
<row>
<entry>
<para>6</para>
</entry>
</row>
<row>
<entry>
<para>7</para>
</entry>
</row>
<row>
<entry morerows="7">
<para>2</para>
</entry>
<entry>
<para>0</para>
</entry>
<entry>
<para>Logical Partitioning: If set the client program supports
logical partitioning and associated hcall()s; else the client
program shall be run with the hypervisor bit on.<superscript><xref linkend="note.hypervisor" xrefstyle="select: nopage" /></superscript></para>
</entry>
</row>
<row>
<entry>
<para>1</para>
</entry>
<entry>
<para>Shared Processor Logical Partitioning: If set the client
program supports the Shared Processor LPAR Option and may be
run with that option enabled; else the Shared Processor LPAR
Option shall be disabled for this partition.</para>
</entry>
</row>
<row>
<entry>
<para>2</para>
</entry>
<entry>
<para>ibm,dynamic-reconfiguration-memory: If set the client
program supports the
<emphasis role="bold"><literal>&#8220;ibm,dynamic-reconfiguration-memory&#8221;</literal></emphasis>
property and it may be presented in the device tree; else, the partition
memory shall be represented with individual
<emphasis>memory</emphasis> nodes.</para>
</entry>
</row>
<row>
<entry>
<para>3</para>
</entry>
<entry>
<para>Large Pages: If this bit is set, the client supports
pages larger than 4 KB; else, the platform shall represent all
of memory as mapped via 4 K pages.</para>
</entry>
</row>
<row>
<entry>
<para>4</para>
</entry>
<entry>
<para>Alpha Partition<superscript><xref linkend="note.alpha" xrefstyle="select: nopage" /></superscript></para>
</entry>
</row>
<row>
<entry>
<para>5</para>
</entry>
<entry>
<para>Tolerate long delays in H_MIGRATE_DMA</para>
</entry>
</row>
<row>
<entry>
<para>6</para>
</entry>
<entry>
<para>Client supports donating dedicated processor
cycles</para>
</entry>
</row>
<row>
<entry>
<para>7</para>
</entry>
<entry>
<para>PCI Express/MSI Support: If set, the client supports PCI
Express implementations utilizing Message Signaled Interrupts
(MSIs).</para>
</entry>
</row>
<row>
<entry morerows="2">
<para>3</para>
</entry>
<entry>
<para>0</para>
</entry>
<entry>
<para>On input to ibm,client-architecture-support a non-zero
value indicates that the client supports the I/O Super Page
Option (Support of &gt;4K I/O pages) (Includes extensions to
H_MIGRATE_DMA for &gt;4K I/O pages and &gt;256 xlates).
See <xref linkend="dbdoclet.50569344_19308" />.</para>
<para>In the
<emphasis role="bold"><literal>ibm,architecture-vec-5</literal></emphasis> property of the
<emphasis role="bold"><literal>/chosen</literal></emphasis> node, a non-zero value indicates
that the platform supports the I/O Super Page Option (Support
of &gt;4K I/O pages).</para>
</entry>
</row>
<row>
<entry>
<para>1-4</para>
</entry>
<entry>
<para>On input to ibm,client-architecture-support this field
shall be zero.</para>
<para>In the
<emphasis role="bold"><literal>ibm,architecture-vec-5</literal></emphasis> property of the
<emphasis role="bold"><literal>/chosen</literal></emphasis> node, this field represents the
implementation dependent number of xlates entries supported per
migration operation as: 256 * 2**N.
See <xref linkend="dbdoclet.50569344_19308" />.</para>
</entry>
</row>
<row>
<entry>
<para>5-7</para>
</entry>
<entry>
<para>On input to ibm,client-architecture-support this field
shall be zero.</para>
<para>In the
<emphasis role="bold"><literal>&#8220;ibm,architecture-vec-5&#8221;</literal></emphasis> property of the
<emphasis role="bold"><literal>/chosen</literal></emphasis> node, this field represents the
implementation dependent number of simultaneous migration
options supported as: 2**N.
See <xref linkend="dbdoclet.50569344_19308" />.</para>
</entry>
</row>
<row>
<entry morerows="26">
<para>Base</para>
<para>&#160;</para>
</entry>
<entry morerows="26">
<para>5</para>
<para>LoPAR or OF Options<superscript><xref linkend="note.opt5" xrefstyle="select: nopage" /></superscript></para>
<para>&#160;</para>
</entry>
<entry morerows="3">
<para>4</para>
</entry>
<entry nameend="c5" namest="c4">
<para>Cooperative Memory Over-commitment Option Control</para>
</entry>
</row>
<row>
<entry>
<para>0</para>
</entry>
<entry>
<para>The value of 1 enables the Cooperative Memory
Over-commitment Option</para>
</entry>
</row>
<row>
<entry>
<para>1</para>
</entry>
<entry>
<para>The value of 1 enables the Extended Cooperative Memory
Over-commit Option</para>
</entry>
</row>
<row>
<entry>
<para>2-7</para>
</entry>
<entry>
<para>Reserved for Expansion</para>
</entry>
</row>
<row>
<entry morerows="3">
<para>5</para>
</entry>
<entry nameend="c5" namest="c4">
<para>Associativity Information Option Control</para>
</entry>
</row>
<row>
<entry>
<para>0</para>
</entry>
<entry>
<para>= the &#8220;Form value&#8221; of the
<emphasis role="bold"><literal>&#8220;ibm,associativity&#8221;</literal></emphasis> and
<emphasis role="bold"><literal>&#8220;ibm,associativity-reference-points&#8221;</literal></emphasis>
properties. See <xref linkend="dbdoclet.50569346_35960" /> for further details.</para>
</entry>
</row>
<row>
<entry>
<para>1</para>
</entry>
<entry>
<para>Platform Resource Reassignment Notification (Affinity
Change)</para>
</entry>
</row>
<row>
<entry>
<para>2-7</para>
</entry>
<entry>
<para>Reserved for Expansion</para>
</entry>
</row>
<row>
<entry morerows="8">
<para>6</para>
</entry>
<entry nameend="c5" namest="c4">
<para>Binary Option Controls</para>
</entry>
</row>
<row>
<entry>
<para>0</para>
</entry>
<entry>
<para>Enable MTT Option</para>
<para>See
<xref linkend="dbdoclet.50569344_50921" />.</para>
</entry>
</row>
<row>
<entry>
<para>1</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
</row>
<row>
<entry>
<para>2</para>
</entry>
<entry>
<para>Enable Active Memory Compression</para>
</entry>
</row>
<row>
<entry>
<para>3</para>
</entry>
<entry>
<para>Request timebase synchronization. On input to
ibm,client-architecture-support, a non-zero value indicates the
OS is requesting timebase synchronization with the logical
partition specified in bytes 28-29.</para>
<para>In the
<emphasis role="bold"><literal>&#8220;ibm,architecture-vec-5&#8221;</literal></emphasis>
property of the <emphasis role="bold"><literal>/chosen</literal></emphasis> node,
a non-zero value indicates the platform successfully synchronized
the timebase with the logical partition specified in bytes 28-29. A
n invalid logical partition specified in bytes 28-29 will result in a zero value.</para>
</entry>
</row>
<row>
<entry>
<para>4</para>
</entry>
<entry>
<para>Reserved for Expansion</para>
</entry>
</row>
<row>
<entry>
<para>5</para>
</entry>
<entry>
<para>Enable Hotplug Interrupts<?linebreak?>
See Hot Plug Events in <xref linkend="Hot_Plug_Events" />.</para>
</entry>
</row>
<row>
<entry>
<para>6</para>
</entry>
<entry>
<para>Enable Support for Multiple Hotplug Slots per PHB</para>
</entry>
</row>
<row>
<entry>
<para>7</para>
</entry>
<entry>
<para>Enable Hash Page Table Resize Option</para>
</entry>
</row>
<row>
<entry>
<para>7</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>Reserved for Expansion</para>
</entry>
</row>
<row>
<entry morerows="2">
<para>8</para>
</entry>
<entry nameend="c5" namest="c4">
<para>SRIOV Virtual Functions Options</para>
</entry>
</row>
<row>
<entry>
<para>0</para>
</entry>
<entry>
<para> SRIOV Virtual Functions Support Dynamic DMA Windows (DDW):<?linebreak?>
0: SRIOV Virtual Functions do not support DDW
1: SRIOV Virtual Functions do support DDW</para>
</entry>
</row>
<row>
<entry>
<para>1-7</para>
</entry>
<entry>
<para> Reserved For Expansion</para>
</entry>
</row>
<row>
<entry morerows="1">
<para>9-12</para>
</entry>
<entry nameend="c5" namest="c4">
<para>Max Processors Supported<?linebreak?>
(For legacy support, if this byte is not present the
partition is limited to a maximum of 64 processors)</para>
</entry>
</row>
<row>
<entry>
<para>0-31</para>
</entry>
<entry>
<para>32 bit unsigned integer maximum number of OF device tree
nodes of type &#8220;cpu&#8221; that may be presented to this
partition.</para>
</entry>
</row>
<row>
<entry>
<para>13-14</para>
</entry>
<entry>
<para>0-7 &amp; 0-7</para>
</entry>
<entry>
<para>Highest Base LoPAR Level Supported as the binary
contents of 13.14<?linebreak?>
(i.e. level 4.15 would be encoded as 0x040F)</para>
</entry>
</row>
<row>
<entry morerows="4">
<para>15-16</para>
</entry>
<entry nameend="c5" namest="c4">
<para>Memory Reference Instrumentation</para>
</entry>
</row>
<row>
<entry>
<para>0</para>
</entry>
<entry>
<para>Reference History Array</para>
</entry>
</row>
<row>
<entry>
<para>1</para>
</entry>
<entry>
<para>Access Rate Array</para>
</entry>
</row>
<row>
<entry>
<para>2</para>
</entry>
<entry>
<para>Affinity Domain Access Log</para>
</entry>
</row>
<row>
<entry>
<para>3-15</para>
</entry>
<entry>
<para>Reserved for Expansion</para>
</entry>
</row>
<row>
<entry morerows="11">
<para>Base</para>
<para>&#160;</para>
</entry>
<entry morerows="11">
<para>5</para>
<para>LoPAR or OF Options<superscript><xref linkend="note.opt5" xrefstyle="select: nopage" /></superscript></para>
<para>&#160;</para>
</entry>
<entry morerows="4">
<para>17-20</para>
</entry>
<entry nameend="c5" namest="c4">
<para>Platform Facilities Enable &#8211; Value of 0b1 indicates
facility is enabled</para>
</entry>
</row>
<row>
<entry>
<para>0</para>
</entry>
<entry>
<para>Random Number Generator</para>
</entry>
</row>
<row>
<entry>
<para>1</para>
</entry>
<entry>
<para>Compression Engine</para>
</entry>
</row>
<row>
<entry>
<para>2</para>
</entry>
<entry>
<para>Encryption Engine</para>
</entry>
</row>
<row>
<entry>
<para>3-31</para>
</entry>
<entry>
<para>Reserved for Expansion -- Value = 0b0</para>
</entry>
</row>
<row>
<entry>
<para>21</para>
</entry>
<entry>
<para>0-7</para>
</entry>
<entry>
<para>Sub-Processor Representation Level --</para>
<para>Defined Values:<?linebreak?>
0: Sub-Processors not supported<?linebreak?>
1: 1,2,or 4 Sub-Processors supported<?linebreak?>
2-255 Reserved</para>
</entry>
</row>
<row>
<entry morerows="2">
<para>22</para>
</entry>
<entry>
<para>0</para>
</entry>
<entry>
<para>If set the client program supports the
<emphasis role="bold"><literal>&#8220;ibm,dynamic-memory-v2&#8221;</literal></emphasis>
property in the
<emphasis role="bold"><literal>&#8220;ibm,dynamic-reconfiguration-memory&#8221;</literal></emphasis>
node and it may be presented in the device tree;
else, the <emphasis role="bold"><literal>&#8220;ibm,dynamic-memory&#8221;</literal></emphasis>
property shall be represented.</para>
</entry>
</row>
<row>
<entry>
<para>1</para>
</entry>
<entry>
<para>If set the client program supports the
<emphasis role="bold"><literal>&#8220;ibm,drc-info&#8221;</literal></emphasis>
property definition and it may be presented in the device tree;
else, the <emphasis role="bold"><literal>&#8220;ibm,drc-indexes&#8221;</literal></emphasis>,
<emphasis role="bold"><literal>&#8220;ibm,drc-types&#8221;</literal></emphasis>,
<emphasis role="bold"><literal>&#8220;ibm,drc-names&#8221;</literal></emphasis>, and
<emphasis role="bold"><literal>&#8220;ibm,drc-power-domains&#8221;</literal></emphasis> properies shall be presented.</para>
</entry>
</row>
<row>
<entry>
<para>2-7</para>
</entry>
<entry>
<para>Reserved for Expansion</para>
</entry>
</row>
<row>
<entry>
<para>23-27</para>
</entry>
<entry nameend="c5" namest="c4">
<para>Reserved for Expansion</para>
</entry>
</row>
<row>
<entry>
<para>28-29</para>
</entry>
<entry>
<para>0-15</para>
</entry>
<entry>
<para>On input to ibm,client-architecture-support, this field
indicates the logical partition ID for timebase synchronization. </para>
</entry>
</row>
<row>
<entry>
<para>30-256</para>
</entry>
<entry nameend="c5" namest="c4">
<para>Reserved for Expansion</para>
</entry>
</row>
<row>
<entry morerows="20">
<para>Base</para>
</entry>
<entry morerows="17">
<para>6</para>
<para>Hints</para>
</entry>
<entry morerows="7">
<para>1</para>
</entry>
<entry>
<para>0</para>
</entry>
<entry morerows="7">
<para>Reserved for Expansion (0b0)</para>
</entry>
</row>
<row>
<entry>
<para>1</para>
</entry>
</row>
<row>
<entry>
<para>2</para>
</entry>
</row>
<row>
<entry>
<para>3</para>
</entry>
</row>
<row>
<entry>
<para>4</para>
</entry>
</row>
<row>
<entry>
<para>5</para>
</entry>
</row>
<row>
<entry>
<para>6</para>
</entry>
</row>
<row>
<entry>
<para>7</para>
</entry>
</row>
<row>
<entry morerows="7">
<para>2</para>
</entry>
<entry>
<para>0</para>
</entry>
<entry>
<para>Secondary Page Table Entry Group: If set, the client does
not use secondary page table entry groups; else the client may
use secondary page table entry groups.</para>
</entry>
</row>
<row>
<entry>
<para>1</para>
</entry>
<entry morerows="6">
<para>Reserved</para>
</entry>
</row>
<row>
<entry>
<para>2</para>
</entry>
</row>
<row>
<entry>
<para>3</para>
</entry>
</row>
<row>
<entry>
<para>4</para>
</entry>
</row>
<row>
<entry>
<para>5</para>
</entry>
</row>
<row>
<entry>
<para>6</para>
</entry>
</row>
<row>
<entry>
<para>7</para>
</entry>
</row>
<row>
<entry>
<para>3</para>
</entry>
<entry>
<para>0-7</para>
</entry>
<entry>
<para>OS Name: Represents the name of the client OS. Defined
values include:<?linebreak?>
0x0: Reserved<?linebreak?>
0x1: AIX<?linebreak?>
0x2: Linux<?linebreak?>
0x3-0xFF: Reserved for Expansion</para>
</entry>
</row>
<row>
<entry>
<para>4-256</para>
</entry>
<entry nameend="c5" namest="c4">
<para>Reserved for Expansion</para>
</entry>
</row>
<row>
<entry>
<para>7</para>
<para>OS Identification</para>
</entry>
<entry>
<para>1-256</para>
</entry>
<entry nameend="c5" namest="c4">
<para>An ASCII character formatted null terminated string that
describes the client operating system. The string shall be
human readable and may be displayed on the console.</para>
</entry>
</row>
<row>
<entry>
<para>8-255</para>
</entry>
<entry nameend="c5" namest="c3">
<para>Reserved for Expansion</para>
</entry>
</row>
<row>
<entry>
<para>256</para>
</entry>
<entry nameend="c5" namest="c3">
<para>Reserved for Expansion to the first Extension Option
Array</para>
</entry>
</row>
<row>
<entry>
<para>Extensions 1-N</para>
</entry>
<entry nameend="c5" namest="c2">
<para>Reserved for Expansion</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para><emphasis role="bold">Notes:</emphasis></para>
<orderedlist>
<listitem xml:id="note.ignore">
<para>The Ignore Policy bit indicates that the client program assumes
all responsibility for the options represented by the option vector. The
firmware is to configure the platform at the highest level consistent
with its configuration variables and ignore the rest of the specific
option vector. An option vector with the Ignore Policy bit set need be no
longer than two bytes (size=0, data = 0b1ddd dddd where d = don&#8217;t
care).</para>
</listitem>
<listitem xml:id="note.cessation">
<para>The Cessation Policy Bit determines if the partition continues
to run if the platform must operate with an option enabled that is not
explicitly supported by the client program as represented by the option
vector setting. If the Cessation Policy Bit is 1, then processing halts
as with a boot failure. If the Cessation Policy Bit is 0 then client
program processing continues if the unsupported option is initialized to
a benign state and stays in that state unless an aware program activates
the option, and the option does not appear in the device tree. If an
unsupported option cannot be initialized to a benign state, then
processing halts with a boot failure. Following are the detailed
definitions of benign state for selected bit vectors.</para>
<itemizedlist>
<listitem>
<para>For option vector numbers 1 &#8220;PowerPC Server Processor
Architecture Level&#8221; and 3 &#8220;IBM PowerPC Server Processor
Extensions&#8221; the benign state is defined as unable to generate
exceptions, mask errors, or present covert channel exposures.</para>
</listitem>
<listitem>
<para>For option vector number 5 &#8220;LoPAR Options&#8221; Byte 2
bit 5 &#8220;Alpha Partition&#8221; The Cessation Policy bit is not
applicable.</para>
</listitem>
<listitem>
<para>For option vector number 2 &#8220;Open Firmware&#8221; the
Cessation Policy Bit is not defined, the platform either accommodates the
values defined in the option vector or proceeds as with boot
failure.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem xml:id="dbdoclet.50569368_24293">
<para>The Initial size
of the RMA is set to the greater of the values indicated by bytes 24-27
or 32 of option vector number 2 &#8220;Open Firmware&#8221; or minimum
RMA size supported by the platform and capped by the maximum memory
defined for the partition and the maximum size of the RMA supported by
the platform. The respective selected values are reported in the length
of the first
<emphasis>memory</emphasis> property.</para>
</listitem>
<listitem xml:id="note.alpha">
<para>The Alpha flag only applies to the first partition of a non HMC
managed system and activates overrides to the partition's I/O resource
allocation as defined in the partition definition.</para>
<itemizedlist>
<listitem>
<para>If the system is HMC managed, the flag is ignored and the client
program gets the resources assigned by its partition definition (no
overrides are activated).</para>
</listitem>
<listitem>
<para>If the partition is not the first partition, the flag is ignored
and the client program gets the resources assigned by the partition
definition (no overrides are activated).</para>
</listitem>
<listitem>
<para>If the Alpha flag applies, and is set, then the partition gets a
VMC virtual I/O device in its device tree regardless of its partition
definition (Override to include VMC is activated).</para>
</listitem>
<listitem>
<para>If the Alpha flag applies, and is not set, then the partition
does not get a VMC virtual I/O device in its device tree regardless of
its partition definition (Override to remove VMC is activated) and it
gets all the physical I/O resources in its device tree regardless of its
partition definition (Override to include all physical I/O is activated).
Note this condition requires that any other platform partitions be
terminated.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem xml:id="note.opt5">
<para>Given that the Ignore policy bit is off and the partition
continues to run, the options and values presented in by this option
vector and supported/chosen by the platform firmware are reported in the
<emphasis role="bold"><literal>&#8220;ibm,architecture-vec-5&#8221;</literal></emphasis> property of the
<emphasis role="bold"><literal>/chosen</literal></emphasis> node.</para>
</listitem>
<listitem xml:id="note.opt6">
<para>Option vector number 1 &#8220;PowerPC Server Processor
Architecture Level&#8221; and the property that reports the chosen value
(i.e.,
<emphasis role="bold"><literal>&#8220;cpu-version&#8221;</literal></emphasis>) represent the operational
base architectural level of the processors -- that is without regard to
enabled processor architectural options. Option vector number 3
&#8220;IBM PowerPC Server Processor Extensions&#8221; and option specific
properties that report the chosen values represent the active processor
architectural options. Some processor implementations may not support all
combinations of these two option vectors. The firmware shall activate the
highest level of processor support, consistent with partition attributes,
that does not exceed the most restrictive of the two option vectors. Note
the Cessation Policy bit may allow operation where the lowest level of
processor support still exceeds the most restrictive case.</para>
</listitem>
<listitem xml:id="note.hypervisor">
<para>If a client program does not support logical partitioning no
other client programs may be running simultaneously on the platform. The
platform may impose further restrictions beyond the scope of LoPAR. If
the platform honors the client program restriction of not supporting
logical partitioning, upon return the logical real address equals the
platform real address. If the platform can not honor the restriction, the
processing terminates as with a boot failure. The cessation policy option
vector bit has no effect upon logical partitioning option vector
bit.</para>
</listitem>
</orderedlist>
</section>
<section xml:id="dbdoclet.50569368_40198">
<title>ROM Node(s)</title>
<para>The ROM Node(s), when present to represent optional platform read
only memory containing directly executable platform firmware, shall be a
child or children of the root node.</para>
<section>
<title>ROM Node Properties</title>
<para>Each ROM Node shall have the following properties:</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> that denotes a ROM Node.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: A string, encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.</para>
<para>The value of this property shall be
<literal>&#8220;rom&#8221;</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> to define a unit-address for the
node.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: One (
<emphasis>phys-addr, size</emphasis>) pair.</para>
<para>The
<emphasis>phys-addr</emphasis> of this property shall be the starting
physical address of this ROM and the
<emphasis>size</emphasis> value shall be 0. The
<emphasis>size</emphasis> =0 prevents a conflict with the
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> of this node&#8217;s
children.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;#address-cells&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> to define the address space
representation of child nodes.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: an integer, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>. Its value shall be identical to that of
this node&#8217;s parent&#8217;s
<emphasis role="bold"><literal>&#8220;#address-cells&#8221;</literal></emphasis> value.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ranges&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> to define the address range that is
decoded by this
<emphasis role="bold"><literal>/rom</literal></emphasis> node.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: One (
<emphasis>child-phys</emphasis>,
<emphasis>parent-phys</emphasis>,
<emphasis>size</emphasis>) triple, where
<emphasis>child-phys</emphasis> equals
<emphasis>parent-phys</emphasis> and the number of cells of each
corresponds to the parent&#8217;s
<emphasis role="bold"><literal>&#8220;#address-cells&#8221;</literal></emphasis> value.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;available&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> to define available ROM
resources.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: Arbitrary number of
<emphasis>phys-addr, size</emphasis> pairs.
<emphasis>Phys</emphasis>-
<emphasis>addr</emphasis> is a
<emphasis>phys.hi...phys.lo</emphasis> list of integers, each integer
encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.
<emphasis>Size</emphasis> is one or more integers, each encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
<para>The value of this property defines resources, managed by this
package, that are currently available for use by a client program.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;write-characteristic&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> defines the ROM Technology.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: a string, encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>, where the value could equal
<emphasis role="bold"><literal>&#8220;flash&#8221;</literal></emphasis>,
<emphasis role="bold"><literal>&#8220;eeprom&#8221;</literal></emphasis>,
<emphasis role="bold"><literal>&#8220;rom&#8221;</literal></emphasis> or
<emphasis role="bold"><literal>&#8220;nvram&#8221;</literal></emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;cacheable&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>OF standard property indicating that the ROM is cacheable.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: &lt;none&gt;.</para>
<para>The presence of this property indicates that the ROM is
cacheable.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section>
<title>ROM Node Methods</title>
<para>If one or more ROM nodes are present, they shall each implement the
following standard methods per
<xref linkend="dbdoclet.50569387_45524" />, Section 3.6.1. The
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property is used to determine which
ROM the standard methods apply to for multiple ROM&#8217;s.</para>
<para>The following methods must be defined by
<emphasis role="bold"><literal>/rom</literal></emphasis> node.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>open</literal></emphasis> (-- true) [M]</term>
<listitem>
<para>Standard method to prepare the ROM Node for subsequent use.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>close</literal></emphasis> (--) [M]</term>
<listitem>
<para>Standard method to close the previously opened ROM Node.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>decode-unit</literal></emphasis>
(addr len -- phys.lo...phys.hi) [M]</term>
<listitem>
<para>Standard method to convert text unit-string to physical address.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>encode-unit</literal></emphasis>
(phys.lo...phys.hi -- unit-str unit-len) [M]</term>
<listitem>
<para>Standard method to convert physical address to text unit-string.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>probe</literal></emphasis> (--) [M]</term>
<listitem>
<para>OF method used at boot time to probe all ROM&#8217;s.</para>
<para>The
<emphasis role="bold"><literal>probe</literal></emphasis> method for ROM Nodes shall probe for FCode
images within the address space defined by its
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property as defined herein. For
each page within its address space, look for a valid FCode image. A valid
FCode image is defined to start with an FCode-header (see section 5.2.2.5
in
<xref linkend="dbdoclet.50569387_45524" />) where the first byte is
<emphasis role="bold"><literal>start1</literal></emphasis>, the format byte is 0x08, the length field
indicates that the FCode program is contained within the address space of
the
<emphasis role="bold"><literal>/rom</literal></emphasis> node, and where the checksum is correct. (This
probing must take into account the possibility that the ROM image is in
the opposite endian-ness from which OF is currently running.)</para>
<para>If such an FCode image is found, a new child node shall be created
by executing
<emphasis role="bold"><literal>new-device</literal></emphasis> and
<emphasis role="bold"><literal>set-args</literal></emphasis>, the FCode image copied to memory (taking
into account the endian-ness) and the copy evaluated with
<emphasis role="bold"><literal>byte-load</literal></emphasis>. (The FCode program can use
<emphasis role="bold"><literal>my-unit</literal></emphasis> to create its
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property.). The arguments used by
<emphasis role="bold"><literal>set-args</literal></emphasis> are defined to be 0,0,unit-str, unit-len
where unit-str is a text string representation of the physical address
location for the FCode Image and unit-len is the length of the FCode
Image.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
</section>
<section>
<title>ROM Child Node(s)</title>
<para>This section describes the properties and methods for a ROM Child
Node.</para>
<section>
<title>ROM Child Node Properties</title>
<para>The following properties must be created by
<emphasis role="bold"><literal>/rom</literal></emphasis> child nodes.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> that denotes a ROM child node.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: A string, encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.</para>
<para>Some physical ROM implementations may not fully decode their entire
address range. This could lead to multiple images of the ROM to appear at
different addresses, due to the &#8220;aliasing&#8221; of the ROM image.
To prevent multiple device nodes from appearing in the device tree, the
FCode for such ROMs should look for an already existing peer node that
represents their image. This could be done, for example, by checking that
any of the peer of the child of its parent node has a
<emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis> property value that is the same as
this node&#8217;s FCode would create.</para>
<para>If such a node is found, the FCode should &#8220;abort&#8221; the
evaluation of its FCode (e.g., by executing an
<emphasis role="bold"><literal>end0</literal></emphasis>) before creating its
<emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis> property. OF shall remove a node
when the FCode evaluation for the node does not result in a
<emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis> property being defined.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> that defines the child node address
range for a ROM image(s).</para>
<para>
<emphasis>prop-encoded-array</emphasis>: List of (
<emphasis>phys-addr, size</emphasis>) specifications.</para>
<para>
<emphasis>Phys-addr</emphasis> is encoded as with
<emphasis role="bold"><literal>encode-phys</literal></emphasis>, and
<emphasis>size</emphasis> is encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>. The
<emphasis>phys-addr</emphasis> is a base address of the ROM image and
<emphasis>size</emphasis> is the length of the ROM image.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section>
<title>ROM Child Node Methods</title>
<para>The following methods must be defined by
<emphasis role="bold"><literal>/rom</literal></emphasis> child nodes.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>open</literal></emphasis> (-- true) [M]</term>
<listitem>
<para>Standard method to prepare this device for subsequent use.</para>
<para>The
<emphasis role="bold"><literal>open</literal></emphasis> method must be prepared to parse
<emphasis>my-args</emphasis> for the case(s) when the node is being opened
in order to access &#8220;files&#8221;; e.g., when the bootinfo.txt file
is being accessed during the
<emphasis>multiboot menu</emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>close</literal></emphasis> (--) [M]</term>
<listitem>
<para>Standard method to close the previously opened device.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>load</literal></emphasis> (addr -- len) [M]</term>
<listitem>
<para>Standard method to load an image. The image must be one that is
recognized by the OF
<emphasis role="bold"><literal>init-program</literal></emphasis> method. It is strongly recommended that
the ELF format be used, since it has the mechanism to specify
configuration variable requirements of an OS.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
</section>
</section>
<section>
<title>Run Time Abstraction Services (RTAS) Node</title>
<para>This system node is a child of
<emphasis role="bold"><literal>&#8220;/&#8221;</literal></emphasis> (root). This section defines
properties and methods for the RTAS node. The RTAS Node shall not have
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> or
<emphasis role="bold"><literal>&#8220;ranges&#8221;</literal></emphasis> properties.</para>
<section xml:id="dbdoclet.50569368_41461">
<title>RTAS Node Properties</title>
<para>This section describes the
<emphasis>rtas</emphasis> node properties.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> that denotes the RTAS node.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: A string, encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.</para>
<para>The value of this property shall be
<literal>&#8220;rtas&#8221;</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;rtas-event-scan-rate&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>
<emphasis>property name</emphasis> that is the rate at which an OS should
read indicator/sensor/error data</para>
<para>
<emphasis>prop-encoded-array</emphasis>: An integer, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis></para>
<para>The value of this property shall be a number indicating the desired
rate for reading sensors and/or error information in calls per minute.
This number is platform dependent.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;rtas-indicators&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>
<emphasis>property name</emphasis> that indicates indicators are
implemented.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: An array of paired integers (
<emphasis>token maxindex</emphasis>), each encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
<para>The values for this property is a list of integers that are the
token values (
<emphasis>token</emphasis>) for the defined indicators and the number of
indicators (
<emphasis>maxindex</emphasis>) for that token which are implemented (see
<xref linkend="dbdoclet.50569332_13537" />) on the platform.</para>
<para>
<emphasis role="bold">Note:</emphasis> The indicator indices for a given token are
numbered 0... maxindex-1.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;rtas-sensors&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>
<emphasis>property name</emphasis> that indicates sensors are
implemented.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: An array of paired integers (
<emphasis>token maxindex</emphasis>), each encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
<para>The values for this property is a list of integers that are the
token values (
<emphasis>token</emphasis>) for the defined sensors and the number of
sensors (
<emphasis>maxindex</emphasis>) for that token which are implemented (see
<xref linkend="dbdoclet.50569332_13537" />) on the platform.</para>
<para>
<emphasis role="bold">Note:</emphasis> The sensor indices for a given token are
numbered 0 ... maxindex-1.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;rtas-version&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>
<emphasis>property name</emphasis> describes version information for the
RTAS implementation.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: An integer, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
<para>The value of this property shall denote the version the RTAS
implementation. For this version, the integer shall be as defined in this
architecture.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;rtas-size&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>
<emphasis>property name</emphasis> is the size of the RTAS memory
image.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: An integer, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
<para>The value of this property shall be the amount of contiguous real
system memory required by RTAS, in bytes.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;rtas-display-device&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>
<emphasis>property name</emphasis> identifies RTAS Display Device</para>
<para>
<emphasis>prop-encoded-array</emphasis>: An integer, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
<para>The value of this property shall be the
<emphasis>phandle</emphasis> of the device node used by the RTAS
display-character function.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;rtas-error-log-max&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>
<emphasis>property name</emphasis> identifies maximum size of an extended
error log entry.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: An integer, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
<para>The value of this property shall be the maximum size of an extended
error log entry, in bytes.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;power-on-max-latency&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>
<emphasis>property name</emphasis> specifies a future power on time
capability.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: An integer, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
<para>The value of this property specifies the capability of the hardware
to control the delay of system power on in days. If the property is
present, the value shall indicate the maximum delay or latency in days.
If the property is not present, the maximum delay or latency is 28
days.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,preserved-storage&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>property name</emphasis> specifies that the client program was
loaded with one or more LMBs preserved from a previous client
program.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: None, this is a name only
property.</para>
<para>The client program may wish to save the contents of the preserved
LMBs and deregister the LMBs for preservation.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,scan-log-directory&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> specifies that the platform supports
the scan-log directory option.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: None, this is a name only
property.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,indicator-</literal></emphasis><emphasis>&lt;token&gt;</emphasis><emphasis role="bold"><literal>&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> to provide a FRU location code for
identifying each indicator.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: an array of
<emphasis>maxindex</emphasis> + 1 strings, encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,sensor-</literal></emphasis><emphasis>&lt;token&gt;</emphasis><emphasis role="bold"><literal>&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> to provide a FRU location code for
identifying each physical sensor.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: an array of
<emphasis>maxindex</emphasis> + 1 strings, encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,display-line-length&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> to provide the length of a display line
in number of characters.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: an integer, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,display-number-of-lines&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> to provide the number of lines in the
display.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: an integer, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,display-truncation-length&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis>, when provided, specifies the length to
which each line to be display is truncated, based on which line of the
physical display on which the line is displayed. When the truncation
length is greater than the length specified in the
<emphasis role="bold"><literal>&#8220;ibm,display-line-length&#8221;</literal></emphasis> property, then
the platform provides a platform-dependent method of displaying the line
to the user.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: An array of integers, each
encoded as with encode-int. The number of integers corresponds to the
number of lines, as defined by the
<emphasis role="bold"><literal>&#8220;ibm,display-number-lines&#8221;</literal></emphasis> property. The
first integer refers to the truncation length for the first physical line
of the display, the second to the second physical line, and so on.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,form-feed&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> to provide an indication of the
form-feed capability.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: a character, NULL (0x00) if
form-feed is not supported and np (0x0C) if form-feed is supported,
encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,environmental-sensors&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> describes the environmental sensors
which are available to an application.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: An array of paired integers
(token maxindex), each encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,flash-block-version&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>property name</emphasis> in the
<emphasis>/rtas</emphasis> node indicates the block list format to be
used.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: integer encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>. Value is 0x01 for the discontiguous
block list. (If a new version of the block list is ever required, other
values could be defined.)</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,errinjct-tokens&#8221;</literal></emphasis> [S]</term>
<listitem>
<para><emphasis>property name</emphasis> defines the error inject functions implemented on
this platform.</para>
<para><emphasis>prop-encoded-array</emphasis>: List of (errinjct-token-name,
errinjct-token-value) specifications.</para>
<para>errinjct-token-name: A string, encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.</para>
<para>errinjct-token-value: is encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,lrdr-capacity&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> in the
<emphasis>/rtas</emphasis> node identifies the dynamic reconfiguration
capabilities of the partition</para>
<para>
<emphasis>prop-encoded-array</emphasis>: A triple consisting of phys,
size, and one integer encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis></para>
<para>The phys (of size #address-cells) communicates the maximum address
in bytes and therefore, the most memory that can be allocated to this
partition.</para>
<para>The size (of size #size-cells) communicates the increment (quantum
of logical memory dynamic reconfiguration).</para>
<para>The first integer communicates the maximum number of processors
(implied quantum of 1).</para>
<para>
<emphasis role="bold">Note:</emphasis> Some implementations depend upon the presence
and value of a second integer. Future extensions to this property should
not define a second integer for new purposes.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,hypertas-functions&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> of the
<emphasis>/rtas</emphasis> node, defines the platform&#8217;s implemented
hypervisor RTAS function sets.</para>
<para><emphasis>prop-encoded-array</emphasis>: List of Hypervisor-RTAS-function-set
specifications.</para>
<para>Each Hypervisor-RTAS-function-set specification is a byte string
encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,dma-delay-time&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> to define the time delay need to ensure outstanding
DMA operations targeting migrated pages have completed.</para>
<para><emphasis>prop-encoded-array</emphasis>: A one cell integer encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis> that represents the number of
micro-seconds that the OS should wait prior to reusing migrated DMA read
target pages.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,associativity-reference-points&#8221;</literal></emphasis> [S]</term>
<listitem>
<para><emphasis>property name</emphasis> to define the associativity reference points for the
<emphasis role="bold"><literal>&#8220;ibm,associativity&#8221;</literal></emphasis>
properties of this platform.</para>
<para><emphasis>prop-encoded-array</emphasis>: A list of one or more integers cell(s) encoded
as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,max-associativity-domains&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> to define the maximum number associativity domains
for this platform.</para>
<para><emphasis>prop-encoded-array</emphasis>: An associativity list such that all values are
the maximum that the platform supports in that location. The
associativity list consisting of a number of entries integer (N) encoded
as with
<emphasis role="bold"><literal>encode-int</literal></emphasis> followed by N integers encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis> each representing maximum number
associativity domains the platform supports at that level.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,current-associativity-domains&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> to define the current number of associativity domains
for this platform.</para>
<para><emphasis>prop-encoded-array</emphasis>: An associativity list such that all values
are the number of unique values that the current platform supports in that location.
The associativity list consisting of a number of entries integer (N) encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>
followed by N integers encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>
each representing
current number of unique associativity domains the platform supports at that level.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,request-partition-shutdown&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>property name</emphasis> to specify that the partition was
rebooted in the forced fire hose dump mode.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: An integer encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis> that represents the platform&#8217;s
partition shutdown configuration variable. The defined states are:</para>
<para>0 = The platform boots with no request to save appropriate data nor
shutdown the partition.</para>
<para>1 = The platform boots with a conditional request to save
appropriate data and shutdown the partition. The client program should
check for an EPOW sensor state of 3 and if present, it should save
appropriate data and shutdown the partition. If the EPOW sensor state of
3 is not present, then the partition should initiate a reboot since the
device tree will be incomplete.</para>
<para>2 = The platform boots with a mandatory request to the client
program to save appropriate data and shutdown the partition.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,integrated-stop-self&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>property name</emphasis> indicating that prior to placing a
processor in the stopped state, the platform flushes and disables any
caches/memory exclusively used by the issuing processor.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: NULL</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,rks-hcalls&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>property name</emphasis>: indicating the hcalls that are
implemented with a reduced kill set. Absence of this property indicates
that only hcalls that are specified as always having a reduced kill set
provide that semantic.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: A one to N byte bit vector, bit
positions representing hcall()s (see
<xref linkend="dbdoclet.50569368_69500" />) that present a reduced kill
set per their architectural specification.</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569368_69500">
<title><emphasis role="bold"><literal>&#8220;ibm,rks-hcalls&#8221;</literal></emphasis> bit vector to hcall map</title>
<?dbhtml table-width="75%" ?>
<?dbfo table-width="75%" ?>
<tgroup cols="3">
<colspec colname="c1" colwidth="33*" align="center" />
<colspec colname="c2" colwidth="33*" align="center" />
<colspec colname="c3" colwidth="33*" align="center" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Byte Number</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Bit Number</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">hcall</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<row>
<entry morerows="7">
<para>0</para>
</entry>
<entry>
<para>0</para>
</entry>
<entry morerows="1" valign="middle">
<para>0b11 for H_CONFER &amp; H_PROD</para>
</entry>
</row>
<row>
<entry>
<para>1</para>
</entry>
</row>
<row>
<entry>
<para>2</para>
</entry>
<entry valign="middle">
<para>Set to 1 if H_PURR is implemented with a reduced volatile
kill set of r3 &amp; r4; else set to 0.</para>
</entry>
</row>
<row>
<entry>
<para>3</para>
</entry>
<entry morerows="4" valign="middle">
<para>Reserved for future expansion (0b0)</para>
</entry>
</row>
<row>
<entry>
<para>4</para>
</entry>
</row>
<row>
<entry>
<para>5</para>
</entry>
</row>
<row>
<entry>
<para>6</para>
</entry>
</row>
<row>
<entry>
<para>7</para>
</entry>
</row>
<row>
<entry>
<para>1-N</para>
</entry>
<entry nameend="c3" namest="c2">
<para>Reserved for future expansion</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,reset-capabilities&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>property name</emphasis> indicates what capabilities the
platform supports relative to the ibm,set-slot-reset RTAS call, when that
RTAS call is implemented.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: An integer encoded as with
encode-int that represents the functions supported in the
<emphasis>ibm,set-slot-reset</emphasis> RTAS call</para>
<para>0 = Platform supports Functions 0 and 1 supported.</para>
<para>1 = Platform supports Functions 0, 1, and 3.</para>
<para><emphasis role="bold">Note:</emphasis> The absence of this property implies the platform supports
Functions 0 and 1 for the
<emphasis>ibm,set-slot-reset</emphasis> RTAS call, when that RTAS call is
implemented.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,configure-kernel-dump-sizes&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>property name</emphasis> specifies that the Platform Assisted
Kernel Dump option is supported for sections described by this
property.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: For each dump section type
supported, a 32 bit cell which defines the ID of a supported section
followed by two 32-bit cells which gives the size of the section in bytes
(not including any disk headers.)</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,configure-kernel-dump-version&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>property name</emphasis> specifies that the Platform Assisted
Kernel Dump option is supported for versions described by this
property.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: Contains a 16-bit cell describing
the minimum kernel dump version supported by the firmware followed by a
16-bit cell describing the maximum kernel dump version supported by the
firmware.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,kernel-dump&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>property name</emphasis> specifies the presence of a registered
kernel dump in the Platform Assisted Kernel Dump option.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: Contains the description of the
registered kernel dump in the format described in
<xref linkend="dbdoclet.50569332_76933" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,read-slot-reset-state-functions&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>property name</emphasis> specifies the implementation of certain
input or output fields in the
<emphasis>ibm,read-slot-reset-state2</emphasis> RTAS call. If this
property does not exist, then the
<emphasis>ibm,read-slot-reset-state2</emphasis> RTAS call implements only
the first 3 inputs and the first 4 outputs (
<emphasis>Number Inputs</emphasis> is required to be 3 and the
<emphasis>Number Outputs</emphasis> is required to be 4), as defined in
<xref linkend="dbdoclet.50569332_80186" />.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: Contains a 32 bit cell, with the
bits defined as follows:</para>
<para>Bits 0-29: Reserved (value of 0).</para>
<para>Bit 30: When a value of 1, the
<emphasis>ibm,read-slot-reset-state2</emphasis> RTAS call checks the
<emphasis>Number Outputs</emphasis> and the implements the 5th output (
<emphasis>Number Outputs</emphasis> of 5), as defined by
<xref linkend="dbdoclet.50569332_80186" />.</para>
<para>Bit 31: When a value of 1, the
<emphasis>ibm,read-slot-reset-state2</emphasis> RTAS call implements the
first 3 inputs and the first 4 outputs (
<emphasis>Number Inputs</emphasis> of 3 and the
<emphasis>Number Outputs</emphasis> of 4), as defined in
<xref linkend="dbdoclet.50569332_80186" />. This bit is always required
to be a value of 1 when this property is implemented.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,change-msix-capable&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>property name</emphasis> indicating the platform supports the
<emphasis>ibm,change-msi</emphasis> RTAS call with
<emphasis>Number of Outputs</emphasis> equal to 4 and
<emphasis>Functions</emphasis> 3, 4, and 5.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: &lt;none&gt;</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section>
<title><literal>/RTAS</literal> node DR Sensors and Indicators</title>
<para>The following sensors and indicators are defined for the /RTAS node
for the DR option.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;9003&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>sensor token</emphasis>, the existence of this token number
denotes that the platform supports the 9003 &#8220;DR entity sense&#8221;
sensor.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;9001&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>indicator token</emphasis>, the existence of this token number
denotes that the platform supports the 9001 &#8220;isolation state&#8221;
indicator.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;9002&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>indicator token</emphasis>, the existence of this token number
denotes that the platform supports the 9002 &#8220;dr-indicator&#8221;
indicator used to guide operators in the physical add or removal of
hardware.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;9003&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>indicator token</emphasis>, the existence of this token number
denotes that the platform supports the 9003
&#8220;allocation-state&#8221; indicator.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,extended-os-term&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property-name</emphasis> indicating that the platform supports
extended
<emphasis>ibm,os-term</emphasis> behavior as described in
<xref linkend="dbdoclet.50569332_42118" />.</para>
<para><emphasis>prop-encoded-array</emphasis>: encode-null</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section>
<title>RTAS Function Property Names</title>
<para>This section defines the property names associated with the various
RTAS functions defined by
<xref linkend="dbdoclet.50569332_20008" />.
<xref linkend="dbdoclet.50569332_20008" /> should be used as the reference
for RTAS Functions currently implemented. Each RTAS function that a
platform implements shall
be represented by its own function property,
who&#8217;s value is the
<emphasis>token</emphasis> used to invoke the function on an RTAS
call.</para>
<para>The formal property definition for each such property is of the
form:</para>
<para>
<emphasis>property name</emphasis> specifies the name of the RTAS function
-- such as:</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;nvram-fetch&#8221;</literal></emphasis> [S]</term>
<listitem>
<para><emphasis>prop-encoded-array</emphasis>: The value,
<emphasis>token</emphasis>, is an integer encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
<para>If an RTAS function is implemented, there is a property name which
corresponds to its function name. The value of this property is a
<emphasis>token</emphasis>. This
<emphasis>token</emphasis>, when passed to RTAS via its
<emphasis>rtas-call</emphasis> interface (see below), invokes the named
RTAS function. If a RTAS function is not implemented, there will not be a
property corresponding to that function name. See the
<xref linkend="dbdoclet.50569332_13537" /> for more information about RTAS
functions.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,termno&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> of the
<emphasis>/rtas</emphasis> node defines the virtual terminal numbers
available for use by this partition.</para>
<para><emphasis>prop-encoded-array</emphasis>: A pair of integers encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>, the first being the value
of the lowest termno in a contiguous range of supported values, the second being the
number of termno values supported.</para>
<para><emphasis role="bold">Note:</emphasis> The number of supported termno values is
implementation dependent -- the minimum number is one.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,hypertas_functions&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> of the /RTAS node, defines the
platform&#8217;s implemented hypervisor RTAS function sets.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: List of
<emphasis>Hypervisor-RTAS-function-set</emphasis> specifications.</para>
<para>Each
<emphasis>Hypervisor-RTAS-function-set</emphasis> specification is a byte
string encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section>
<title>RTAS Node Methods</title>
<para>The
<emphasis role="bold"><literal>instantiate-rtas</literal></emphasis> or
<emphasis role="bold"><literal>instantiate-rtas-64</literal></emphasis> method is invoked by the OS to
instantiate the RTAS functionality. This is accomplished via the
call-method
<emphasis>Client Interface Service</emphasis>. If the platform supports
the
<emphasis role="bold"><literal>ibm,client-architecture-support</literal></emphasis> root node method, and
that method has not been called prior to the call of the
<emphasis role="bold"><literal>instantiate-rtas</literal></emphasis> or
<emphasis role="bold"><literal>instantiate-rtas-64</literal></emphasis> methods, then the platform shall
operate at the least functional level supported by the platform.</para>
<para>
<emphasis role="bold">Note:</emphasis> Platforms should provide a manual override
capability to allow most functional level allowed by the partition
configuration in the event that a client program does not call the
<emphasis role="bold"><literal>ibm,client-architecture-support</literal></emphasis> root node method
prior to the instantiation of RTAS.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>instantiate-rtas</literal></emphasis> (rtas-base-address -- rtas-call) [M]</term>
<listitem>
<para>Invoking the
<emphasis role="bold"><literal>instantiate-rtas</literal></emphasis> method binds the RTAS environment to
a given location in System Memory and initializes the RTAS environment.
The in parameter,
<emphasis>rtas-base-address</emphasis>, is the physical address to which
the RTAS environment is to be bound. This call indicates that RTAS is
instantiated in a 32-bit mode. The amount of contiguous real memory that
should be allocated for the RTAS environment is given by the value of the
<emphasis role="bold"><literal>&#8220;rtas-size&#8221;</literal></emphasis> property.</para>
<para>Upon completion of the
<emphasis role="bold"><literal>instantiate-rtas</literal></emphasis> method, an entry point address,
<emphasis>rtas-call</emphasis>, is returned. The value of
<emphasis>rtas-call</emphasis> specifies the physical address of the entry
point into RTAS for future RTAS function calls.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>instantiate-rtas-64</literal></emphasis> (rtas-base-address -- rtas-call) [M]</term>
<listitem>
<para>Invoking the optional
<emphasis role="bold"><literal>instantiate-rtas-64</literal></emphasis> method binds the RTAS environment
to a given location in System Memory and initializes the RTAS
environment. The in parameter,
<emphasis>rtas-base-address</emphasis>, is the physical address to which
the RTAS environment is to be bound. This call indicates that RTAS is
instantiated in a 64-bit mode. The amount of contiguous real memory that
should be allocated for the RTAS environment is given by the value of the
<emphasis role="bold"><literal>&#8220;rtas-size&#8221;</literal></emphasis> property.</para>
<para>Upon completion of the
<emphasis role="bold"><literal>instantiate-rtas-64</literal></emphasis> method, an entry point address,
<emphasis>rtas-call</emphasis>, is returned. The value of
<emphasis>rtas-call</emphasis> specifies the physical address of the entry
point into RTAS for future RTAS function calls.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
</section>
<section xml:id="dbdoclet.50569368_31401">
<title>Properties of the Node of type cpu</title>
<para>When the platform implements the LPAR option the following
properties are required of the /cpus node</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>ibm,pft-size</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> of the children of type
&#8220;cpu&#8221; of the
<emphasis>/cpus</emphasis> node, defines the size of the processor&#8217;s
page frame table.</para>
<para> <emphasis>prop-encoded-array</emphasis>: A pair of integers encoded as
with
<emphasis role="bold"><literal>encode-int</literal></emphasis>, the first being the NUMA CEC Cookie (up
to a maximum of (2
<emphasis>16</emphasis>)-1) the second being the base 2 log of the size
of the page frame table in bytes.</para>
<para>
<emphasis role="bold">Notes:</emphasis>
</para>
<orderedlist>
<listitem>
<para>On single CEC platforms, the NUMA CEC Cookie value is
zero.</para>
</listitem>
<listitem>
<para>Due to constraints caused by initial memory allocations, and
other running partitions, the firmware may not be able to allocate a
node&#8217;s PFT for the full size requested in the PFT_size
configuration variable. The
<emphasis role="bold"><literal>&#8220;ibm,pft-size&#8221;</literal></emphasis> property of course
reflects the actual size allocated.</para>
</listitem>
<listitem>
<para>The partitions running on multiple NUMA nodes would have
multiple PFTs which did not look alike due to the difference in mapping
local and remote page frames.)</para>
</listitem>
</orderedlist>
</listitem>
</varlistentry>
</variablelist>
<para>To support dynamic addition and removal of processors, the /cpus
node contains either the
<emphasis>ibm,drc-info</emphasis> property or the following set of four properties:
<emphasis>ibm,drc-types</emphasis> (cpu),
<emphasis>ibm,drc-indexes ibm,drc-names</emphasis> and
<emphasis>ibm,drc-power-domains</emphasis> (-1's). These properties have
entries for the maximum number of dynamically reconfigurable processors
that the platform supports for the specific OS image.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,ppc-interrupt-server#s&#8221;</literal></emphasis> [S]</term>
<listitem>
<para><emphasis>property name</emphasis>: Defines the single processor server
numbers associated with this processor. Placing the numerical equivalent
of one of these quantities into the server# field of an XIVR directs
associated interrupts to this processor. The first server number is
associated with the &#8220;primary processor thread&#8221; any subsequent
numbers are associated with the secondary. etc. hardware threads that the
processor may implement.</para>
<para><emphasis>prop-encoded-array</emphasis>: A list of one or more integers
in the range of 0 to
<literal>2</literal><superscript>&#8220;ibm,interrupt-server#-size&#8221;</superscript>
encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
<para><emphasis role="bold">Note:</emphasis> In order to achieve optimal performance,
processor server numbers should be activated in the order that they are
presented in the
<emphasis role="bold"><literal>&#8220;ibm,ppc-interrupt-server#s&#8221;</literal></emphasis> property and
deactivated in the reverse order.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,ppc-interrupt-gserver#s&#8221;</literal></emphasis> [S]</term>
<listitem>
<para><emphasis>property name</emphasis>: Defines the multiple processor global
server numbers to which this processor belongs. Placing the numerical
equivalent of one of these quantities into the server# field of an XIVR
directs associated interrupts to one of the processors in that
group.</para>
<para><emphasis>prop-encoded-array</emphasis>: A list of (
<emphasis>server#, gserver#s</emphasis>) specification pairs. the first
integer specifies a single processor
<emphasis>server#</emphasis> as presented in the node&#8217;s
<emphasis role="bold"><literal>&#8220;ibm,ppc-interrupt-server#s&#8221;</literal></emphasis> property,
followed by an integer with a value less than or equal to 2
<emphasis role="bold"><literal><superscript>&#8220;ibm,interrupt-server#-size&#8221;</superscript></literal></emphasis>
encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis> that specifies the global server queue
that also may present interrupts to the interrupt management area
associated with the
<emphasis>server#</emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,sub-processors&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis>: the sub-processor configuration that
is running on this processor. In the absence of this property, this
processor may not be divided into sub-processors.</para>
<para><emphasis>prop-encoded-array</emphasis>: a series of three or more
integers each encoded as with encode-int. The value of the first integer
indicates how many integers follow (the value 2 indicates that two
integers follow). The second integer indicates the number of
sub-processors that are running on this processor. If the processor is
not divided into sub-processors the value of the second integer shall be
1, two sub-processors shall be represented by the value 2, four
sub-processors shall be represented by the value 4 and so on. The third
integer indicates the maximum number of sub-processors that could be
configured to run on this processor.</para>
<para>Client programs shall ignore subsequent integers beyond those
defined at the time they were written.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section>
<title>Extensions for LoPAR I/O Sub-Systems</title>
<para>LoPAR I/O sub-system events may be signaled in a variety of ways
depending upon platform capabilities. In order of increasing
functionality:</para>
<orderedlist>
<listitem>
<para>Events are universally fatal, and are signaled via
checkstop.</para>
</listitem>
<listitem>
<para>After being enabled, the effected section enters freeze state
signalling this state with a return of all 1&#8217;s to any MMIO load
instruction (If not enabled functionality of the specific section reverts
to #1. Presence of
<emphasis>ibm,set-eeh-option</emphasis> RTAS call denotes platforms that
support this level of functionality.)</para>
</listitem>
<listitem>
<para>An extension to #2 above wherein, after being enabled for a
specific section of the I/O sub-system, additional event conditions may
be reported and events are signaled using an external interrupt. The
platform&#8217;s capability to support this level of functionality is
reported by the inclusion of the
<emphasis role="bold"><literal>&#8220;ibm,i/o-events-capable&#8221;</literal></emphasis> property (see
definition below) in nodes where enabling control may be
exercised.</para>
</listitem>
</orderedlist>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,i/o-events-capable&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> indicating that I/O sub-system events
detected by the hardware represented by this node in the device tree may
be singled with an I/O event interrupt if enabled.</para>
<para><emphasis>prop-encoded-array</emphasis>: 0 to N interrupt specifiers (per
the definition of interrupt specifiers for the node&#8217;s interrupt
parent).</para>
<para>When no interrupt specifiers are present, then the interrupt, if
enabled, is signaled via the interrupt specifier given in the
<emphasis role="bold"><literal>I/O-events</literal></emphasis> child node of the
<emphasis role="bold"><literal>/events</literal></emphasis> node.</para>
<para>To perform certain management functions, it is necessary to quiesce
segments of the platform&#8217;s I/O infrastructure, such quiescence
domains are not representable by a strict tree structure. The
<emphasis role="bold"><literal>&#8220;ibm,io-quiesce-domains&#8221;</literal></emphasis> property relates
the membership of the various elements of a platform&#8217;s I/O
sub-system to such quiescence domains.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,io-quiesce-domains&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> indicating the I/O quiesce domains of
which this device, and all devices under this device (if any), is a
member.</para>
<para><emphasis>prop-encoded-array</emphasis>: List of one or more
domain-id&#8217;s to which this device belongs, and to which all devices
under this device (if any) belongs. Domain-id's are encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
</listitem>
</varlistentry>
</variablelist>
<para>Virtual I/O that does not take up physical address locations is
represented in a device sub tree for which the
<emphasis role="bold"><literal>&#8220;#size-cells&#8221;</literal></emphasis> and
<emphasis role="bold"><literal>&#8220;#address-cells&#8221;</literal></emphasis> properties are zero and
one, respectively. However, the ibm dma-window properties, such as
<emphasis role="bold"><literal>&#8220;ibm,dma-window&#8221;</literal></emphasis> and
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis>, need to contain
real size and address fields. The number of cells for these real size and
address fields need to be non-zero.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,#dma-size-cells&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> to define the package&#8217;s dma
address
<emphasis>size</emphasis> format.</para>
<para><emphasis>prop-encoded-array</emphasis>: number encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
<para>The property value specifies the number of cells that are used to
encode the size field of ibm dma-window properties. If the
<emphasis role="bold"><literal>&#8220;ibm,#dma-size-cells&#8221;</literal></emphasis> property is
missing, the default value is the
<emphasis role="bold"><literal>&#8220;#size-cells&#8221;</literal></emphasis> property for the package.
If both the
<emphasis role="bold"><literal>&#8220;ibm,#dma-size-cells&#8221;</literal></emphasis> and
<emphasis role="bold"><literal>&#8220;#size-cells&#8221;</literal></emphasis> properties are missing,
refer to the
<emphasis role="bold"><literal>&#8220;#size-cells&#8221;</literal></emphasis> property definition in the
<xref linkend="dbdoclet.50569387_45524" /> for the default value.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,#dma-address-cells&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> to define the package&#8217;s dma
address format.</para>
<para><emphasis>prop-encoded-array</emphasis>: number encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
<para>The property value specifies the number of cells that are used to
encode the physical address field of ibm dma-window properties. If the
<emphasis role="bold"><literal>&#8220;ibm,#dma-address-cells&#8221;</literal></emphasis> property is
missing, the default value is the
<emphasis role="bold"><literal>&#8220;#address-cells&#8221;</literal></emphasis> property for the
package. If both the
<emphasis role="bold"><literal>&#8220;ibm,#dma-address-cells&#8221;</literal></emphasis> and
<emphasis role="bold"><literal>&#8220;#address-cells&#8221;</literal></emphasis> properties are missing,
refer to the
<emphasis role="bold"><literal>&#8220;#address-cells&#8221;</literal></emphasis> property definition in
the
<xref linkend="dbdoclet.50569387_45524" /> for the default value.</para>
</listitem>
</varlistentry>
</variablelist>
<section>
<title>PCI Host Bridge Nodes</title>
<para>This section describes the PCI Host Bridge (PHB) properties which
are added or modified for an LoPAR implementation. Refer to
<xref linkend="dbdoclet.50569387_22451" /> for the base PCI properties and
methods. For each platform PCI Host Bridge, a
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property shall be present in the
respective PCI Node.</para>
<para>
<emphasis role="bold">Note:</emphasis> Since the standard RTAS PCI configuration
access services do not have separate arguments identifying the PCI host
bridge to which a service applies, platforms with multiple PCI host
bridges must assign them unique bus numbers. An OS must not reassign bus
numbers if it expects to make subsequent use of the any RTAS PCI
configuration access services.</para>
<para>To support dynamic addition and removal of PHBs, the / node
contains either the
<emphasis>ibm,drc-info</emphasis> property or the following set of four properties:
<emphasis>ibm,drc-types</emphasis> (phb),
<emphasis>ibm,drc-indexes ibm,drc-names</emphasis> and
<emphasis>ibm,drc-power-domains</emphasis> (-1's). These properties have
entries for the maximum number of dynamically reconfigurable PHBs that
the platform supports for the specific OS image.</para>
<section xml:id="dbdoclet.50569368_43390">
<title>PCI Host Bridge Properties</title>
<para>For each PHB in the platform (called a PCI Bus Controller in the
<emphasis>PCI Bus binding</emphasis>), a PCI Host Bridge Node shall
be defined as a child node of the system bus, in
accordance with
<xref linkend="dbdoclet.50569387_22451" />. Each PCI PHB Node shall have
a Unit Address defined in the
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property that is unique and
persistent from each boot-to-boot. One way for the platform to meet this
requirement is to supply a virtual Unit Address based upon a unique
identifier stored in the hardware. In this case, the size field of the
first
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property phys-address, size pair
shall be zero. The following properties are modified or added by this
architecture and shall apply to each of these nodes.</para>
<para>Each PHB shall also have the
<emphasis role="bold"><literal>&#8220;used-by-rtas&#8221;</literal></emphasis> property, since RTAS is
used for PCI Configuration.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ranges&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> defines this PHB&#8217;s physical
address ranges.</para>
<para><emphasis>prop-encoded-array</emphasis>: Two or more (
<emphasis>child-phys, parent-phys, size</emphasis>)
specifications.</para>
<para>This property is mandatory for PCI Host Bridges in LoPAR
implementations. The property value consists of four (
<emphasis>child-phys, parent-phys, size</emphasis>) specifications, as
described in
<xref linkend="dbdoclet.50569387_45524" />.</para>
<para>The first specification shall specify the configured address and
size of this PHB&#8217;s I/O Space. (I/O Space is shown as
&#8220;BIOn&#8221; to &#8220;TIOn&#8221; in
<xref linkend="dbdoclet.50569328_Address-Map" />.) The
second specification shall specify the configured address and size of
this PHB&#8217;s Memory Space. (Memory Space is shown as
&#8220;BPMn&#8221; to &#8220;TPMn&#8221; in the Common Hardware Reference
Platform Architecture.)</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;model&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> indicating this PHB&#8217;s
manufacturer, part number, and revision level. This property shall be
present if this PHB does not supply the following standard PCI
configuration properties which represent the values of standard PCI
configuration registers:
<emphasis role="bold"><literal>&#8220;vendor-id&#8221;</literal></emphasis>,
<emphasis role="bold"><literal>&#8220;device-id&#8221;</literal></emphasis>, and
<emphasis role="bold"><literal>&#8220;revision-id&#8221;</literal></emphasis>.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: Text string, encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.</para>
<para>The value of this property is a vendor dependent string which
uniquely identifies this PHB and is correlated to its manufacturer, part
number, and revision level. (see
<xref linkend="dbdoclet.50569387_45524" /> for more information.) The
string value is device dependent, but shall supply information sufficient
to identify the part to a level equivalent to the level achievable via
the standard PCI configuration registers:
<emphasis role="bold"><literal>&#8220;vendor-id&#8221;</literal></emphasis>,
<emphasis role="bold"><literal>&#8220;device-id&#8221;</literal></emphasis>, and
<emphasis role="bold"><literal>&#8220;revision-id&#8221;</literal></emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;64-bit-addressing&#8221;</literal></emphasis> [S]</term>
<listitem>
<para><emphasis>property name</emphasis> indicates this PHB&#8217;s capability
to address more than 4 GB of memory.</para>
<para><emphasis>prop-encoded-array</emphasis>: &lt;none&gt;</para>
<para>This property shall be present indicating that the PHB supports
addressing more than 4 GB of memory (required for all
<emphasis role="bold"><literal>PHB</literal></emphasis> nodes).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;external-control&#8221;</literal></emphasis> [S]</term>
<listitem>
<para><emphasis>property name</emphasis> indicates this PHB&#8217;s ability to
support the PA external control facility.</para>
<para><emphasis>prop-encoded-int</emphasis>: List of integers, each encoded as
with <emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
<para>The property value, if present, is a list of Resource ID&#8217;s
the version of the PA external control facility supports. This property
shall be present if this PHB supports the PA external control facility,
otherwise the property shall be absent.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,tce-alloc-info&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> indicates the addresses of platform pre
allocated TCE table space.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: One to N
<emphasis>phys-addr, size</emphasis> pair(s). The first pair represents
the memory area allocated by the platform for the TCE tables associated
with this PHB. Any subsequent pairs represent memory areas that the OS
should avoid using to minimize performance impacts.</para>
<para><emphasis>Phys-addr</emphasis> is encoded as with
<emphasis role="bold"><literal>encode-phys</literal></emphasis> the number of cells for
<emphasis>phys</emphasis> corresponds to
<emphasis role="bold"><literal>&#8220;#address-cells&#8221;</literal></emphasis> value applicable to this
node.</para>
<para><emphasis>size</emphasis> the number of cells for
<emphasis>size</emphasis> corresponds to the
<emphasis role="bold"><literal>&#8220;#cell-size&#8221;</literal></emphasis> value applicable to this
node.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,max-completion-latency&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> indicates the maximum DMA Read
completion latency for IOAs under this PHB.</para>
<para><emphasis>prop-encoded-array</emphasis>: Integer, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
<para>This property, when present (for example, see Requirement
<xref linkend="dbdoclet.50569335_65475" />), indicates the maximum DMA
Read completion latency for IOAs under this PHB, in microseconds. For
plug-in adapters, the latency value does not include latency of any
additional PCI fabric (for example, PCI Express switches) on the plug-in
adapter.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,extended-address&#8221;</literal></emphasis> [S]</term>
<listitem>
<para><emphasis>property name</emphasis> indicates this platform supports
Peripheral Memory Spaces, Peripheral I/O Spaces, and SCA spaces above 4
GB.</para>
<para><emphasis>prop-encoded-array</emphasis>: &lt;none&gt;</para>
<para>This property must be present in all PHB nodes.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,pcie-link-width-stats&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> indicates the collection of PCI Express
link-width capabilities and measurements at the PE below the PHB.</para>
<para><emphasis>prop-encoded-array</emphasis>: 2 integers encoded with
<emphasis role="bold"><literal>encode-int</literal></emphasis></para>
<para>The first integer represents the maximum PCI Express lane-width at
the Partitionable Endpoint.</para>
<para>The second integer represents the actual PCI Express lane-width at
the Partitionable Endpoint.</para>
<para><emphasis role="bold">Implementation Note:</emphasis> In some cases, a PCIe device may
train at a different width depending on the speed capabilities of the
link.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,pcie-link-speed-stats&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> indicates the collection of PCI Express
link-speed capabilities and measurements at the PE below the PHB.</para>
<para><emphasis>prop-encoded-array</emphasis>: 2 integers encoded with
<emphasis role="bold"><literal>encode-int</literal></emphasis>. The value of each integer is
based on which bit is set to reflect link speed according to the Supported Link Speed Vector
segment of the Link Capabilities 2 Register as defined in the PCI Express Capability Structure
chapter of the <xref linkend="dbdoclet.50569387_66784" />. In the 3.0 version of that
specification, the supported values are 0x1 (bit 0) = 2.5 GT/s, 0x2 (bit 1) = 5.0 GT/s, and 0x4 (bit 2) = 8.0 GT/s.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,max-rtce-mappings&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis>: for platforms that support the hcall-migrate function
set and more than a single Redirected RDMA mapping per virtual TCE, this property indicates
that there are limits to the number if such multiple Redirected RDMA mappings when used
by children of this PHB as indicated by the property value.</para>
<para><emphasis>prop-encoded-array</emphasis>: Maximum number of Redirected RTCE mappings encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
</listitem>
</varlistentry>
</variablelist>
<section xml:id="dbdoclet.50569368_69645">
<title>Properties for Children of PCI Host Bridges</title>
<para>The following properties are defined for PCI host bridges and their
children.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;133mhz-capable&#8221;</literal></emphasis> [S]</term>
<listitem>
<para><emphasis>property name</emphasis>: The presence of this property
indicates the device&#8217;s capability of operating at 133 megahertz.
Only present if PCI-X Status Register bit 17 is set.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: None.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;266mhz-capable&#8221;</literal></emphasis> [S]</term>
<listitem>
<para><emphasis>property name</emphasis>: The presence of this property
indicates the device&#8217;s capability of operating at 266 megahertz.
Only present if PCI-X Status Register bit 30 is set.</para>
<para><emphasis>prop-encoded-array</emphasis>: None.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;533mhz-capable&#8221;</literal></emphasis> [S]</term>
<listitem>
<para><emphasis>property name</emphasis>: The presence of this property
indicates the device&#8217;s capability of operating at 533 megahertz.
Only present if PCI-X Status Register bit 31 is set.</para>
<para><emphasis>prop-encoded-array</emphasis>: None.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,msi-ranges&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis>: Defines the Message Signaled
Interrupt interrupt source number (as returned by H_XIRR) range(s)
assigned to this unit using the MSI capability structure. (Note this
property is only supplied if the package is assigned one or more message
signaled interrupt numbers at boot time using the MSI capability
structure, those packages assigned level sensitive interrupts include the
standard interrupts property.) The platform firmware assigns the
interrupt source numbers in order to the first N Message Signaled
Interrupt configuration spaces of the adapter, setting the associated
configuration spaces, in accordance with the platform's hardware
configuration, to produce the interrupt source numbers specified.</para>
<para><emphasis>prop-encoded-array</emphasis>: List of one or more (int-number,
range) specifications.</para>
<para><emphasis>Int-number</emphasis> is the first interrupt source number in a
contiguous range of interrupt source numbers encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
<para><emphasis>Range</emphasis> is the one based count of consecutive interrupt
source numbers that compose the specified range of interrupt source
numbers, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,msi-x-ranges&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> defines the Message Signaled Interrupt
interrupt source number (as returned by H_XIRR) range(s) assigned to this
IOA function using the MSI-X capability structure. (Note this property is
only supplied if the package is assigned one or more message signaled
interrupt numbers at boot time using MSI-X capability structure, those
packages assigned level sensitive interrupts include the standard
interrupts property.) The platform firmware assigns the interrupt source
numbers in order to the first N MSI-X vectors of the IOA function,
setting the associated configuration spaces and MSI-X vectors, in
accordance with the platform's hardware configuration, to produce the
interrupt source numbers specified.</para>
<para><emphasis>prop-encoded-array</emphasis>: List of one or more (int-number,
range) specifications.</para>
<para><emphasis>Int-number</emphasis> is the first interrupt source number in a
contiguous range of interrupt source numbers encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
<para><emphasis>Range</emphasis> is the one based count of consecutive interrupt
source numbers that compose the specified range of interrupt source
numbers, encoded as with encode-int.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,req#msi&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis>: Defines the number of Message
Signaled Interrupts requested by the adapter as communicated in its MSI
capability structure. This number may be greater than the number of
Message Signaled Interrupts actually assigned by the firmware.</para>
<para><emphasis>prop-encoded-array</emphasis>: number of requested interrupts
encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,req#msi-x&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis>: Defines the number of MSI-X Interrupts
requested by the adapter as communicated in the Table Size field of the
MSI-X Capability Structure for the adapter. This number may be greater
than the number of MSI-X interrupts actually assigned by the
firmware.</para>
<para><emphasis>prop-encoded-array</emphasis>: number of requested MSI-X
interrupts encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,connector-type&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> to identify the connectors associated with a built-in
IOA that supports wrap test. This property must be provided if there is
more than one connector for the same IOA on the platform.</para>
<para><emphasis>prop-encoded-array</emphasis>: the concatenation, with
<emphasis role="bold"><literal>encode+</literal></emphasis>, of an arbitrary number of text strings,
each encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,wrap-plug-pn&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> to provide the part number(s) of the wrap plug(s)
required for testing built-in IOAs with the default connector or the
connectors specified in
<emphasis role="bold"><literal>&#8220;ibm,connector-type&#8221;</literal></emphasis>. If this property
is provided in the same node with an
<emphasis role="bold"><literal>&#8220;ibm,connector-type&#8221;</literal></emphasis> property, there is a
one-to-one correspondence between the strings in each property. If this
property is provided without an
<emphasis role="bold"><literal>&#8220;ibm,connector-type&#8221;</literal></emphasis> property, there is
assumed to be only one connector for the device (default connector) and
this property should contain only one string. If multiple wrap plugs may
be used with the same connector, their part numbers shall be represented
in the same string, separated by commas.</para>
<para><emphasis>prop-encoded-array</emphasis>: the concatenation, with
<emphasis role="bold"><literal>encode+</literal></emphasis>, of an arbitrary number of text strings,
each encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,pci-config-space-type&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis>: Indicates if the platform supports
access to an extended configuration address space from the PHB up to and
including this node.</para>
<para>0 = Platform supports only an eight bit register number for
configuration address space accesses.</para>
<para>1 = Platform supports a twelve bit register number for
configuration address space accesses.</para>
<para>This property may be provided in all
<emphasis role="bold"><literal>PHB</literal></emphasis> nodes and their children.</para>
<para><emphasis role="bold">Note:</emphasis> The absence of this property implies the platform supports
only an eight bit register number for configuration address space
accesses.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,reserved-explanation&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> indicates why this PHB's
<emphasis role="bold"><literal>&#8220;status&#8221;</literal></emphasis> property contains the value of
<literal>&#8220;reserved&#8221;</literal> or
<literal>&#8220;reserved-uninitialized&#8221;</literal>.</para>
<para><emphasis>prop-encoded-array</emphasis>: Text string, encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.</para>
<para>The property value, when present, can have the values specified in
<xref linkend="dbdoclet.50569368_79030" />.</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569368_79030">
<title>Values
<emphasis role="bold"><literal>&#8220;ibm,reserved-explanation&#8221;</literal></emphasis></title>
<?dbhtml table-width="75%" ?>
<?dbfo table-width="75%" ?>
<tgroup cols="2">
<colspec colname="c1" colwidth="50*" align="center" />
<colspec colname="c2" colwidth="50*" align="center" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Value</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Explanation</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<row>
<entry>
<para>storage-system-io</para>
</entry>
<entry>
<para>Reserved for storage system product use</para>
</entry>
</row>
<row>
<entry>
<para>pcix-over-pcie</para>
</entry>
<entry>
<para>PCIe device is abstracted as a PCIx device in the device
tree for legacy compatibility</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,pe-total-#msi&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> defines the maximum number of Message
Signaled Interrupts (MSI plus MSI-X) that are available to the PE below
this device tree node. This number only indicates the number of available
interrupts, not the number assigned. The number assigned for an IOA may
be obtained by Function 0 (Query only) of the
<emphasis>ibm,change-msi</emphasis> RTAS call.</para>
<para><emphasis>prop-encoded-array</emphasis>: Maximum number of interrupts
encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,ehci-boot-supported&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis>: indicates if this IOA function for
USB 2.0 (EHCI) supports devices beneath it to be used for boot.</para>
<para><emphasis>prop-encoded-array</emphasis>: None.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,pe-reset-is-flr&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis>: The presence of this property in the
PCI Express function&#8217;s OF Device Tree node indicates that the
platform will use the Function Level Reset (FLR) of the function to reset
the function when the
<emphasis>ibm,set-slot-reset</emphasis> RTAS call is used to reset the PE,
and not the PCI Express Hot Reset.</para>
<para><emphasis>prop-encoded-array</emphasis>: None.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,ddw-applicable&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis>: The Dynamic DMA Windows option RTAS
calls may be used against the PE below this node.</para>
<para><emphasis>prop-encoded-array</emphasis>: A list of three integers encoded
as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
<para>This property may be provided in all PHB nodes or bridge nodes that
are the PHB&#8217;s children. Separate properties must exist for each PE
that can participate in the DDW option (exists in the node above the PE).
The existence of this property in any node, indicates that the platform
supports the Dynamic DMA Windows option for the platform and for the PE
below that node. Lack of this property in the bridge node above a PE
indicates that the DDW option RTAS calls are not applicable to that PE.
The values in the property are defined as follows:</para>
<para>The first integer represents the token to be used for the
<emphasis>ibm,query-pe-dma-window</emphasis> RTAS call.</para>
<para>The second integer represents the token to be used for the
<emphasis>ibm,create-pe-dma-window</emphasis> RTAS call.</para>
<para>The third integer represents the token to be used for the
<emphasis>ibm,remove-pe-dma-window</emphasis> RTAS call.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,ddw-extensions&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis>: Extensions to the Dynamic DMA Windows
option RTAS calls may be used against the PE below this node.</para>
<para><emphasis>prop-encoded-array</emphasis>: A list of integers encoded as
with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
<para>This property may be provided in all PHB nodes or bridge nodes that
are the PHB&#8217;s children. Separate properties shall exist for each PE
that can participate in the extensions to the DDW option (exists in the
node above the PE). The existence of this property in any node, indicates
that the platform supports the extensions to the Dynamic DMA Windows
option for the platform and for the PE below that node. Lack of this
property in the bridge node above a PE indicates that the extensions of
the DDW option RTAS calls are not applicable to that PE. This property is
designed to be extended in the future by adding integers to the end of
the list, reading software should be prepared to handle earlier versions
of the property that will have a short list as well as ignore longer
lists from later versions than it was designed to handle. The values in
the property are defined as follows:</para>
<para>The first integer represents the number of extensions implemented.
Subsequent integers represent values associated with each extension such
as a token for an additional RTAS call or an architectural level of an
extended interface. The value of one indicates that only a single
extension is implemented as specified by the second integer in the list.
<xref linkend="dbdoclet.50569332_25585" /> provides the definition of the
subsequent integers as defined for the LoPAR level of the DDW
option.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>ibm,h-get-dma-xlates-supported</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis>: to identify those PHBs for which
H_GET_DMA_XLATES is supported on all child LIOBNs.</para>
<para><emphasis>prop-encoded-array</emphasis>: &lt;none&gt;</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>ibm,h-get-dma-xlates-limited-supported</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis>: to identify those PHBs for which
H_GET_DMA_XLATES_LIMITED is supported on all child LIOBNs.</para>
<para><emphasis>prop-encoded-array</emphasis>: &lt;none&gt;</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="dbdoclet.50569368_94451">
<title>LPAR Option Properties</title>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,dma-window&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> to define the bus address window
children of this bridge may use for dma.</para>
<para><emphasis>prop-encoded-array</emphasis>: One (
<emphasis>logical-bus-number, phys</emphasis>,
<emphasis>size</emphasis>) triple where the logical bus number (LIOBN) is
a one cell cookie representing the unique range of TCE entries assigned
to this bridge encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>, the number of cells for
<emphasis>phys</emphasis> corresponds to the node&#8217;s
<emphasis role="bold"><literal>&#8220;ibm,#dma-address-cells&#8221;</literal></emphasis> value while the
number of cells for
<emphasis>size</emphasis> corresponds to the
<emphasis role="bold"><literal>&#8220;ibm,#dma-size-cells&#8221;</literal></emphasis> for this
node.</para>
<para><emphasis role="bold">Implementation Note:</emphasis> Platforms that support PHB level
granularity of IO assignment to partitions place the
<emphasis role="bold"><literal>&#8220;ibm,dma-window&#8221;</literal></emphasis> property in the PHB
node, while platforms that support slot level granularity place the
<emphasis role="bold"><literal>&#8220;ibm,dma-window&#8221;</literal></emphasis> property in the bridge
node that creates the per slot bus isolation.</para>
<para><emphasis role="bold">Note:</emphasis> The first element of the ibm,dma-window triple
(the LIOBN) is used as a parameter to firmware DMA setup routines to
identify the specific I/O address space (TCE table) to be
referenced.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,is-vf&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> to define that the node represents an
I/O Virtualized instance of an I/O adapter.</para>
<para><emphasis>prop-encoded-array</emphasis>: A one cell value that represents the LoPAR
architectural level of the virtualization:</para>
<table frame="all" pgwide="1">
<title>&#8220;<emphasis>ibm,is-vf</emphasis> &#8221; Values</title>
<?dbhtml table-width="50%" ?>
<?dbfo table-width="50%" ?>
<tgroup cols="2">
<colspec colname="c1" colwidth="50*" align="center" />
<colspec colname="c2" colwidth="50*" align="center" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Value:</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Description:</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<row>
<entry>
<para>0</para>
</entry>
<entry>
<para>Not used</para>
</entry>
</row>
<row>
<entry>
<para>1</para>
</entry>
<entry>
<para>Per LoPAR</para>
</entry>
</row>
<row>
<entry>
<para>All others</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>
</variablelist>
</section>
</section>
</section>
</section>
<section>
<title>Memory Node</title>
<para>This section defines the LoPAR modifications to the OF /
<emphasis>memory</emphasis> node. In LoPAR, the memory allocated to an OS
image may be divided into a number of allocation units called
&#8220;regions&#8221; or &#8220;Logical Memory Blocks (LMB). An OS image
may be dynamically allocated additional regions or may be asked to
release regions. Each LMB is either represented in the device tree by its
own /
<emphasis>memory</emphasis> node or by an entry in
<emphasis role="bold"><literal>/ibm,dynamic-reconfiguration-memory</literal></emphasis> nodes (see
<xref linkend="dbdoclet.50569368_28484" />). The /
<emphasis>memory</emphasis> node that refers to the storage starting at
real address zero (
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property starting at the value
zero) always remains allocated to an OS image. The client program is
initially loaded into this storage, called the RMA, that is represented
by the first value of the
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property of this first /
<emphasis>memory</emphasis> node. Additional storage regions may each be
represented by their own /
<emphasis>memory</emphasis> node that includes dynamic reconfiguration
(DR) properties or by an entry in <emphasis role="bold"><literal>/ibm,dynamic-reconfiguration-memory</literal></emphasis> nodes.</para>
<para>To support dynamic addition and removal of regions, the / node
contains either the
<emphasis>ibm,drc-info</emphasis> property or the following set of four properties:
<emphasis>ibm,drc-types</emphasis> (MEM),
<emphasis>ibm,drc-indexes ibm,drc-names</emphasis> and
<emphasis>ibm,drc-power-domains</emphasis> (-1's). These properties have
entries for the maximum number of dynamically reconfigurable regions that
the platform supports for the specific OS image.</para>
<section>
<title>Properties of the memory Node</title>
<para>In addition to the standard properties defined for the
<emphasis role="bold"><literal>/memory</literal></emphasis> node, the following are required for each
node representing a dynamically allocable memory region. Platforms that
support the dynamic reconfiguration of memory regions represent each such
logical memory block with its own
<emphasis role="bold"><literal>/memory</literal></emphasis> node. Any new memory granted to an OS image
is done so with a new
<emphasis role="bold"><literal>/memory</literal></emphasis> node, and OS images may free memory only in
full blocks represented by one of its currently held
<emphasis role="bold"><literal>/memory</literal></emphasis> nodes.</para>
<para>The value of
<emphasis role="bold"><literal>&#8220;#address-cells&#8221;</literal></emphasis>
for this node is 1.</para>
<para>The value of
<emphasis role="bold"><literal>&#8220;#size-cells&#8221;</literal></emphasis>
for this node is 0 because the children of this node do not consume any physical
address space.</para>
<para>The
<emphasis role="bold"><literal>&#8220;ibm,my-drc-index&#8221;</literal></emphasis> property as defined in
<xref linkend="dbdoclet.50569368_13582" />.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,preservable&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> that denotes the platform&#8217;s
ability to preserve the contents of the storage represented by this
node.</para>
<para><emphasis>prop-encoded-array</emphasis>: A integer encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis> that represents
the ability of the platform to preserve the contents of the storage.</para>
<para>All non-negative values represents the expected length of time, in
minutes, that the platform can sustain the state of the storage. A value
of 0 indicates the storage is not preservable and the client program may
not register this storage for preservation, this is the assumed state if the
<emphasis role="bold"><literal>&#8220;preservable&#8221;</literal></emphasis>
property is not present. The largest positive number represents an indefinite
retention time as provided by such technologies as flash storage.</para>
<para>Negative values indicate that the storage is preservable as long as
external power is maintained, perhaps by an external battery not directly
integrated into the platform.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,preserved&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> that denotes the preservation state of
the contents of the storage represented by this node.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: An integer encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis> that represents the preservation state of
the storage. The defined states are:</para>
<para>0= The storage was not registered for preservation and thus not
preserved. This is the assumed state if the
<emphasis role="bold"><literal>&#8220;preserved&#8221;</literal></emphasis> property is not present. This
is also the state if the platform has lost knowledge of the preservation
registration state of the storage.</para>
<para>1= The storage was registered for preservation and is has been
preserved since the client program last modified it.</para>
<para>2= The storage was registered for preservation, however, the
contents have not been preserved.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,expected#pages&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> that denotes the number of pages that
the client program is expected to use to virtually map the LMB
represented by this node.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: An integer encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis> that represents the log base 2 of the
expected number of virtual pages that the client program will use to map
the LMB represented by this node.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,no-h-migrate-dma&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> that designates that the memory in the
<emphasis>memory</emphasis> node in which this property resides cannot
have the H_MIGRATE_DMA hcall() used against it.</para>
<para><emphasis>prop-encoded-value</emphasis>: &lt;none&gt; this is a name only
property.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="dbdoclet.50569368_28484">
<title>ibm,dynamic-reconfiguration-memory</title>
<para>This device tree node defines an alternative means to represent a
number of dynamically-reconfigurable logical memory blocks (LMBs). This
node must only be generated by OF when instructed to do so by the client
program in the ELF header. All memory which is not subject to dynamic
reconfiguration (such as the RMA) is represented in
<emphasis role="bold"><literal>/memory</literal></emphasis> node(s).</para>
<para>This node is a child of root. This node does not have a unit
address or
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property.</para>
<para>The following properties are defined.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,lmb-size&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> that defines the size of each
dynamically reconfigurable LMB.</para>
<para><emphasis>prop-encoded-array</emphasis>: An integer encoded as with
<emphasis role="bold"><literal>encode-phys</literal></emphasis> that represents the size in bytes of each
LMB.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,associativity-lookup-arrays&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> that defines a lookup array in which to
find the
<emphasis>ibm,associativity-array</emphasis> property value for the
LMBs.</para>
<para><emphasis>prop-encoded-array</emphasis>: The number M of associativity
lists encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>, the number N of entries per
associativity list encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>, followed by M associativity lists each
of length N integers encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
<para>This property is used to duplicate the function of the
<emphasis role="bold"><literal>&#8220;ibm,associativity&#8221;</literal></emphasis> property in a
<emphasis role="bold"><literal>/memory</literal></emphasis> node. Each &#8220;assigned&#8221; LMB
represented has an index valued between 0 and M-1 which is used as in
index into this table to select which associativity list to use for the
LMB. &#8220;unassigned&#8221; LMBs are place holders for potential DLPAR
additions, for which the associativity list index is meaningless and is
given the reserved value of -1. This static property, need only contain
values relevant for the LMBs presented in the
<emphasis role="bold"><literal>&#8220;ibm,dynamicreconfiguration-memory&#8221;</literal></emphasis> node;
for a dynamic LPAR addition of a new LMB, the device tree fragment
reported by the
<emphasis>ibm,configure-connector</emphasis> RTAS function is a /memory
node, with the inclusion of the
<emphasis role="bold"><literal>&#8220;ibm,associativity&#8221;</literal></emphasis> device tree property
defined in
<xref linkend="dbdoclet.50569368_10192" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,dynamic-memory&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> that defines memory subject to dynamic
reconfiguration.</para>
<para><emphasis>prop-encoded-array</emphasis>: The number N of LMB list entries
defined at boot time, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>, followed by N LMB list entries.</para>
<para>An LMB list entry consists of the following elements. There is one
LMB list entry per LMB represented.</para>
<para>Logical address of the start of the LMB, encodes as with
<emphasis role="bold"><literal>encode-phys</literal></emphasis>. This corresponds to the first words in
the
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property in a
<emphasis role="bold"><literal>/memory</literal></emphasis> device tree node.</para>
<para>DRC index of the LMB, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>. This corresponds to the
<emphasis role="bold"><literal>&#8220;ibm,my-drc-index&#8221;</literal></emphasis> property in a
<emphasis role="bold"><literal>/memory</literal></emphasis> device tree node.</para>
<para>Four (4) bytes reserved for future expansion of flag.</para>
<para>Associativity list index for the LMB, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>. This is used as an index into
<emphasis role="bold"><literal>&#8220;ibm,associativity-lookup-arrays&#8221;</literal></emphasis>
property defined above to retrieve the associativity list for the LMB. The associativity
list corresponds to the
<emphasis role="bold"><literal>&#8220;ibm,associativity&#8221;</literal></emphasis> property in a
<emphasis role="bold"><literal>/memory</literal></emphasis> device tree node.</para>
<para>A flags word, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>. This word represents 32 boolean flags.
As of this definition, flag bits are defined to correspond to the
<emphasis role="bold"><literal>&#8220;ibm,preservable&#8221;</literal></emphasis> and
<emphasis role="bold"><literal>&#8220;ibm,preserved&#8221;</literal></emphasis> properties in a
<emphasis role="bold"><literal>/memory</literal></emphasis> device tree node. This definition allows for
additional flags to be added in the future.</para>
<para>The following bits in the &#8220;flags word&#8221; above are
defined.</para>
<table frame="all" pgwide="1" xml:id="table_flag_word">
<title>Flag Word</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="20*" align="center" />
<colspec colname="c2" colwidth="20*" align="center" />
<colspec colname="c3" colwidth="60*" />
<tbody valign="middle" >
<row>
<entry>
<para>Name</para>
</entry>
<entry>
<para>Bit Position</para>
</entry>
<entry align="center">
<para>Description</para>
</entry>
</row>
<row>
<entry>
<para>preserved</para>
</entry>
<entry>
<para>0x00000001</para>
</entry>
<entry>
<para>If b'0', corresponds to the
<emphasis role="bold"><literal>&#8220;ibm,preserved&#8221;</literal></emphasis> property having
a zero value.</para>
<para>If b'1', corresponds to the
<emphasis role="bold"><literal>&#8220;ibm,preserved&#8221;</literal></emphasis> property having
a non-zero value, and the preserved_state bit below indicates
the state of preservation.</para>
</entry>
</row>
<row>
<entry>
<para>preservable</para>
</entry>
<entry>
<para>0x00000002</para>
</entry>
<entry>
<para>If b'0', corresponds to the
<emphasis role="bold"><literal>&#8220;ibm,preservable&#8221;</literal></emphasis> property
having a zero value.</para>
<para>If b'1', corresponds to the
<emphasis role="bold"><literal>&#8220;ibm,preservable&#8221;</literal></emphasis> property
having a non-zero value.</para>
</entry>
</row>
<row>
<entry>
<para>preserved_state</para>
</entry>
<entry>
<para>0x00000004</para>
</entry>
<entry>
<para>If b'0', corresponds to the
<emphasis role="bold"><literal>&#8220;ibm,preserved&#8221;</literal></emphasis> property having
a 0x1 value.</para>
<para>If b'1', corresponds to the
<emphasis role="bold"><literal>&#8220;ibm,preserved&#8221;</literal></emphasis> property having
a 0x2 value (and, in the old binding, the LMB having a status
of &#8220;fail&#8221;).</para>
</entry>
</row>
<row>
<entry>
<para>assigned</para>
</entry>
<entry>
<para>0x00000008</para>
</entry>
<entry>
<para>If b'1', this LMB is assigned to the partition as of boot
time. If b'0', this LMB is not assigned to the partition as of
boot time.</para>
</entry>
</row>
<row>
<entry>
<para>No H_MIGRATE_DMA</para>
</entry>
<entry>
<para>0x00000010</para>
</entry>
<entry>
<para>If b'0', corresponds to non-existence of the
<emphasis role="bold"><literal>&#8220;ibm,no-h-migrate-dma&#8221;</literal></emphasis> in the
<emphasis>memory</emphasis> node.</para>
<para>If b'1', corresponds to existence of the
<emphasis role="bold"><literal>&#8220;ibm,no-h-migrate-dma&#8221;</literal></emphasis> in the
<emphasis>memory</emphasis> node.</para>
</entry>
</row>
<row>
<entry>
<para>DRC invalid</para>
</entry>
<entry>
<para>0x00000020</para>
</entry>
<entry>
<para>If b'0', the DRC field of
<emphasis role="bold"><literal>&#8220;ibm,dynamic-memory&#8221;</literal></emphasis> property
is valid or the DRC values for the set of
<emphasis role="bold"><literal>&#8220;ibm,dynamic-memory-v2&#8221;</literal></emphasis>
property are valid.</para>
<para>If b'1', the DRC field of
<emphasis role="bold"><literal>&#8220;ibm,dynamic-memory&#8221;</literal></emphasis> property
is invalid or the DRC values for the set of
<emphasis role="bold"><literal>&#8220;ibm,dynamic-memory-v2&#8221;</literal></emphasis>
property are invalid.</para>
</entry>
</row>
<row>
<entry>
<para>Associativity Index</para>
</entry>
<entry>
<para>0x00000040</para>
</entry>
<entry>
<para>If b'0', the Associativity List Index field of
<emphasis role="bold"><literal>&#8220;ibm,dynamic-memory&#8221;</literal></emphasis> property
or <emphasis role="bold"><literal>&#8220;ibm,dynamic-memory-v2&#8221;</literal></emphasis> is valid.</para>
<para>If b'1', the Associativity List Index field of
<emphasis role="bold"><literal>&#8220;ibm,dynamic-memory&#8221;</literal></emphasis> property
or <emphasis role="bold"><literal>&#8220;ibm,dynamic-memory-v2&#8221;</literal></emphasis> is invalid.</para>
</entry>
</row>
<row>
<entry>
<para>Reserved Memory</para>
</entry>
<entry>
<para>0x00000080</para>
</entry>
<entry>
<para>If b'0', corresponds to the
<emphasis role="bold"><literal>&#8220;status&#8221;</literal></emphasis> property having a
value of &#8220;okay&#8221;.</para>
<para>If b'1', corresponds to the
<emphasis role="bold"><literal>&#8220;status&#8221;</literal></emphasis> property having a
value of &#8220;reserved&#8221;.</para>
</entry>
</row>
<row>
<entry>
<para>Hot-removable Memory</para>
</entry>
<entry>
<para>0x00000100</para>
</entry>
<entry>
<para>If b'1', this LMB can be &#8220;hot-removed&#8221;.</para>
<para>If b'0', this LMB may fail to be &#8220;hot-removed&#8221;.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,dynamic-memory-v2&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> that defines memory subject to dynamic
reconfiguration with data in version 2 format.</para>
<para><emphasis>prop-encoded-array</emphasis>: The number N of LMB set entries, encoded with
<emphasis role="bold"><literal>encode-int</literal></emphasis>,
followed by N LMB set entries.</para>
<para>The <emphasis>number-of-sequential-lmbs</emphasis> encoded with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.
The number of LMBs in the set.</para>
<para>The <emphasis>starting-logical-address</emphasis> encoded with
<emphasis role="bold"><literal>encode-phys</literal></emphasis>.
The logical address of the first LMB in the set.</para>
<para>The <emphasis>starting-drc-index</emphasis> encoded with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.
The drc-index of the first LMB in the set.</para>
<para>The <emphasis>associativity-index</emphasis> encoded with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.
All LMBs within the set share the same associativity.</para>
<para>The <emphasis>flags</emphasis> word encoded with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.
All LMBs within the set share the same flag value. The bits in the flags word are defined in
<xref linkend="table_flag_word" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,memory-flags-mask&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> that defined which flags in the
&#8220;flags word&#8221; above are defined in this version of this
architecture.</para>
<para><emphasis>prop-encoded-array</emphasis>: An integer encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis> with all flag bits recognized by this
version of this architecture having a b'1' value. For this version, the
value will be 0x000000FF.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,memory-preservation-time&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> that defined the time value that would
appear in the
<emphasis role="bold"><literal>&#8220;ibm,preservable&#8221;</literal></emphasis> property in the old
bindings for a preservable LMB.</para>
<para><emphasis>prop-encoded-array</emphasis>: An integer value encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis> that represents the expected length of
time, in minutes, that the platform can sustain the state of power for a
preservable LMB. The largest positive number represents an indefinite
retention time as provided by such technologies as flash storage. A value
zero indicates that no memory will be marked as preservable.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
</section>
<section>
<title>Memory Controller Nodes</title>
<para>This section describes
<emphasis role="bold"><literal>memory-controller</literal></emphasis> nodes and their properties. NUMA
configurations, have multiple
<emphasis role="bold"><literal>memory-controller</literal></emphasis> nodes in the device tree one for
each Central Electronics Complex (CEC). In dynamic reconfiguration NUMA
environments, these
<emphasis>/memory-controller</emphasis> nodes are subject to standard
LoPAR dynamic reconfiguration operations and contain standard LoPAR
dynamic reconfiguration properties.</para>
<section>
<title>Memory Controller Node Properties</title>
<para>No nodes of type
<emphasis role="bold"><literal>memory-controller</literal></emphasis> shall be defined anywhere in the
device tree when the platform fully abstracts the memory controller and
the OS has no access to the memory controller (typically when running in
a partition). Otherwise, one or more nodes of type
<emphasis role="bold"><literal>memory-controller</literal></emphasis> shall be defined as a child of
&#8220;/&#8221; (the root) and shall not have a
<emphasis role="bold"><literal>&#8220;ranges&#8221;</literal></emphasis> property. The following
properties shall apply to each of these nodes. If the platform does not
abstract the functions of a platform's multiple memory controllers via
firmware (such as RTAS) then the platform shall
include a node of type
<emphasis role="bold"><literal>memory-controller</literal></emphasis> for each Memory Controller in the
platform.</para>
<para>A Memory Controller can also have the
<emphasis role="bold"><literal>&#8220;used-by-rtas&#8221;</literal></emphasis> property (see
<xref linkend="dbdoclet.50569368_31220" />), if it has functions
abstracted by RTAS.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;device_type&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard <emphasis>property name</emphasis> that denotes a Memory Controller
node.</para>
<para><emphasis>prop-encoded-array</emphasis>: A string, encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.</para>
<para>The value of this property shall be
<literal>&#8220;memory-controller&#8221;</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> defines the base physical address and
size of this Memory Controller&#8217;s addressable register space.</para>
<para><emphasis>prop-encoded-array</emphasis>: One (
<emphasis>phys-address, size</emphasis>) pair where
<emphasis>phys-address</emphasis> is encoded as with
<emphasis role="bold"><literal>encode-phys</literal></emphasis>, and
<emphasis>size</emphasis> is encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
<para>The property value shall be the base physical address and size of
this Memory Controller&#8217;s register space.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;model&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard <emphasis>property name</emphasis> indicating this Memory
Controller&#8217;s manufacturer, part number and revision level.</para>
<para><emphasis>prop-encoded-array</emphasis>: Text string, encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.</para>
<para>The value of this property is a vendor dependent string which
uniquely identifies this Memory Controller and shall be correlated to its
manufacturer, part number, and revision level. (see Core document for
more information.)</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;external-control&#8221;</literal></emphasis> [S]</term>
<listitem>
<para><emphasis>property name</emphasis> indicates this Memory
Controller&#8217;s ability to support the PA external control
facility.</para>
<para><emphasis>prop-encoded-int</emphasis>: List of integers, each encoded as
with <emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
<para>The property value, if present, is a list of Resource ID&#8217;s
the version of the PA external control facility supports. This property
shall be present if this Memory Controller supports the PA external
control facility, otherwise the property shall be absent.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;error-checking&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard <emphasis>property name</emphasis> defines the error checking capability
of the node.</para>
<para><emphasis>prop-encoded-array</emphasis>: a string, encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>, where the value could equal
&#8220;none&#8221;, &#8220;ecc&#8221;, or &#8220;parity&#8221;.</para>
<para>The value of
<emphasis role="bold"><literal>&#8220;#address-cells&#8221;</literal></emphasis>
for this node is 1.</para>
<para>The value of
<emphasis role="bold"><literal>&#8220;#size-cells&#8221;</literal></emphasis> for this node is 0 because
the children of this node do not consume any physical address
space.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
</section>
<section>
<title><literal>IBM,memory-module</literal> Nodes</title>
<para>Memory packaged on DIMMs or DIMM like modules are represented in
the device tree with
<emphasis role="bold"><literal>IBM,memory-module</literal></emphasis> nodes. These nodes represent
physical packages, these packages do not necessarily map directly to a
memory address range.</para>
<para>No nodes of type
<emphasis role="bold"><literal>IBM,memory-module</literal></emphasis> shall be defined anywhere in the
device tree when the platform supports dynamic VPD via the RTAS
<emphasis>ibm,get-vpd</emphasis> service. Instead the VPD that would
normally be reported via the
<emphasis role="bold"><literal>&#8220;ibm,vpd&#8221;</literal></emphasis> property in these nodes shall
be reported by
<emphasis>ibm,get-vpd</emphasis>.</para>
<section xml:id="dbdoclet.50569368_27720">
<title>Properties for Memory Modules</title>
<para>Memory modules appear as children of the
<emphasis>memory</emphasis> node or, for platforms supporting memory DR
operations (either logical or physical), the
<emphasis role="bold"><literal>memory-controller</literal></emphasis> node of the device tree. This
section defines properties for the
<emphasis role="bold"><literal>IBM,memory-module</literal></emphasis> nodes and additional properties for
the
<emphasis>memory</emphasis> and
<emphasis role="bold"><literal>memory-controller</literal></emphasis> nodes.</para>
</section>
<section>
<title><literal>IBM,memory-module</literal> Node Properties</title>
<para>An
<emphasis role="bold"><literal>IBM,memory-module</literal></emphasis> node is a child of the
<emphasis>memory</emphasis> node or, for platforms supporting memory DR
operations (either logical or physical), the
<emphasis role="bold"><literal>memory-controller</literal></emphasis> node.</para>
<para>The
<emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis>
of the node is &#8220;IBM,memory-module&#8221;</para>
<para>The
<emphasis role="bold"><literal>&#8220;device_type&#8221;</literal></emphasis>
of the node is &#8220;IBM,memory-module&#8221;</para>
<para>The
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis>
standard property for an
<emphasis role="bold"><literal>IBM,memory-module</literal></emphasis> node is its memory module number
which is an arbitrary OF selected enumeration.</para>
<para>The
<emphasis role="bold"><literal>&#8220;ibm,size&#8221;</literal></emphasis>
property for an
<emphasis role="bold"><literal>IBM,memory-module</literal></emphasis> node is an integer which is less
than 4GB and which by itself indicates the size of the memory module, in
bytes, if the memory module is smaller than 4GB and if
<emphasis role="bold"><literal>&#8220;status&#8221;</literal></emphasis> is
<emphasis role="bold"><literal>&#8220;okay&#8221;</literal></emphasis> or
<emphasis role="bold"><literal>&#8220;fail&#8221;</literal></emphasis>.</para>
<para>If the memory module is larger than or equal to 4GB in size, then
the
<emphasis role="bold"><literal>&#8220;ibm,size-upper&#8221;</literal></emphasis>
property for an
<emphasis role="bold"><literal>IBM,memory-module</literal></emphasis> node is present in addition to the
<emphasis role="bold"><literal>&#8220;ibm,size&#8221;</literal></emphasis> property. This property is an
integer which is multiplied times 4GB and then added to the value of the
<emphasis role="bold"><literal>&#8220;ibm,size&#8221;</literal></emphasis> property to get the size of
the module, in bytes. The property
<emphasis role="bold"><literal>&#8220;ibm,size-upper&#8221;</literal></emphasis> is not required if the
memory module size is less than 4GB.</para>
<para>The
<emphasis role="bold"><literal>&#8220;status&#8221;</literal></emphasis>
standard property for an
<emphasis role="bold"><literal>IBM,memory-module</literal></emphasis> node may have one of the following
string values:</para>
<itemizedlist>
<listitem>
<para><emphasis role="bold"><literal>&#8220;okay&#8221;</literal></emphasis> for a good memory module</para>
</listitem>
<listitem>
<para><emphasis role="bold"><literal>&#8220;fail&#8221;</literal></emphasis> for a bad memory module</para>
</listitem>
<listitem>
<para><emphasis role="bold"><literal>&#8220;fail-no-matched-pair&#8221;</literal></emphasis> for a missing
memory module if one of a pair is missing</para>
</listitem>
<listitem>
<para><emphasis role="bold"><literal>&#8220;fail-unsupport&#8221;</literal></emphasis> for an unsupported
memory module</para>
</listitem>
<listitem>
<para><emphasis role="bold"><literal>&#8220;fail-partial&#8221;</literal></emphasis> for a bad memory module
where part of the memory on the module is bad and has not been configured
and part of the memory is good and has been configured.</para>
</listitem>
<listitem>
<para>
<emphasis role="bold"><literal>&#8220;fail-excess-memory&#8221;</literal></emphasis> for
<emphasis role="bold"><literal>&#8220;okay&#8221;</literal></emphasis> memory modules that are not
configured because they exceed the system memory addressability of the
platform.</para>
</listitem>
<listitem>
<para>
<emphasis role="bold"><literal>&#8220;disabled&#8221;</literal></emphasis> for a memory module that has
been manually deconfigured.</para>
</listitem>
</itemizedlist>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,mem-banks&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> defines the number of memory banks
contained within the memory module.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: an integer, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>, which describes whether this is a 1, 2,
or 4-bank module, with a corresponding value of 1, 2 or 4 and so on to
match the number of banks in the physical device.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,mem-type&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> defines the memory module type.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: a string, encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>, that describes the type of module,
with values of
<emphasis role="bold"><literal>&#8220;FP&#8221;</literal></emphasis> (Fast Page),
<emphasis role="bold"><literal>&#8220;EDO&#8221;</literal></emphasis> (Extended Data Out), or
<emphasis role="bold"><literal>&#8220;SDRAM&#8221;</literal></emphasis> (Synchronous DRAM).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,mem-err-det&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> defines the type of error detection
mechanism supported by the module</para>
<para><emphasis>prop-encoded-array</emphasis>: a string, encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>, with values of
<emphasis role="bold"><literal>&#8220;none&#8221;</literal></emphasis>,
<emphasis role="bold"><literal>&#8220;parity&#8221;</literal></emphasis>, or
<emphasis role="bold"><literal>&#8220;ECC&#8221;</literal></emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,mem-speed&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> defines the access or clock speed
supported by the module, in picoseconds</para>
<para>
<emphasis>prop-encoded-array</emphasis>: an integer, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>, which describes the access or clock
speed supported by the module, in picoseconds.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
</section>
<section>
<title>Interrupt Controller Nodes</title>
<para>This section describes the properties for the LoPAR interrupt
controller node. If an interrupt controller node includes the
<emphasis role="bold"><literal>&#8220;used-by-rtas&#8221;</literal></emphasis> property, then the
platform includes firmware code for accessing the interrupt
controller.</para>
<para>For LSIs, the platform shall adhere to the
<xref linkend="dbdoclet.50569387_67880" /> interrupt structure OF
representation.</para>
<para>PAPR may support one of two generations of interrupt controllers with
backward compatible firmware interfaces. The first generation interrupt
controller is represented per
<xref linkend="sec_powerpc_external_interrupt_controller_nodes" />
and its sub sections.
The second generation, External Interrupt Virtualization Engine is
represented either per
<xref linkend="sec_powerpc_external_interrupt_controller_nodes" />
when operated in Legacy Compatibility mode, or per
<xref linkend="sec_powerpc_external_interrupt_virtualization_engine_node" />
and its sub sections when operated in Exploitation mode.</para>
<section xml:id="sec_powerpc_external_interrupt_controller_nodes">
<title>PowerPC External Interrupt Controller Nodes</title>
<para>This section describes the properties for the PowerPC External
Interrupt Controller nodes. PowerPC interrupt controllers are normally
packaged inside other system chips, however, they are logically
represented in the device tree by two or more independent interrupt
controller nodes. Each node reports either the interrupt source layer
resources that are housed in a single Bus Unit Controller (BUC) e.g. host
bridge, or logical equivalent, or a subset of the resources associated
with the platform&#8217;s interrupt presentation layer. The node per BUC
and presentation layer subset divisions provides a foundation for dynamic
reconfiguration.</para>
<para>At a dynamic reconfiguration event, such as adding an IO drawer, or
removing a processor, the interrupt controller nodes associated with the
added or removed hardware will also be added or removed. Therefore.
platforms should report, in individual nodes, each interrupt controller
that occupies a separate physical package. And OSs should expect a fine
granularity of interrupt controller reporting.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,interrupt-domain&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> that denotes a PowerPC External
Interrupt Domain</para>
<para><emphasis>prop-encoded-array</emphasis>: An integer encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
</listitem>
</varlistentry>
</variablelist>
<section xml:id="dbdoclet.50569368_26927">
<title>PowerPC External Interrupt Presentation Controller Node
Properties</title>
<para>The following properties apply to this node.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> that denotes a PowerPC External
Interrupt Controller.</para>
<para><emphasis>prop-encoded-array</emphasis>: A string, encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.</para>
<para>The value of this string shall be
<literal>&#8220;interrupt-controller&#8221;</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;device_type&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> that indicates an Interrupt
Controller.</para>
<para><emphasis>prop-encoded-array</emphasis>: A string, encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.</para>
<para>The value of this property shall be
<literal>&#8220;PowerPC-External-Interrupt-Presentation&#8221;</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> defines the base physical address(s)
and size(s) of this PowerPC External Interrupt Presentation layer&#8217;s
registers.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: List of (
<emphasis>phys-addr, size</emphasis>
<emphasis>)</emphasis> specifications.</para>
<para>
<emphasis>Phys-addr</emphasis> is encoded as with
<emphasis role="bold"><literal>encode-phys</literal></emphasis>, and
<emphasis>size</emphasis> is encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
<para>The entries shall represent the base address of a single set of
PowerPC External Interrupt Presentation Layer Registers of the Interrupt
Management Area. There shall be one entry for each interrupt server queue
supported by this unit. The order of the entries shall correspond to the
entries in the
<emphasis role="bold"><literal>&#8220;ibm,interrupt-server-ranges&#8221;</literal></emphasis> property
described below.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;compatible&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> to define alternate
<emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis> property values.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: The concatenation, with
<emphasis role="bold"><literal>encode+</literal></emphasis>, of an arbitrary number of text strings,
each encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.</para>
<para>The property value shall include
<emphasis role="bold"><literal>&#8220;IBM,ppc-xicp&#8221;</literal></emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,interrupt-buid-size&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis>: Defines the number of bits
implemented in the concatenation of the BUID fields.</para>
<para>
<emphasis>prop-encoded-value</emphasis>: An integer in the range of 9 to
20 encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
<para>As platforms grow in size so as to require use of larger BUIDs
(values of the
<emphasis role="bold"><literal>&#8220;ibm,interrupt-buid-size&#8221;</literal></emphasis>
property greater than 9) the platform engineers need to interlock with their OS
providers to ensure support.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,interrupt-server-ranges&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>Property name</emphasis> that defines the interrupt server
number(s) and range(s) handled by this unit.</para>
<para><emphasis>prop-encoded-array</emphasis>: List of (<emphasis>server#, range</emphasis>) specifications.</para>
<para><emphasis>Server#</emphasis> is encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis> in the range of 0 - 2
<superscript>the largest value of the
&#8220;ibm,interrupt-server#-size&#8221; property contained in the device
tree</superscript>.</para>
<para><emphasis>Range</emphasis> is encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
<para>The first entry in this list shall contain the
<emphasis>server#</emphasis> associated with the first
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property entry. The
<emphasis>server#</emphasis> corresponds to a value of a processor&#8217;s
<emphasis role="bold"><literal>&#8220;ibm,ppc-interrupt-server#s&#8221;</literal></emphasis> property.
The range shall be the number of contiguous
<emphasis>server#</emphasis> s supported by the unit (this also
corresponds to the number of
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> entries).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;interrupt-controller&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> to indicate an interrupt (sub-)tree
root.</para>
<para><emphasis>prop-encoded-array</emphasis>: &lt;none&gt; The presence of
this property indicates that this node represents an interrupt
controller.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;model&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> indicating this unit&#8217;s
manufacturer, part number, and revision level.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: Text string, encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.</para>
<para>The value of this property shall be a string which uniquely
identifies the interrupt controller and shall be correlated to the
manufacturer, part number, and revision level. This value is device
dependent (see the Core document for more information).</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="dbdoclet.50569368_69563">
<title>PowerPC External Interrupt Source Controller Node
Properties</title>
<para>Interrupt source controller resources as represented by
<emphasis role="bold"><literal>&#8220;interrupt-ranges&#8221;</literal></emphasis>,
<emphasis role="bold"><literal>&#8220;#interrupt-cells&#8221;</literal></emphasis>, and
<emphasis role="bold"><literal>&#8220;ibm,interrupt-server#-size&#8221;</literal></emphasis> properties
may be reported in stand-alone interrupt source controller nodes or in
other logical equivalent nodes which contain the
<emphasis role="bold"><literal>&#8220;interrupt-controller&#8221;</literal></emphasis> property. The
following properties apply to these nodes.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> that denotes a PowerPC External
Interrupt Controller.</para>
<para><emphasis>prop-encoded-array</emphasis>: A string, encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.</para>
<para>The value of this string shall be
<literal>&#8220;interrupt-controller&#8221;</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;device_type&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> that indicates the specific flavor of
Interrupt Source Controller.</para>
<para><emphasis>prop-encoded-array</emphasis>: A string, encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.</para>
<para>The value of this property shall be one of the following:</para>
<para><literal>&#8220;PowerPC-LSI-Source&#8221;</literal><?linebreak?>
For Level Sensitive Interrupt source controllers.</para>
<para><literal>&#8220;PowerPC-MSI-Source&#8221;</literal><?linebreak?>
For Message Sensitive Interrupt source controllers such as used
with PCI MSI.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> defines the base physical address(s)
and size(s) of this PowerPC External Interrupt Source if any.</para>
<para><emphasis>prop-encoded-array</emphasis>: List of (
<emphasis>phys-addr, size</emphasis>) specifications.</para>
<para><emphasis>Phys-addr</emphasis> is encoded as with
<emphasis role="bold"><literal>encode-phys</literal></emphasis>, and
<emphasis>size</emphasis> is encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
<para>If the
<emphasis role="bold"><literal>&#8220;device-type&#8221;</literal></emphasis> of the interrupt source
controller is
<emphasis role="bold"><literal>&#8220;PowerPC-MSI-Source&#8221;</literal></emphasis>, then the last
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> entry shall correspond to the
interrupt controller&#8217;s 4 byte Message Interrupt Input Port.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;compatible&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> to define alternate
<emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis> property values.</para>
<para><emphasis>prop-encoded-array</emphasis>: The concatenation, with
<emphasis role="bold"><literal>encode+</literal></emphasis>, of an arbitrary number of text strings,
each encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.</para>
<para>The property value shall include
<emphasis role="bold"><literal>&#8220;ibm,ppc-xics&#8221;</literal></emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;interrupt-ranges&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> that defines the interrupt number(s)
and range(s) handled by this unit.</para>
<para><emphasis>prop-encoded-array</emphasis>: List of (
<emphasis>int-number, range</emphasis>) specifications.</para>
<para><emphasis>Int-number</emphasis> is encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
<para>
<emphasis>Range</emphasis> is encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
<para>The first entry in this list shall contain the
<emphasis>int-number</emphasis> associated with the first
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property entry. The
<emphasis>int-number</emphasis> is the value representing the interrupt
source as would appear in the PowerPC External Interrupt Architecture
XISR. The range shall be the number of sequential interrupt numbers which
this unit can generate.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;interrupt-controller&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> to indicate an interrupt (sub-)tree
root.</para>
<para><emphasis>prop-encoded-array</emphasis>: &lt;none&gt; The presence of
this property indicates that this node represents an interrupt
controller.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;model&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> indicating this unit&#8217;s
manufacturer, part number, and revision level.</para>
<para><emphasis>prop-encoded-array</emphasis>: Text string, encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.</para>
<para>The value of this property shall be a string which uniquely
identifies the interrupt controller and shall be correlated to the
manufacturer, part number, and revision level. This value is device
dependent (see the Core document for more information).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;#interrupt-cells&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard <emphasis>property name</emphasis> to define the number of cells in an
<emphasis>interrupt-specifier</emphasis> within an interrupt
domain.</para>
<para><emphasis>prop-encoded-array</emphasis>: An integer, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>, that denotes the number of cells
required to represent an interrupt specifier in its child nodes.</para>
<para>The value of this property for the PowerPC External Interrupt
option shall be 2. Thus all interrupt specifiers (as used in the standard
<emphasis role="bold"><literal>&#8220;interrupts&#8221;</literal></emphasis> property) shall consist of
two cells, each containing an integer encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>. The first integer represents the
interrupt number the second integer is the trigger code: 0 for edge
triggered, 1 for level triggered.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,interrupt-server#-size&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis>: Defines the number of bits
implemented in the concatenation of the server#extension and server#
fields.</para>
<para><emphasis>prop-encoded-value</emphasis>: An integer in the range of 8 to
24 encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
<para>As platforms grow in size so as to require use of the
server#extension field (values of the
<emphasis role="bold"><literal>&#8220;ibm,interrupt-server#-size&#8221;</literal></emphasis>
property greater than 8) the platform engineers need to interlock with their OS
providers to ensure support.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
</section>
<section xml:id="sec_powerpc_external_interrupt_virtualization_engine_node">
<title>PowerPC External Interrupt Virtualization Engine Nodes</title>
<para>This section describes the properties for the External Interrupt Virtualization
node. Interrupt controllers are normally packaged inside system chips, however,
they are logically represented in the device tree by the interrupt controller
node. This node reports the logical real addresses through which the client
program can manage the interrupt context for its physical processor thread.</para>
<para>Event source resources consist of either a single or pair of page addresses
associated with each individual event source that is allocated to the partition.
These addresses do not appear in the device tree; rather the platform provides
the hcall(), H_INT_GET_SOURCE_INFO.</para>
<para>At a dynamic reconfiguration event, such as adding or removing an IO adapter,
or processor, the associated
<emphasis role="bold"><literal>&#8220;int&#8221;</literal></emphasis>
property is added or removed from the partition
configuration and along with it the associated page addresses.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> that denotes a PowerPC External
Interrupt Controller.</para>
<para><emphasis>prop-encoded-array</emphasis>: A string, encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.</para>
<para>The value of this string shall be
<literal>&#8220;interrupt-controller&#8221;</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;device_type&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> that indicates an Interrupt
Controller.</para>
<para><emphasis>prop-encoded-array</emphasis>: A string, encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.</para>
<para>The value of this property shall be
<literal>&#8220;power-ivpe&#8221;</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> to define the base logical addresses
and sizes of the registers for managing the interrupt context of a
physical processor thread</para>
<para>
<emphasis>prop-encoded-array</emphasis>: Two
(<emphasis>encode-phys, endcode-int</emphasis>)
pairs. The entries represent the user and OS level views of the
XIVE physical processor thread interrupt management areas respectively
(“TIMA” addresses). The first of the two entries is the base address and
size of the user level view and the second of the two entries is the
base address and size of the OS level view.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;compatible&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> to define alternate
<emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis> property values.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: The concatenation, with
<emphasis role="bold"><literal>encode+</literal></emphasis>, of an arbitrary number of text strings,
each encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.</para>
<para>The property value shall include
<emphasis role="bold"><literal>&#8220;ibm,power-ivpe&#8221;</literal></emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,xive_eq-sizes&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis>: Defines the sizes of event
queues that are supported by for the XIVE option.</para>
<para>
<emphasis>prop-encoded-value</emphasis>: One to N integers, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
<para>Each integer is expressed as the power of 2 of the event queue size.
For example, a 4K event queue size is represented by the value of 12
(4K = 2<superscript>12</superscript>). The integers are arranged in ascending order.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,xive-lisn-ranges&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name:</emphasis> Defines the LISN ranges assigned
to the client program.</para>
<para><emphasis>prop-encoded-array</emphasis>: One or more
(<emphasis>LISN, number</emphasis>) pairs, where LISN is a single cell
hexadecimal value between 0x00000000 and 0x7FFFFFFF, and number is an
integer. Each pair represents a contiguous range of LISNs. These LISNs
can be used by the OS for any purpose (eg IPIs). The first range will
contain at least one per possible thread in the partition.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;interrupt-controller&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> to indicate an interrupt (sub-)tree
root.</para>
<para><emphasis>prop-encoded-array</emphasis>: &lt;none&gt; The presence of
this property indicates that this node represents an interrupt
controller.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
</section>
<section>
<title>Additional Node Properties</title>
<para>Additional properties and methods are defined in this section for
LoPAR binding adapters and/or devices.</para>
<section>
<title>Interrupt Properties</title>
<para>The properties in this section shall be implemented for any device
that can present an interrupt for an LoPAR platform implementation. The
platform shall adhere to the
<xref linkend="dbdoclet.50569387_67880" /> definition for the interrupt
structure.</para>
</section>
<section xml:id="dbdoclet.50569368_31220">
<title>Miscellaneous Node Properties</title>
<para>This section defines properties which support devices, adapter and
buses with geographical information. These properties shall be present
for an LoPAR platform.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;built-in&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard <emphasis>property name</emphasis>: Any device that connects to an
industry standard I/O expansion bus attached through a non-standard
connector.</para>
<para><emphasis>prop-encoded-string</emphasis>: &lt;none&gt;.</para>
<para><emphasis role="bold">Note:</emphasis> This property will also include platform
&#8216;riser&#8217; cards.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;used-by-rtas&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard <emphasis>property name</emphasis>: Indicates the device can be in use by
an RTAS Function Call.</para>
<para><emphasis>prop-encoded-int</emphasis>: Presence of property indicates a
device may have an I/O or resource conflict with a RTAS Function
Call.</para>
</listitem>
</varlistentry>
</variablelist>
<para>The use of the
<emphasis role="bold"><literal>&#8220;slot-names&#8221;</literal></emphasis> property defined below is
deprecated in favor of the
<emphasis role="bold"><literal>&#8220;ibm,loc-code&#8221;</literal></emphasis> property.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;slot-names&#8221;</literal></emphasis> [S]</term>
<listitem>
<para><emphasis>property name</emphasis>: Describes external labeling of
adapter/device connectors.</para>
<para><emphasis>prop-encoded-array</emphasis>: An integer, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>, followed by a list of strings, each
encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.</para>
<para>The integer portion of the property value is a bitmask of available
connectors; for each connector associated with the adapter/device, the
bit corresponding to that connector&#8217;s ID number is set from
least-significant to most-significant ID number. The number of following
strings is the same as the number of connectors; the first string gives
the platform nomenclature or label for the connector with the smallest ID
number, and so on.</para>
<para>
<emphasis role="bold">Note:</emphasis> Each device that has a connector should
identify the order and contents of the list of strings in a
binding.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,loc-code&#8221;</literal></emphasis> [S]</term>
<listitem>
<para><emphasis>property name</emphasis> to provide location code(s) for the
Field Replacable Unit.</para>
<para><emphasis>prop-encoded-array</emphasis>: an arbitrary number of strings,
encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,vpd&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> to provide Vital Product Data (VPD)
information as defined in
<xref linkend="dbdoclet.50569341_29745" />.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: the concatenation, with
<emphasis role="bold"><literal>encode+</literal></emphasis>, of one or more pairs of elements, the first
element of each pair being an integer (representing the length of the
second element) encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>, and the second element of each pair
being a series of bytes (the VPD data) encoded as with
<emphasis role="bold"><literal>encode-bytes</literal></emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,loc-code-map&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>prop-name</emphasis> to identify that the interface may have
child nodes, which may or may not be present in the device tree, that
have a physical location code based on their unit-address.</para>
<para><emphasis>prop-encoded-array</emphasis>: A list of pairs (unit-address,
location-code). The unit-address is the child device node's
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property string-encoded according
to the parent node's architecture and encoded as with encode-string. The
location-code is the child device node's
<emphasis role="bold"><literal>&#8220;ibm,loc-code&#8221;</literal></emphasis> property encoded as with
encode-string.</para>
<para>If a child device under this node has a matching unit-address, the
location code corresponds to the physical location of that child
device.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
</section>
<section xml:id="dbdoclet.50569368_18247">
<title><literal>/aliases</literal> Node</title>
<para>A <emphasis>device alias</emphasis>, or simply
<emphasis>alias</emphasis>, is a shorthand representation of a
<emphasis>device-path</emphasis>.
<emphasis>Aliases</emphasis> are properties of the
<emphasis role="bold"><literal>aliases</literal></emphasis> node, encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>. Aliases are typically used by a user
to facilitate not specifying a long path name at the User Interface
&#8216;ok&#8217; prompt.</para>
<para>An implementation of OF for an LoPAR platform shall provide the
following aliases as properties of the
<emphasis role="bold"><literal>aliases</literal></emphasis> node, if the corresponding device
exists:</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;disk&#8221;</literal></emphasis> [S]</term>
<listitem>
<para><emphasis>property name</emphasis> indicating the device path of the
factory default disk that is the preferred boot disk<footnote xml:id="pgfId-585989">
<para><emphasis role="bold">Implementation Note:</emphasis> The preferred
boot disk should be the disk
that results in the fastest boot time. Implementations might
automatically spin up a disk at system power on and provide mechanisms
for firmware to report that disk in this property.</para>
</footnote>for the platform.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;tape&#8221;</literal></emphasis> [S]</term>
<listitem>
<para><emphasis>property name</emphasis> indicating the device path of the
factory default tape.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;cdrom&#8221;</literal></emphasis> [S]</term>
<listitem>
<para><emphasis>property name</emphasis> indicating the device path of the
factory default CDROM.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;keyboard&#8221;</literal></emphasis> [S]</term>
<listitem>
<para><emphasis>property name</emphasis> indicating the device path to the
keyboard to be used for the User Interface.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;mouse&#8221;</literal></emphasis> [S]</term>
<listitem>
<para><emphasis>property name</emphasis> indicating the device path to the mouse
to be used for the User Interface.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;screen&#8221;</literal></emphasis> [S]</term>
<listitem>
<para><emphasis>property name</emphasis> indicating the device path to the
screen to be used for the User Interface.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;pc-keyboard&#8221;</literal></emphasis> [S]</term>
<listitem>
<para><emphasis>property name</emphasis> indicating the device path of the
factory default PC-style keyboard.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;pc-mouse&#8221;</literal></emphasis> [S]</term>
<listitem>
<para><emphasis>property name</emphasis> indicating the device path of the
factory default PC-style mouse.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;adb-keyboard&#8221;</literal></emphasis> [S]</term>
<listitem>
<para><emphasis>property name</emphasis> indicating the device path of the
factory default ADB-style keyboard.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;adb-mouse&#8221;</literal></emphasis> [S]</term>
<listitem>
<para><emphasis>property name</emphasis> indicating the device path of the
factory default ADB-style mouse.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;scsi&#8221;</literal></emphasis> [S]</term>
<listitem>
<para><emphasis>property name</emphasis> indicating the device path of the
factory default built-in SCSI device.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;com1&#8221;</literal></emphasis> [S]</term>
<listitem>
<para><emphasis>property name</emphasis> indicating the device path of the
factory default 16550-style serial port known as
&#8220;com1.&#8221;</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;com2&#8221;</literal></emphasis> [S]</term>
<listitem>
<para><emphasis>property name</emphasis> indicating the device path of the
factory default 16550-style serial port known as &#8220;com2.&#8221;</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;scca&#8221;</literal></emphasis> [S]</term>
<listitem>
<para><emphasis>property name</emphasis> indicating the device path of the
factory default SCC-style serial port known as &#8220;SCCA.&#8221;</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;sccb&#8221;</literal></emphasis> [S]</term>
<listitem>
<para><emphasis>property name</emphasis> indicating the device path of the
factory default SCC-style serial port known as &#8220;SCCB.&#8221;</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;floppy&#8221;</literal></emphasis> [S]</term>
<listitem>
<para><emphasis>property name</emphasis> indicating the device path of the
factory default floppy drive.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;net&#8221;</literal></emphasis> [S]</term>
<listitem>
<para><emphasis>property name</emphasis> indicating the device path of the
factory default built-in network interface controller.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;rtc&#8221;</literal></emphasis> [S]</term>
<listitem>
<para><emphasis>property name</emphasis> indicating the device path of the
factory default real-time-clock chip.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;nvram&#8221;</literal></emphasis> [S]</term>
<listitem>
<para><emphasis>property name</emphasis> indicating the device path of the
factory default NVRAM.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="dbdoclet.50569368_38112">
<title><literal>/event-sources</literal> Node</title>
<para>The
<emphasis role="bold"><literal>/event-sources</literal></emphasis> node describes the possible RTAS Error
and Event Classes for interrupts. The
<emphasis role="bold"><literal>/event-sources</literal></emphasis> node shall be defined to be a child of
the root device tree node if the platform supports any event interrupts.
The following properties shall be defined for this node:</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> that denotes the Event Sources.</para>
<para><emphasis>prop-encoded-array</emphasis>: A string, encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.</para>
<para>The value of this string shall be
<literal>&#8220;event-sources&#8221;</literal>.</para>
<para>When events are reported as virtual interrupts there shall be a
node of
<emphasis role="bold"><literal>device_type
&#8220;PowerPC-External-Interrupt-Presentation&#8221;</literal></emphasis> from
which the virtual interrupt source BUID size can be obtained. Also the
<emphasis role="bold"><literal>event-sources</literal></emphasis> node represents the interrupt source
node for virtual event interrupts and thus the following properties shall
be defined for this node:</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;interrupt-controller&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard <emphasis>property name</emphasis>: to indicate the events interrupt tree
root.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: &lt;none&gt; The presence of
this property indicates that this node represents a source of virtual
interrupts. Encoded with
<emphasis>encode-null</emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;#interrupt-cells&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Refer to the definition of the
<emphasis role="bold"><literal>&#8220;#interrupt-cells&#8221;</literal></emphasis> property for nodes of
<emphasis role="bold"><literal>device_type &#8220;PowerPC-LSI-Source&#8221;</literal></emphasis> for
information about the definition of this property for virtual event
interrupts.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;interrupt-ranges&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Refer to the definition of the
<emphasis role="bold"><literal>&#8220;interrupt-ranges&#8221;</literal></emphasis> property for nodes of
device_type
<emphasis role="bold"><literal>&#8220;PowerPC-LSI-Source&#8221;</literal></emphasis> for information
about the definition of this property for virtual event
interrupts.</para>
<para>Children of
<emphasis role="bold"><literal>/event-sources</literal></emphasis> present the interrupt specifiers
associated with the reporting of platform events. LoPAR platforms have
historically implied the default value of
<emphasis role="bold"><literal>&#8220;#interrupt-cells&#8221;</literal></emphasis> of 1 to report the
associated interrupt specifiers without the interrupt trigger specifier.
However, all new designs shall present interrupt specifiers with explicit
trigger level values.</para>
</listitem>
</varlistentry>
</variablelist>
<section>
<title>Child nodes of the Event Sources Node</title>
<para>The following specify standard child nodes of the
<emphasis role="bold"><literal>/event-sources</literal></emphasis> node. These nodes could be present in
an LoPAR platform.</para>
<para>Children of the
<emphasis role="bold"><literal>/event-sources</literal></emphasis> node specify the interrupt specifiers
associated with the reporting of platform events. Interrupt designs shall
use the 1275 standard
<emphasis role="bold"><literal>&#8220;interrupts&#8221;</literal></emphasis> property as configured to
report the interrupt specifier for the platforms PowerPC interrupt
controller. The interrupt specifiers if the
<emphasis role="bold"><literal>&#8220;interrupts&#8221;</literal></emphasis> property indicates one or
more interrupt source numbers that are used to report event
conditions.</para>
<section>
<title>internal-errors</title>
<para>The presence of the node indicates that all or some of the function
has been implemented and will be reported using an interrupt.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> that denotes the internal error&#8217;s
events.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: A string, encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.</para>
<para>The value of this string shall be
<literal>&#8220;internal-error&#8221;</literal>.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section>
<title>epow-events</title>
<para>The presence of the node indicates that all or some of the function
has been implemented and will be reported using an interrupt.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> that denotes the EPOW events.</para>
<para><emphasis>prop-encoded-array</emphasis>: A string, encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.</para>
<para>The value of this string shall be
<literal>&#8220;epow-events&#8221;</literal>.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section>
<title>ibm,io-events</title>
<para>The presence of the node indicates that all or some of the function
has been implemented and will be reported using an interrupt.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> that denotes the I/O sub-system
events.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: A string, encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.</para>
<para>The value of this string shall be
<literal>&#8220;ibm,io-events&#8221;</literal>.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
</section>
<section xml:id="sec_papr_bindings_hot_plug_events">
<title>hot-plug-events</title>
<para>The presence of the node indicates that all or some of the function
has been implemented and will be reported using an interrupt. </para>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis></term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> that denotes the hot-plug
events.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: A string, encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.</para>
<para>The value of this string shall be
<literal>&#8220;hot-plug-events&#8221;</literal>.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
</section>
<section>
<title><literal>/reserved</literal> Node</title>
<para>This section defines a reserved node which shall have a
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property which allocates addresses
(on the bus of which it is a child) which is intended to be a place to
identify hardware registers that do not otherwise belong to a recognized
device.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> that denotes reserved addresses that do
not belong to a recognized device.</para>
<para><emphasis>prop-encoded-array</emphasis>: A string, encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.</para>
<para>The value of this string shall be
<literal>&#8220;reserved&#8221;</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;device_type&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> that indicates the device type.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: Text string, encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.</para>
<para>The value of this property shall be
<literal>&#8220;reserved&#8221;</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> defines a hardware register address and
range of addresses not intended for OS (OS) use.</para>
<para><emphasis>prop-encoded-array</emphasis>: List of (
<emphasis>phys-addr, size</emphasis>) specifications.</para>
<para><emphasis>Phys-addr</emphasis> is a (phys.lo ... phys.hi) sequence equal
to <emphasis role="bold"><literal>#address-cells</literal></emphasis>, encoded as with
<emphasis role="bold"><literal>encode-phys</literal></emphasis>.</para>
<para>
<emphasis>size</emphasis> is a sequence equal to
<emphasis role="bold"><literal>#size-cells</literal></emphasis> encoded as with
<emphasis>encode-size</emphasis>.</para>
<para>The first entry in this list shall be a hardware register address (
<emphasis>phys-addr</emphasis>) and a range of hardware addresses (
<emphasis>size</emphasis>) that is not intended for OS usage. Successive
entries in this list shall be additional hardware addresses not intended
for OS usage.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="dbdoclet.50569368_11392">
<title><literal>/chosen</literal> Node</title>
<para>This section lists additional properties as required under the
<emphasis role="bold"><literal>/chosen</literal></emphasis> node with the following text in a manner that
is consistent with
<xref linkend="dbdoclet.50569387_45524" />, Section 3.5.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;nvram&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard <emphasis>property name</emphasis> that defines the package
<emphasis>Ihandle</emphasis> for CHRP NVRAM.</para>
<para><emphasis>prop-encoded-array</emphasis>: an integer, as encoded with
<emphasis role="bold"><literal>encode-int</literal></emphasis>, that is the package
<emphasis>Ihandle</emphasis> the CHRP NVRAM.</para>
<para><emphasis role="bold">Note:</emphasis> The nvram Node identified in the /chosen Node
shall support a size method as specified in
<xref linkend="dbdoclet.50569387_27008" />, Section 7.2. The size method
will return a value that is the total platform NVRAM size.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,rpa-client-config&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> that defines the processed fields of
the client program&#8217;s <emphasis role="bold"><literal>IBM,RPA-Client-Config</literal></emphasis> ELF note section.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: an array of integers encoded as
with
<emphasis role="bold"><literal>encode-int</literal></emphasis>, that consist of the fields of the note
section that the firmware processed prior to loading the client
program.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,architecture-vec-5&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis>: that presents the values of the
option vector #5 negotiated by the
<emphasis>ibm,client architecture-support</emphasis> method. Presence of
this property signifies that the client program load module invoked the
<emphasis>ibm,client architecture-support</emphasis> method.</para>
<para><emphasis>prop-encoded-array</emphasis>: An array of bytes having the
format of the fifth option vector from
<xref linkend="dbdoclet.50569368_10077" /> representing the value chosen
by the <emphasis>ibm,client architecture-support</emphasis> method.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,client-architecture-support-reboot&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis>: that indicates that one or more
reboots have occurred in this boot sequence in order to adjust the
platform settings to match the specification in the
<emphasis role="bold"><literal>&#8220;ibm,client-architecture-support&#8221;</literal></emphasis> open
firmware method or the <emphasis role="bold"><literal>IBM,RPA-Client-Config</literal></emphasis> ELF header note. Note this
property is not included for the first boot in a sequence.</para>
<para><emphasis>prop-encoded-array</emphasis>: encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis> that specifies the number of reboots that
have occurred in this boot sequence in order to adjust the platform
settings to match the specification in the
<emphasis role="bold"><literal>&#8220;ibm,client-architecture-support&#8221;</literal></emphasis> open
firmware method or the <emphasis role="bold"><literal>IBM,RPA-Client-Config</literal></emphasis> ELF header note.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section>
<title><literal>/vdevice</literal> Node</title>
<para>The node of type vdevice is a child of the root node. It is only
present in trees that also include the
<emphasis role="bold"><literal>&#8220;ibm,hypertas_functions&#8221;</literal></emphasis> property. It,
and its children represent the virtualized devices that are implemented
by the platform firmware. Virtualized devices do not surface to a client
program a direct hardware interface. They do not appear to take up space
in the client program&#8217;s address map. Standard property names
associated with the
<emphasis>/vdevice</emphasis> node have special values as specified
below.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;#address-cells&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis> that specifies the number of cells
required to represent a child bus address. Shall have the value of 1.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;#size-cells&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis> that specifies the number of cells
required to encode the size field of a child&#8217;s reg property. Shall
have the value of 0 indicating that no child node may actually take
physical address space.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> string encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis> that defines the name of node. The
value shall be the string &#8220;vdevice&#8221;.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;device_type&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> string encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis> that defines the device type of the
node. The value shall be the string &#8220;vdevice&#8221;.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,max-virtual-dma-size&#8221;</literal></emphasis></term>
<listitem>
<para>Vendor unique
<emphasis>property name</emphasis> indicating the maximum size virtual dma
transfer size supported by the platform</para>
<para><emphasis>prop-encoded-array</emphasis>: a single integer encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,migration-control&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> that indicates when platform firmware
supports the ability for an I/O server partition to delay the migration
of a partition to a different server in order to let any in progress I/O
to be completed. Specifically, this property indicates that the
DISABLE_MIGRATION and ENABLE_MIGRATION subfunctions of the H_VIOCTL
hypervisor call are supported.</para>
<para><emphasis>prop-encoded-array</emphasis>: None, this is a name only
property.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,reserved-virtual-addresses&#8221;</literal></emphasis></term>
<listitem>
<para>Vendor unique
<emphasis>property name</emphasis> indicating ranges of the client program
virtual address space that are reserved for platform use.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: one or more pairs of
abbreviated-virtual-address, virtual-address-length specifications
representing the origin and length respectively of a reserved virtual
address range.</para>
<para><emphasis>abbreviated-virtual-address</emphasis>: Consists of two integers
encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis> representing the high order and low order
32 bits respectively of the 64 bit abbreviated virtual address. The full
virtual address is the abbreviated-virtual-address concatenated with 3
low order bytes of 0x00.</para>
<para><emphasis>virtual-address-length</emphasis>: Consists of a single integer
encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis> representing the number of consecutive 4K
pages contained within the range.</para>
</listitem>
</varlistentry>
</variablelist>
<section xml:id="dbdoclet.50569368_26956">
<title>Children of the <literal>/vdevice</literal> Node</title>
<para>The children of the
<emphasis>/vdevice</emphasis> node represent the individual virtual
devices.</para>
<para>Children of the
<emphasis>/vdevice</emphasis> node that support dma operations contain a
the
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property as defined
below:</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> that defines the bus address window(s)
that this IOA may use for its dma.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: One or more (
<emphasis>logical-I/O-bus-number, phys</emphasis>,
<emphasis>size</emphasis>) triple(s) where the logical bus number is a
one cell cookie representing the unique range of TCE entries assigned to
this IOA encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>, the number of cells for
<emphasis>phys</emphasis> corresponds to the node&#8217;s
<emphasis role="bold"><literal>&#8220;ibm,#dma-address-cells&#8221;</literal></emphasis> value while the
number of cells for
<emphasis>size</emphasis> corresponds to the
<emphasis role="bold"><literal>&#8220;ibm,#dma-size-cells&#8221;</literal></emphasis> for this node. The
first triple represents the TCE range available for mapping local memory,
while the second triple, if it exists, is where remote memory mapped by
remote partitions appears. The size field of the second triple shall be
equal to the size field of the corresponding remote partition&#8217;s
first triple.</para>
<para>The
<emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property is the per
device equivalent of the
<emphasis role="bold"><literal>&#8220;ibm,dma-window&#8221;</literal></emphasis> property found in nodes
representing bus bridges.</para>
<para>Children of the
<emphasis>/vdevice</emphasis> node share the ability to display unique
capabilities as represented by the following properties.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,async-dma-required&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> indicates that the virtual device
requires the use of asynchronous virtual DMA interfaces (see
<xref linkend="dbdoclet.50569387_85757" /> for definition of asynchronous
virtual DMA interfaces).</para>
<para><emphasis>prop-encoded-array</emphasis>: None, this is a name only
property.</para>
<para>Children of the
<emphasis>/vdevice</emphasis> node which act a a server to other virtual
client devices, display the following property.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,vserver&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> indicates that the virtual device is a
server to virtual devices.</para>
<para><emphasis>prop-encoded-array</emphasis>: None, this is a name only
property.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,mac-address-filters&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> specifies the number of non-broadcast
multicast MAC filters supported by the implementation.</para>
<para><emphasis>prop-encoded-array</emphasis>: an integer in the range of 0-255
encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,trunk-adapter&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> that indicates that the virtual device
is a trunk adapter server to the logical LAN.</para>
<para><emphasis>prop-encoded-array</emphasis>: None, this is a name only
property.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,illan-options&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis>: The existence of this property is
required when any of the ILLAN sub-options are implemented and indicates
that the H_ILLAN_ATTRIBUTES hcall() is implemented, and that hcall() is
then used to determine which ILLAN options are implemented.</para>
<para><emphasis>prop-encoded-array</emphasis>: None, this is a name only
property.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,vf-loc-code&#8221;</literal></emphasis></term>
<listitem>
<para>Vendor unique <emphasis>property name</emphasis> indicating the physical device
virtual function upon which the vnic-server runs. The value is that of the
<emphasis role="bold"><literal>&#8220;ibm,loc-code&#8221;</literal></emphasis>
property of the physical device virtual function.</para>
<para><emphasis>prop-encoded-array</emphasis>: an arbitrary number of strings, encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,vnic-mode&#8221;</literal></emphasis></term>
<listitem>
<para>Vendor unique <emphasis>property name</emphasis> that represents the operational
mode in which the vnic-server runs.</para>
<para><emphasis>prop-encoded-array</emphasis>: a single byte, encoded as with
<emphasis role="bold"><literal>encode-bytes</literal></emphasis>.</para>
<para>Defined values:</para>
<itemizedlist>
<listitem>
<para>0: backing device is dedicated to one VNIC client</para>
</listitem>
<listitem>
<para>1: backing device is shared by multiple VNIC clients</para>
</listitem>
<listitem>
<para>2-255: reserved</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,vnic-client-mac&#8221;</literal></emphasis></term>
<listitem>
<para>Vendor unique <emphasis>property name</emphasis> that represents the MAC
address of a given vNIC server's client.</para>
<para><emphasis>prop-encoded-array</emphasis>: 6 bytes, encoded as with
<emphasis role="bold"><literal>encode-bytes</literal></emphasis>.</para>
</listitem>
</varlistentry>
</variablelist>
<section>
<title>Virtual Teletype Device</title>
<para>The virtual teletype device allows communication through the
platform&#8217;s attached Hardware System Console. There is one such
virtual device node for each virtual terminal enumerated by the
<emphasis role="bold"><literal>&#8220;ibm,termno&#8221;</literal></emphasis> property. The unit addresses
of the virtual teletype devices shall correspond to the enumeration
presented in the
<emphasis role="bold"><literal>&#8220;ibm,termno&#8221;</literal></emphasis> property. Such virtual
terminals, as represented by the
<emphasis role="bold"><literal>&#8220;ibm,termno&#8221;</literal></emphasis> property, are intended for
the use of the client program and shall not be marked
<emphasis role="bold"><literal>&#8220;used-by-rtas&#8221;</literal></emphasis>. Similarly they may be
&#8220;chosen&#8221; as the default input and output device.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis> that defines the device name. The value
shall be the string
<emphasis role="bold"><literal>&#8220;vty&#8221;</literal></emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard <emphasis>property name</emphasis> to define a unit address for the node.
One (
<emphasis>phys-addr, size</emphasis>) pair. The
<emphasis>phys-addr</emphasis> is the unit address of the device
(corresponding to one of the virtual terminals enumerated by the
<emphasis role="bold"><literal>&#8220;ibm,termno&#8221;</literal></emphasis> property), and the
<emphasis>size</emphasis> shall have a length of zero.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;device_type&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard <emphasis>property name</emphasis> encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis> to specify the device type. The value
shall be the string
<emphasis role="bold"><literal>&#8220;serial&#8221;</literal></emphasis> indicating that the device
emulates a serial terminal.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;compatible&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis> to specify the device driver
compatibility. The value shall be one of the strings specified in
<xref linkend="dbdoclet.50569368_46297" />.</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569368_46297">
<title>Virtual tty compatibility strings</title>
<?dbhtml table-width="75%" ?>
<?dbfo table-width="75%" ?>
<tgroup cols="2">
<colspec colname="c1" colwidth="40*" />
<colspec colname="c2" colwidth="60*" />
<thead>
<row>
<entry align="center">
<para>
<emphasis role="bold">Compatible property String
Value</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Comments</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;hvterm1&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Standard client virtual tty protocol</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;hvterm2&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Standard server virtual tty protocol</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold"><literal>&#8220;hvterm-protocol&#8221;</literal></emphasis>
</para>
</entry>
<entry>
<para>Client virtual tty protocol extended for control of
modems etc.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>See
<xref linkend="dbdoclet.50569352_15379" /> for further detail on this
virtual device.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section>
<title>Children of
<literal>/vdevice</literal> node defined in other documents</title>
<para>Like children of the pci bus node, children of
<emphasis>/vdevice</emphasis> may be defined by their own binding
documents or via binding sections/tables in their device specifications.
For example, the binding information for the LoPAR Interpartition
Logical LAN, Virtual SCSI, and Virtual Terminal can be found in the
appropriate sections of this document. The virtualization of traditional
physical devices repositions their associated device tree nodes to be
children of
<emphasis>/vdevice</emphasis>. Examples include NVRAM and Real Time Clock
(RTC) devices which are defined by
<xref linkend="dbdoclet.50569387_27008" />.</para>
</section>
</section>
</section>
<section>
<title>Barrier Synchronization Facility</title>
<para>This section describes the OF node that represents the optional
Barrier Synchronization Register (BSR) facility. If the platform provides
a BSR facility it provides the
<emphasis>ibm,bsr</emphasis> node as a child of
<emphasis>/</emphasis> (root). If the platform provides a client program
with multiple independent facilities, it represents each such facility
with a separate node. A given facility may have multiple representations
through parallel windows. Each window of a given facility is represented
by a separate
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property value. The following
properties are the minimum required, optional support such as dynamic
reconfiguration will add properties per requirements called out in the
<xref linkend="dbdoclet.50569342_82208" />.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis> that defines the device name. The value
shall be the string
<emphasis role="bold"><literal>&#8220;ibm,bsr&#8221;</literal></emphasis> for legacy implementations and
<emphasis role="bold"><literal>&#8220;ibm,bsr2&#8221;</literal></emphasis> for POWER8 implementations and
beyond.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> to define the addresses for the
facility window(s).</para>
<para>
<emphasis>prop-encoded-array</emphasis>: One or more (
<emphasis>phys-addr, size</emphasis>) pair(s). The
<emphasis>phys-addr</emphasis>, encoded as with
<emphasis role="bold"><literal>encode-phys</literal></emphasis>, is the starting address (4 K aligned) of
the window. The
<emphasis>size</emphasis>, encoded in the number of cells specified by
<emphasis role="bold"><literal>&#8220;#size-cells&#8221;</literal></emphasis> of the parent, is the
length of the corresponding window.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;device_type&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis> to specify the device type. The value
shall be the string
<emphasis role="bold"><literal>&#8220;ibm,bsr&#8221;</literal></emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;compatible&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis> to specify the device driver
compatibility. The value shall be the string
<emphasis role="bold"><literal>&#8220;ibm,bsr&#8221;</literal></emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,#lock-bytes&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis>: Indicates the number of lock bytes
per line of the BSR facility.</para>
<para><emphasis>prop-encoded-array</emphasis>: One or more integers encoded as
with <emphasis role="bold"><literal>encode-int</literal></emphasis>. When the facility has multiple windows,
as represented by multiple values of the
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property, then there is a
corresponding number of integers, each integer representing the number of
lock bytes per line of the corresponding window.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,lock-stride&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis>: Indicates the number of bytes between
the beginning of lock lines in the BSR facility.</para>
<para><emphasis>prop-encoded-array</emphasis>: One or more integers encoded as
with <emphasis role="bold"><literal>encode-int</literal></emphasis>. When the facility
has multiple windows, as represented by multiple values of the
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property, then there is a
corresponding number of integers, each integer representing the number of
bytes to the beginning of the next lock line in the corresponding
window.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section>
<title>Nodes of device_type <literal>&#8220;block&#8221;</literal> and
<literal>&#8220;byte&#8221;</literal></title>
<para>This section describes the OF nodes that provide access to storage
devices in block or byte commands. This applies to such nodes with and
without a
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,write-supported&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis>: Indicates the driver supports write
functionality and has been verified by IBM. The use of the write function
without this property is discouraged.</para>
<para><emphasis>prop-encoded-array</emphasis>: None, this is a name only
property.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,16byte-cdb-supported&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis>: Indicates the driver supports using
the 16 byte Command Descriptor Block format, which is needed to access
above 2 TB on 512 byte block-sized media.</para>
<para><emphasis>prop-encoded-array</emphasis>: None, this is a name only
property.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section>
<title><literal>/ibm,platform-facilities</literal></title>
<para>The node of type
<emphasis role="bold"><literal>ibm,platform-facilities</literal></emphasis> is a child of the root node.
It and its children represent the non-CPU platform computational
facilities that are available. Platform facilities do not take up space
in the client program&#8217;s address map. Standard property names
associated with the
<emphasis>/ibm,platformfacilities</emphasis> node have special values as
specified below.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;#address-cells&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis> that specifies the number of cells
required to represent a child bus address. Shall have the value of
1.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;#size-cells&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis> that specifies the number of cells
required to encode the size field of a child&#8217;s reg property. Shall
have the value of 0 indicating that no child node may actually take
physical address space.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> string encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis> that defines the name of node. The
value shall be the string
<emphasis role="bold"><literal>&#8220;ibm,platform-facilities&#8221;</literal></emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;device_type&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> string encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis> that defines the device type of the
node. The value shall be the string
<emphasis role="bold"><literal>&#8220;ibm,platform-facilities&#8221;</literal></emphasis>.</para>
<para>Some platform facilities configurations allow multiple facilities
to share a common pool of interrupt server numbers. Individual operations
specify which interrupt server number from the pool shall be used to
signal completion of the operation. To represent such a configuration,
the
<emphasis>/ibm,platformfacilities</emphasis> node may either represent an
interrupt source controller for its children or the interrupt source
controller associated with the shared pool may be represented by a
PowerPC External Interrupt Source Controller Node as an additional child
node of the
<emphasis role="bold"><literal>/ibm,platform-facilities</literal></emphasis> node
(<xref linkend="dbdoclet.50569368_69563" />). Additionally, the node
representing the platform facilities Interrupt Source Controller shall
contain the
<emphasis role="bold"><literal>&#8220;ibm,interrupt-pool&#8221;</literal></emphasis> property, and all
platform facilities that share the common pool of interrupts shall
contain the
<emphasis role="bold"><literal>&#8220;ibm,shared-interrupt-pool&#8221;</literal></emphasis> property.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,interrupt-pool&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis>: that indicates this interrupt
controller provides a shared pool of interrupt source numbers.</para>
<para><emphasis>property encoded array</emphasis>: single cell encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis> that represents the type of shared
interrupt pool being represented: Defined values are: 0 with all other
values reserved.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,max-async-ops-per-processor&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis>: that indicates for the partition the
allowed maximum number of outstanding operations for the platform
facility based upon the number of processors currently allocated to the
partition. The total allowable number of such operations outstanding
across all partition processors is the product of the value of
<emphasis role="bold"><literal>&#8220;ibm,max-async-ops-per-processor&#8221;</literal></emphasis> and the
number of nodes of type cpu in the current partition device tree.</para>
<para><emphasis>property encoded array</emphasis>: single cell encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis></para>
</listitem>
</varlistentry>
</variablelist>
<section>
<title>Children of the <literal>/ibm,platform-facilities</literal> Node</title>
<para>The children of the
<emphasis role="bold"><literal>/ibm,platform-facilities</literal></emphasis> node represent the
individual platform facilities. Standard property names associated with
the children of the
<emphasis role="bold"><literal>/ibm,platform-facilities</literal></emphasis> node have special values as
specified below. Note the children of the
<emphasis role="bold"><literal>/ibm,platform-facilities</literal></emphasis> node shall contain the
following standard properties with their standard definitions:</para>
<itemizedlist>
<listitem>
<para><emphasis role="bold"><literal>&#8220;compatible&#8221;</literal></emphasis></para>
</listitem>
<listitem>
<para><emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis> The defined Values for the
<emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis> property of children of
<emphasis role="bold"><literal>/ibm,platform-facilities</literal></emphasis> are (were # is the version
number of the interface):</para>
<itemizedlist>
<listitem>
<para><emphasis role="bold"><literal>ibm,random-v#</literal></emphasis> Random number generator</para>
</listitem>
<listitem>
<para><emphasis role="bold"><literal>ibm,compression-v#</literal></emphasis> Compression/Decompression
engine</para>
</listitem>
<listitem>
<para><emphasis role="bold"><literal>ibm,sym-encryption-v#</literal></emphasis> Symmetric encryption/decryption
engine</para>
</listitem>
<listitem>
<para><emphasis role="bold"><literal>ibm,asym-encryption-v#</literal></emphasis> Asymmetric
encryption/decryption engine</para>
</listitem>
<listitem>
<para><emphasis role="bold"><literal>ibm,memory-utilization-instrumentation-v#</literal></emphasis> Memory
usage information</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para><emphasis role="bold"><literal>&#8220;status&#8221;</literal></emphasis></para>
</listitem>
</itemizedlist>
<para><emphasis role="bold">Optionally</emphasis> the children of the
<emphasis role="bold"><literal>/ibm,platform-facilities</literal></emphasis> node may contain as
appropriate the following standard properties with their standard
definitions:</para>
<itemizedlist>
<listitem>
<para><emphasis role="bold"><literal>&#8220;interrupts&#8221;</literal></emphasis></para>
</listitem>
</itemizedlist>
<para><emphasis role="bold">Additionally</emphasis> the children of the
<emphasis role="bold"><literal>/ibm,platform-facilities</literal></emphasis> node may contain as
appropriate the following unique properties:</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,resource-id&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis>: that indicates the platform facility
resource identification handle.</para>
<para><emphasis>property encoded array</emphasis>: single cell encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis></para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,max-sync-cop&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis>: that indicates the maximum
characteristics of the parameters for a synchronous call of the platform
facility. These characteristics are represented as a series of integers
encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis> that
may grow over time as platform
facilities evolve. The absence of this property indicates that
synchronous operations are not allowed for the given child.</para>
<para>
<emphasis>property encoded array</emphasis>: a series of zero or more or
more cells each encoded as with
<emphasis>encode-int.</emphasis> The interpretation of the series of
integers is unique per the value of the
<emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis> property:</para>
<itemizedlist>
<listitem>
<para>For the Random number generator: NULL value indicating that all
calls are synchronous</para>
</listitem>
<listitem>
<para>For the compression/decompression engine: Two series of cells the
first series of cells represents the maximums that can be synchronously
compressed. The second series of cells represents the maximums that can
be synchronously decompressed.</para>
<itemizedlist>
<listitem>
<para>The first cell in each series contains the count of the number of
data length, scatter/gather elements pairs that follow &#8211; each being
of the form</para>
<itemizedlist>
<listitem>
<para>One cell data byte length</para>
</listitem>
<listitem>
<para>One cell total number of scatter/gather elements</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>For the symmetric encryption/decryption engine: the series of
cells report for each function code (FC) and mode combination the maximum
amount of data and scatter/gather list elements that can be processed
with a given key length. Thus the array consists of 1-N sub sequences
each of the form:</para>
<itemizedlist>
<listitem>
<para>First cell contains the FC field</para>
</listitem>
<listitem>
<para>Second cell contains the mode field</para>
</listitem>
<listitem>
<para>Third cell contains the count of the number of key length, data
length, scatter/gather elements triples that follow &#8211; each being of
the form:</para>
<itemizedlist>
<listitem>
<para>One cell key bit length</para>
</listitem>
<listitem>
<para>One cell data byte length</para>
</listitem>
<listitem>
<para>One cell total number of scatter/gather elements</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,max-sg-len&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis>: that indicates the maximum byte length
of a scatter/gather list for the platform facility.</para>
<para>
<emphasis>property encoded array</emphasis>: single cell encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis></para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,shared-interrupt-pool&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis>: that provides an indirect pointer to
the node representing the shared interrupt pool used by this
facility.</para>
<para><emphasis>property encoded array</emphasis>: the phandle of the node
representing the PowerPC External Interrupt Source Controller that
sources the interrupts of the shared interrupt pool used by this
facility.</para>
</listitem>
</varlistentry>
</variablelist>
<itemizedlist>
<listitem>
<para>For the memory utilization instrumentation facility node the following properties are defined:</para>
</listitem>
</itemizedlist>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,mui-associativity-mapping&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> to define the mapping between Memory Usage
Instrumentation Affinity Log Array entries and their associated associativity strings.</para>
<para><emphasis>property encoded array</emphasis>: An integer (L) encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis> followed by L sets ALA map entries.</para>
<para>Each ALA map entry consisting of:</para>
<itemizedlist>
<listitem>
<para>An integer (ALAentry) encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>
as would be found in the affinity_log record for the return buffer
from the H_RETURN_PAGEINFO hcall() followed by;</para>
</listitem>
<listitem>
<para>An integer (M) encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>
that represents the type of source of the reference
(defined values are presented below). Sources of a general
type are grouped together, so that if the
client program does not recognize a given specific type,
it can still categorize via the more general
type of source:</para>
<itemizedlist spacing="compact">
<listitem>
<para>0-100,000,000 CPU</para>
</listitem>
<listitem>
<para>100,000,001 – 200,000,000 I/O Bridge</para>
</listitem>
<listitem>
<para>200,000,001 – 300,000,000 Platform Service Device</para>
</listitem>
<listitem>
<para>All other values reserved (may be grouped together as an unknown source type).</para>
</listitem>
</itemizedlist>
<para>Followed by:</para>
</listitem>
<listitem>
<para>An integer (N) encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>
followed by N associativity lists.</para>
</listitem>
<listitem>
<para>Each associativity list consisting of a number of entries integer (P) encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>
followed by P integers encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>
each representing an associativity
domain number.</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,mui-ranges&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis> to define the implementation specific
ranges of memory utilization instrumentationmeasures.</para>
<para><emphasis>property encoded array</emphasis>: An integer (N) encoded as with
encode-int
which communicates the number of pairs of range values, each being an integer encoded as with
encode-int
which represent the implementation limits of a given measure. See
<xref linkend="table_mui_range_limits" />
for details. The reader is to ignore values pairs beyond those it was designed to use.
If the value of N is zero the MUI measures are not available.</para>
</listitem>
</varlistentry>
</variablelist>
<table xml:id="table_mui_range_limits">
<?dbhtml table-width="75%" ?>
<?dbfo table-width="75%" ?>
<title><emphasis role="bold"><literal>&#8220;ibm,mui-associativity-mapping&#8221;</literal></emphasis> range limits</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="10*" align="center" />
<colspec colname="c2" colwidth="20*" align="center" />
<colspec colname="c3" colwidth="70*" />
<thead>
<row>
<entry>
<para>Pair #</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
</row>
</thead>
<tbody valign="middle">
<row>
<entry>
<para>1</para>
</entry>
<entry>
<para>MIN/MAX</para>
</entry>
<entry>
<para>The minimum and maximum supported value of the HUC field
which is the power of 2 multiplier of microseconds that defines the
History Bit Array update period.</para>
</entry>
</row>
<row>
<entry>
<para>2</para>
</entry>
<entry>
<para>0/MAX</para>
</entry>
<entry>
<para>The number of bits implemented in the HBA.</para>
</entry>
</row>
<row>
<entry>
<para>3</para>
</entry>
<entry>
<para>0/MAX</para>
</entry>
<entry>
<para>Access rate in accesses per millisecond.</para>
</entry>
</row>
<row>
<entry>
<para>4</para>
</entry>
<entry>
<para>0/MAX</para>
</entry>
<entry>
<para>Page Age; the MAX value is the number of Page Age Granules
which saturates the page age counter.</para>
</entry>
</row>
<row>
<entry>
<para>5</para>
</entry>
<entry>
<para>0/MAX</para>
</entry>
<entry>
<para>Remote Reference; the MAX value is the number of implemented ALA entries.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
</section>
<section xml:id="sec_ibm_coherent_platform_facility_node">
<title><literal>/ibm,coherent-platform-facility node</literal></title>
<para>The <emphasis role="bold">ibm,coherent-platform-facility</emphasis> nodes
represent the coherent platform facilities. Standard property names associated
with the <emphasis role="bold">ibm,coherent-platform-facility</emphasis> node
have special values as specified below.
</para>
<para>Three-cell addresses encoded with encode-phys shall be formatted as follows:
<programlisting><![CDATA[Bit# 33222222 22221111 11111100 00000000
10987654 32109876 54321098 76543210
phys.hicell: 00000000 00000000 00000000 tttttttt
phys.midcell: hhhhhhhh hhhhhhhh hhhhhhhh hhhhhhhh
phys.locell: llllllll llllllll llllllll llllllll
where:
t = is the type of address, enumerated as:
0x00 = Unit Addressing
0x01 = PSL Privilege 2 Area Address
0x02 = AFU Problem State Area Address
0x03 = Memory Mapped Address
hh..hh = is a 32-bit unsigned number
ll..ll = is a 32-bit unsigned number]]></programlisting>
</para>
<para>When the hh...hh and ll...ll fields are concatenated to form a larger
number, hh...hh is the most significant portion and ll...ll is the least
significant portion.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;#address-cells&#8221;</literal></emphasis></term>
<listitem>
<para>Standard <emphasis>property name</emphasis>, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>,
that specifies the number of cells required to represent a child’s
bus address. The value of
<emphasis role="bold"><literal>&#8220;#address-cells&#8221;</literal></emphasis>
for the child's bus address shall be 3.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;#size-cells&#8221;</literal></emphasis></term>
<listitem>
<para>Standard <emphasis>property name</emphasis>, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>,
that specifies the number of size cells required to represent a child’s
bus address. Shall have the value of 2 indicating that a child node may
take physical address space.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;compatible&#8221;</literal></emphasis></term>
<listitem>
<para>Standard <emphasis>property name</emphasis> per
<xref linkend="dbdoclet.50569387_45524"/>
specifying the programming models that are compatible with this coherent
platform facility. The last value of this property shall be
<emphasis role="bold"><literal>&#8220;ibm,coherent-platform-facility&#8221;</literal></emphasis>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis></term>
<listitem>
<para>Standard <emphasis>property name</emphasis> per
<xref linkend="dbdoclet.50569387_45524"/>
to define the name of the package. This property is encoded with
<emphasis role="bold"><literal>encode-string</literal></emphasis>
and the value shall be:
<emphasis role="bold"><literal>&#8220;ibm,coherent-platform-facility&#8221;</literal></emphasis>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;model&#8221;</literal></emphasis></term>
<listitem>
<para>Standard <emphasis>property name</emphasis> per
<xref linkend="dbdoclet.50569387_45524"/>
to define a manufacturer’s model number. This value defines the programming
version of the facility and has the value of the coherent platform
facility PSL version.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis></term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> that defines the coherent platform
facility handle.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: List of
(<emphasis>phys-addr, size</emphasis>) specifications.
<itemizedlist mark="none">
<listitem>
<para><emphasis>phys-addr</emphasis> is encoded as with
<emphasis role="bold"><literal>encode-phys</literal></emphasis> and
<emphasis>size</emphasis> is encoded with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
</listitem>
</itemizedlist>
The first value of the property shall be the handle for use with
the coherent platform facility, where
<emphasis>phys-addr</emphasis>
denotes the unit-address. It shall have a size value of 0. This
value is always present.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ranges&#8221;</literal></emphasis></term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> to define the mapping of the parent
address space to child address spaces.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: List of
(<emphasis>child-phys, parent-phys,size</emphasis>) specifications.</para>
<itemizedlist mark="none">
<listitem>
<para><emphasis>child-phys</emphasis> is an addresss, encoded as with
<emphasis role="bold"><literal>encode-phys</literal></emphasis>, and
is the child address and shall have a type field indicating Memory Mapped
Address.</para>
</listitem>
<listitem>
<para><emphasis>parent-phys</emphasis> is encoded as with
<emphasis role="bold"><literal>encode-phys</literal></emphasis> and
is the parent address.</para>
</listitem>
<listitem>
<para><emphasis>size</emphasis> is encoded with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,loc-code&#8221;</literal></emphasis></term>
<listitem>
<para>Property name Property name specifying the unique and persistent
location code associated with this coherent platform facility p
resented as an encoded array as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.
The value shall be of the form specified in Ux-Px-Cx.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;interrupt-ranges&#8221;</literal></emphasis></term>
<listitem>
<para>Standard <emphasis>property name</emphasis> specifying the
interrupt-source number(s) and range(s) associated with this coherent
platform facility. The property is presented as an encoded array of
two cells per entry, each cell encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>,
with the first cell of an entry containing the first interrupt source
number (ISN <subscript>1</subscript>) of a range and the second cell of an entry containing
an unsigned integer, specifying the count (N) of ISNs in the range,
such that ISN1<subscript>1</subscript>+(N-1) specifies the value of the last
ISN<subscript>N</subscript> in the range.</para>
<para>The interrupt source numbers are assigned and utilized by the children of this node,
<emphasis role="bold"><literal>ibm,coherent-platform-function</literal></emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;device_type&#8221;</literal></emphasis></term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> string encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis> that defines the device type of the
node. For the coherent platform facility, the device type the value shall
be the string <emphasis role="bold"><literal>&#8220;capi&#8221;</literal></emphasis>.</para>
</listitem>
</varlistentry>
</variablelist>
<para>Optionally the
<emphasis role="bold"><literal>/ibm,coherent-platform-facility</literal></emphasis>
node may contain the following properties.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,my-drc-index&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>property name</emphasis> denotes an integer index (value of the
entry in the
<emphasis role="bold"><literal>&#8220;ibm,drc-indexes&#8221;</literal></emphasis> property) for the
connector between the node and the node&#8217;s parent. The presence of
this indicates that the resource is dynamically reconfigurable.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: An array of integers encoded as
with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,drc-indexes&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>property name</emphasis> denotes an integer index to be used to
communicate to the firmware what connector is to be operated upon for the
various RTAS calls used for DR.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: An integer encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis> specifying
the number of items in the following list, followed by a list of integers also
encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,drc-names&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>property name</emphasis> describes the external labeling of the
DR connectors.</para>
<para><emphasis>prop-encoded-array</emphasis>: An integer encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis> specifying
the number of items in the following list, followed by a list of strings each
encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.</para>
<para>The values shall be the location code for each child node.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,drc-types&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>property name</emphasis>, describes the type of each connector
associated with the node, in a human-readable form.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: An integer encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>
specifying the number of items in the following list, followed by a list of strings each
encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,drc-power-domains&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>property name</emphasis> gives the power domain number for each
connector associated with the node.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: An integer encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>
specifying the number of items in the following list, followed by a list of integers also
encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
<para>A value other than -1 indicates that the coherent platform facility
power is controlled by the
<emphasis>set-power-level</emphasis> RTAS call. A value of -1 indicates that no
<emphasis>set-power-level</emphasis> RTAS call is required.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,phandle&#8221;</literal></emphasis></term>
<listitem>
<para>Package handle for the <emphasis>coherent-platform-facility</emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,cai-version&#8221;</literal></emphasis></term>
<listitem>
<para>Property name, encoded with
<emphasis role="bold"><literal>encode-int</literal></emphasis>,
that describes the CAIA version of the coherent platform facility.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,psl-revision&#8221;</literal></emphasis></term>
<listitem>
<para>Property name, encoded with
<emphasis role="bold"><literal>encode-int</literal></emphasis>,
that describes the PSL revision of the coherent platform facility.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,vpd-size&#8221;</literal></emphasis></term>
<listitem>
<para>The size in bytes, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>,
or the VPD for the <emphasis>ibm,coherent-platform-facility</emphasis>.
This value is used to size the buffer in H_CONTROL_CA_FACILITY with
operation Collect VPD.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;status&#8221;</literal></emphasis></term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> to indicate the operational status
of this device.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: Text string, encoded with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.</para>
<para>If this property is present, the value is a string indicated the
status of the device, as follows:</para>
<variablelist>
<varlistentry>
<term>"okay"</term>
<listitem>
<para>The device is believed to be operational.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>"disabled"</term>
<listitem>
<para>The device represented by this node is not operation, but it
might become operational in the future (e.g., an external switch
is turned off, or something isn’t plugged in.)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>"fail"</term>
<listitem>
<para>The device represented by this node is not operational
because a fault has been detected, and it is unlikely that the
device will become operational without repair. No additional
failure details are available.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>"fail-xxx"</term>
<listitem>
<para>The device represented by this node is not operational
because a fault has been detected, and it is unlikely that
the device will become operational without repair. “xxx” is
additional human-readable information about the particular
fault condition that was detected.</para>
</listitem>
</varlistentry>
</variablelist>
<para>The absence of this property means that the operational status is
unknown or okay.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,privileged-facility&#8221;</literal></emphasis></term>
<listitem>
<para>Property name, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>,
that specifies if the <emphasis>ibm,coherent-platform-facility</emphasis>
is privileged. The absence of this property or a property of 0
indicates the facility is not privileged.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;vendor-id&#8221;</literal></emphasis></term>
<listitem>
<para>Vendor ID from PCI header for the
<emphasis>ibm,coherent-platform-facility</emphasis></para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;device-id&#8221;</literal></emphasis></term>
<listitem>
<para>Device ID from PCI header for the
<emphasis>ibm,coherent-platform-facility</emphasis></para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;revision-id&#8221;</literal></emphasis></term>
<listitem>
<para>Revision ID from PCI header for the
<emphasis>ibm,coherent-platform-facility</emphasis></para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;class-code&#8221;</literal></emphasis></term>
<listitem>
<para>Class Code from PCI header for the
<emphasis>ibm,coherent-platform-facility</emphasis></para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;subsystem-vendor-id&#8221;</literal></emphasis></term>
<listitem>
<para>Subsystem Vendor ID from PCI header for the
<emphasis>ibm,coherent-platform-facility</emphasis></para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;subsystem-id&#8221;</literal></emphasis></term>
<listitem>
<para>Subsystem ID from PCI header for the
<emphasis>ibm,coherent-platform-facility</emphasis></para>
</listitem>
</varlistentry>
</variablelist>
<section xml:id="sec_children_of_the_ibm_coherent_platform_facility_node">
<title>Children of the /ibm,coherent-platform-facility node</title>
<para>The
<emphasis role="bold">ibm,coherent-platform-function</emphasis>
nodes are the children of the
<emphasis role="bold">/ibm,coherent-platform-facility</emphasis>
node represent the individual platform facility functions. Standard property
names associated with the children of the
<emphasis role="bold">/ibm,coherent-platform-facility</emphasis>
node have special values as specified below. Note the children of the
<emphasis role="bold">/ibm,coherent-platform-facility</emphasis>
node shall contain the following standard properties with their standard
definitions:</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;compatible&#8221;</literal></emphasis></term>
<listitem>
<para>Standard <emphasis>property name</emphasis> per
<xref linkend="dbdoclet.50569387_45524"/>
specifying the programming models that are compatible with this coherent
platform function. A value may be present such as “capiVVVV,DDDD.SSSS.ssss”,
where VVVV is “vendor-id”, DDDD is “device-id”, SSSS is “subsystem-vendor-id”
and ssss is “subsystem-id”. The last value of this property shall be
<emphasis role="bold"><literal>&#8220;ibm,coherent-platform-function&#8221;</literal></emphasis>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis></term>
<listitem>
<para>Standard <emphasis>property name</emphasis> per
<xref linkend="dbdoclet.50569387_45524"/>
to define the name of the package. This property is encoded with
<emphasis role="bold"><literal>encode-string</literal></emphasis>
and the value shall be:
<emphasis role="bold"><literal>&#8220;ibm,coherent-platform-function&#8221;</literal></emphasis>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis></term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> that defines the coherent platform
function device handle and mmio address regions.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: List of
(<emphasis>phys-addr, size</emphasis>) specifications.
<itemizedlist mark="none">
<listitem>
<para><emphasis>phys-addr</emphasis> is encoded as with
<emphasis role="bold"><literal>encode-phys</literal></emphasis>,
indicating an address relative to value of the associated
<emphasis>assigned-address</emphasis> value.</para>
</listitem>
<listitem>
<para><emphasis>Size</emphasis> is encoded with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
</listitem>
</itemizedlist>
The first value of the property shall be the handle for use in
hypervisor calls to the coherent platform function. It shall have a
type of Unit Address and size value of 0. This value is always present.</para>
<para>Optionally additional values may be present that specify if
the coherent-platform-function has access to PSL Privilege 2 Area
or AFU Problem State Area indicated by the type field in the
<emphasis>phys-addr</emphasis>.</para>
<para>To calculate the address of memory-mapped area the
<emphasis>assigned-address phys.mid,phys.lo</emphasis>
field is added to the reg
<emphasis>phys.mid,phys.lo</emphasis> field for the matching area
to give the calculated address.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;assigned-addresses&#8221;</literal></emphasis></term>
<listitem>
<para>Property name that defines the coherent platform
function assigned mmio address regions.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: List of
(<emphasis>phys-addr, size</emphasis>) specifications.
<itemizedlist mark="none">
<listitem>
<para><emphasis>phys-addr</emphasis> is encoded as with
<emphasis role="bold"><literal>encode-phys</literal></emphasis>
and denotes the assigned addresses for each register set.</para>
</listitem>
<listitem>
<para><emphasis>size</emphasis> is encoded with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,loc-code&#8221;</literal></emphasis></term>
<listitem>
<para>Property name specifying the unique and persistent location
code associated with this coherent platform function presented
as an encoded array as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.
The value shall be of the form specified in Ux-Px-Cx-Sy-Sz,
where y is a logical platform function unit number and z is the
virtual function unit number.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>Optionally a child node of the
<emphasis role="bold"><literal>/ibm,coherent-platform-facility</literal></emphasis>
node with the
<emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis> of
<emphasis role="bold"><literal>&#8220;ibm,coherent-platform-function&#8221;</literal></emphasis>
may contain as appropriate the following unique properties:</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;device_type&#8221;</literal></emphasis></term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> string encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis> that defines the device type of the
node. For the coherent platform device type the value shall
be the string <emphasis role="bold"><literal>&#8220;ibm,coherent-accel&#8221;</literal></emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,my-drc-index&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>property name</emphasis> denotes an integer index (value of the
entry in the
<emphasis role="bold"><literal>&#8220;ibm,drc-indexes&#8221;</literal></emphasis> property) for the
connector between the node and the node&#8217;s parent. The presence of
this indicates that the resource is dynamically reconfigurable.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: An array of integers encoded as
with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,#processes&#8221;</literal></emphasis></term>
<listitem>
<para>Property name, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>, that
defines the number of operating system processes that can be concurrently
attached to the coherent accelerator function via the H_ATTACH_CA_PROCESS
hcall.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,scratchpad-size&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>Property name</emphasis> that specifies the size of the
scratch pad area supported by the coherent platform function in terms
of cells. The absence of this parameter or a value of 0 indicates the
coherent platform function does not support a scratch pad area.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: Consisting of two integers
(<emphasis>value-hi</emphasis>, <emphasis>value-lo</emphasis>)
each encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>,
such that their combined value is (<emphasis>value-hi</emphasis> ||
<emphasis>value-lo</emphasis>).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,programmable&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>Property name</emphasis>, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>, that
specifies if the coherent platform function can be programmed
(via H_DOWNLOAD_CA_FUNCTION) with a value of 1. The absence of this
parameter or a value of 0 indicates the coherent platform function
does not support programming.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,phandle&#8221;</literal></emphasis></term>
<listitem>
<para>Package handle for the <emphasis>coherent-platform-function</emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,max-ints-per-process&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>Property name</emphasis>, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>, that
specifies the maximum number of interrupts from the
<emphasis role="bold"><literal>&#8220;interrupt-ranges&#8221;</literal></emphasis>
property of the <emphasis>ibm,coherent-platform-facility</emphasis>
that can be assigned per process with the H_ATTACH_CA_PROCESS hcall.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,min-ints-per-process&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>Property name</emphasis>, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>, that
specifies the minimum number of interrupts from the
<emphasis role="bold"><literal>&#8220;interrupt-ranges&#8221;</literal></emphasis>
property of the <emphasis>ibm,coherent-platform-facility</emphasis>
that must be assigned per process with the H_ATTACH_CA_PROCESS hcall.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,max-ints&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>Property name</emphasis>, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>, that
specifies the maximum number of interrupts from the
<emphasis role="bold"><literal>&#8220;interrupt-ranges&#8221;</literal></emphasis>
property of the <emphasis>ibm,coherent-platform-facility</emphasis>
that can be assigned for all processes attached on the
<emphasis>coherent-platform-function</emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,vpd-size&#8221;</literal></emphasis></term>
<listitem>
<para>The size in bytes, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>,
for the VPD for the <emphasis>ibm,coherent-platform-function</emphasis>.
This value is used to size the buffer in H_CONTROL_CA_FUNCTION with
operation Collect VPD.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,error-buffer-size&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>Property name</emphasis> that specifies the error buffer size
for the <emphasis>ibm,coherent-platform-function</emphasis>. This
value is used in H_CONTROL_CA_FUNCTION with operation Get Error Buffer.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: Consisting of two integers
(<emphasis>value-hi</emphasis>, <emphasis>value-lo</emphasis>)
each encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>,
such that their combined value is (<emphasis>value-hi</emphasis> ||
<emphasis>value-lo</emphasis>).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,config-record-type&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>Property name</emphasis>, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>,
that specifies the type of the configuration record for the
<emphasis>ibm,coherent-platform-function</emphasis>.
This value is used to identify the format of the Function Configuration
Record and is defined by the CAIA.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,config-record-size&#8221;</literal></emphasis></term>
<listitem>
<para>
<emphasis>Property name</emphasis> that specifies the size of each configuration
record for the <emphasis>ibm,coherent-platform-function</emphasis>. This
value is used in H_CONTROL_CA_FUNCTION with operation Get Function
Configuration Record</para>
<para>
<emphasis>prop-encoded-array</emphasis>: Consisting of two integers
(<emphasis>value-hi</emphasis>, <emphasis>value-lo</emphasis>)
each encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>,
such that their combined value is (<emphasis>value-hi</emphasis> ||
<emphasis>value-lo</emphasis>).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,#config-records&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>Property name</emphasis>, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>,
that specifies the number of the configuration records for the
<emphasis>ibm,coherent-platform-function</emphasis>.
This value is used in H_CONTROL_CA_FUNCTION with operation Get
Function Configuration Record.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,function-number&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>Property name</emphasis>, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>,
that specifies the function number for the
<emphasis>ibm,coherent-platform-function</emphasis>.
This value is used to call H_DOWNLOAD_CA_FUNCTION and download
images to the function.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,privileged-function&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>Property name</emphasis>, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>,
that specifies if the
<emphasis>ibm,coherent-platform-function</emphasis> is privileged.
The absence of this property or a property of 0 indicates the
function is not privileged.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;vendor-id&#8221;</literal></emphasis></term>
<listitem>
<para>Vendor ID from PCI header for the
<emphasis>ibm,coherent-platform-function</emphasis></para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;device-id&#8221;</literal></emphasis></term>
<listitem>
<para>Device ID from PCI header for the
<emphasis>ibm,coherent-platform-function</emphasis></para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;revision-id&#8221;</literal></emphasis></term>
<listitem>
<para>Revision ID from PCI header for the
<emphasis>ibm,coherent-platform-function</emphasis></para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;class-code&#8221;</literal></emphasis></term>
<listitem>
<para>Class Code from PCI header for the
<emphasis>ibm,coherent-platform-function</emphasis></para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;subsystem-vendor-id&#8221;</literal></emphasis></term>
<listitem>
<para>Subsystem Vendor ID from PCI header for the
<emphasis>ibm,coherent-platform-function</emphasis></para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;subsystem-id&#8221;</literal></emphasis></term>
<listitem>
<para>Subsystem ID from PCI header for the
<emphasis>ibm,coherent-platform-function</emphasis></para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,process-mmio&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>Property name</emphasis>, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>,
that if set to 1, defines that the coherent platform function
utilizes per-process MMIO spaces. The H_ATTACH_CA_PROCESS hcall
returns MMIO address/range information. If this property is 0 or
not present, per-process MMIO is not supported.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,process-mmio-size&#8221;</literal></emphasis></term>
<listitem>
<para>The size in bytes of the per-process MMIO space available for
each attached process. This is the same value that will be returned
in R6 for H_ATTACH_CA_FUNCTION. If the
<emphasis role="bold"><literal>ibm,process-mmio</literal></emphasis>
property is 0 or not present, this property will be 0 or not present.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: Consisting of two integers
(<emphasis>value-hi</emphasis>, <emphasis>value-lo</emphasis>)
each encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>,
such that their combined value is (<emphasis>value-hi</emphasis> ||
<emphasis>value-lo</emphasis>).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,programming-model&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis>, encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>,
describes the programming model currently in effect for the coherent
platform function.</para>
<para>The value shall be one of the following:</para>
<itemizedlist spacing="compact">
<listitem>
<para>"none"</para>
</listitem>
<listitem>
<para>"dedicated-process"</para>
</listitem>
<listitem>
<para>"shared-afu-directed"</para>
</listitem>
<listitem>
<para>"shared-time-sliced"</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,programming-models&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>property name</emphasis>, describes the programming
models supported by the coherent platform function.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: An integer encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis> specifying
the number of items in the following list, followed by a list of
strings each encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.
Each of the values shall be one of the possible values specified
for the
<emphasis role="bold"><literal>&#8220;ibm,programming-model&#8221;</literal></emphasis> property.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,supports-aur&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>Property name</emphasis>, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>,
that if set to 1, defines that the coherent platform function
supports an acceleration utilization record (AUR). If this
property is 0 or not present, the coherent platform function
does not support an AUR.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,supports-csrp&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>Property name</emphasis>, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>,
that if set to 1, defines that the coherent platform function
supports a context / save restore (CSRP). If this property is 0
or not present, the coherent platform function does not support a CSRP.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,supports-prr&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>Property name</emphasis>, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>,
that if set to 1, defines that the coherent platform function
supports paged resolution responses (PRR). If this property is 0
or not present, the coherent platform function does not support
PRR.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;ibm,function-error-interrupt&#8221;</literal></emphasis></term>
<listitem>
<para><emphasis>Property name</emphasis>, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>,
that defines the interrupt source number of the
<emphasis>ibm,coherent-platform-function </emphasis>
error interrupt. An interrupt on this source indicates an error
that is scoped to the entire
<emphasis>ibm,coherent-platform-function</emphasis>.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
</section>
</section>
<section xml:id="dbdoclet.50569368_56107">
<title>Symmetric Multi-Processors (SMP)</title>
<para>LoPAR platforms can have Symmetric Multi-Processor (SMP)
Configurations. In addition to the processor node properties defined in
<xref linkend="dbdoclet.50569374_59715" />, a SMP Configuration will
utilize the
<emphasis>/cpus</emphasis> node as explained in
<xref linkend="dbdoclet.50569368_35974" /></para>
<section xml:id="dbdoclet.50569368_35974">
<title>SMP Platform Device Tree Structure</title>
<para>OF requires that multiple instances of any device that appears more
than once in the device tree must be unique and distinguishable by means
of their
<emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> properties. For LoPAR platforms,
processors shall not be directly attached to the main physical bus (root
node (&#8220;
<emphasis>/</emphasis> &#8221;)). Instead, cpu devices shall be children
of the
<emphasis>/cpus</emphasis> node.</para>
<para>The
<emphasis>/cpus node</emphasis> shall have one child node of device type
cpu for each processor. The
<emphasis>ihandle</emphasis> of the &#8220;executing&#8221; processor
shall
be published in the
<emphasis role="bold"><literal>&#8220;cpu&#8221;</literal></emphasis> property of the
<emphasis role="bold"><literal>/chosen</literal></emphasis> node.</para>
<para>
<emphasis role="bold">Note:</emphasis> The properties of a cpu device are already
defined in
<xref linkend="dbdoclet.50569374_59715" />. The only change for symmetric
multiprocessor (SMP) systems is that there will be a cpu device node
under the
<emphasis>/cpus</emphasis> node for each individual processor. Other
properties of the cpu devices shall
conform with the requirements stated in
<xref linkend="dbdoclet.50569374_59715" />.</para>
</section>
<section>
<title>SMP Properties</title>
<para>The following properties are for a PA SMP environment. These SMP
properties will be under the
<emphasis>/cpus</emphasis> Node.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;slot-names&#8221;</literal></emphasis> [S]</term>
<listitem>
<para><emphasis>property name</emphasis> that describes platform labeling of
plug-in cpu/processor card slots.</para>
<para><emphasis>prop-encoded-array</emphasis>: An integer, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>, followed by a list of strings, each
encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.</para>
<para>The integer portion of the property value is a bitmask of possible
processors; for each add-in slot on the bus, the bit corresponding to
that slot&#8217;s ID number is set from least-significant to
most-significant ID number. The number of following strings is the same
as the number of slots; the first string gives the platform nomenclature
for the slot with the smallest ID number, and so on. The CPU&#8217;s
<emphasis role="bold"><literal>&#8220;slot-names-index&#8221;</literal></emphasis> property can be used
as an index into the bitmask integer of this property. The absence of
this property indicates that no slots are present.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;smp-enabled&#8221;</literal></emphasis> [S]</term>
<listitem>
<para><emphasis>property name</emphasis> that indicates a platform can be SMP
enabled.</para>
<para><emphasis>prop-encoded-array</emphasis>: &lt;NULL&gt;</para>
<para>The presence of this property signifies that the platform is SMP
enabled, even if it only has one processor.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section>
<title>Processor Node</title>
<para>The following properties are for a PA SMP environment. This SMP
property will be under each
<emphasis role="bold"><literal>/cpu</literal></emphasis> Node.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;slot-names-index&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>
<emphasis>property name</emphasis>: Identifies each cpu with a unique
number.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: An integer, encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
<para>The value of this integer is a platform unique number with a range
from 0 to
<emphasis>n-1</emphasis> for each CPU where
<emphasis>n</emphasis> is the number of slots. This number is used to
index into the
<emphasis role="bold"><literal>&#8220;slot-names&#8221;</literal></emphasis> property to identify the
value of the string associated with the slot name.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
</section>
<section>
<title>Device Power Management Properties/Methods</title>
<para>This section defines standard platform node properties, device node
properties, and methods related to power management. The properties and
methods of this section shall be implemented on any platform which supports
power management except where noted. However, it is still being enhanced.
OS providers who want to ensure that the data needed for their power
management policies is included should contact the authors of this
document.</para>
<section>
<title>System Node Properties</title>
<para>The following defines properties are to be associated with the rtas
and the power-management-events nodes of the device tree.</para>
<section>
<title>Properties assigned to the RTAS node</title>
<para>Power domains are a feature of platforms which support power
management. Within the OF device tree, power domains are represented by a
power domain identifier which is defined to be an integer in the range 0
... n-1, where n is the number of power domains on the platform.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;power-domains-tree&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> which defines the power domain
hierarchy for this platform.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: An array of integers, each
encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>, that is a flattened representation of
the power domain dependency tree.</para>
<para>The array consists of a number of tuples, one for each power domain
defined on the platform. Each tuple consists of the power domain
identifier domain#, followed by the number of power levels #levels
supported by the domain, followed by an array of tuples, one for each
level. These tuples consist of a level identifier level, followed by the
number of power sources from which the domain draws power, followed by an
array of tuples (power-source-id, power). The power domain tuple is
terminated by the number of children #children followed by a list of the
domain identifiers of each child. The power values are expressed in
milliamperes and include only the power consumed by support logic not
represented as devices in the device tree including any RTAS abstracted
devices within the particular power domain.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;power-domains-controllers&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> which defines the power domain
controllers present on this platform.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: an array of integers, each
encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
<para>Each integer is the
<emphasis>phandle</emphasis> of the device tree node that functions as the
power domain controller for a domain. A single controller may serve as
the control point for multiple domains (the architecture calls them power
domain control points). Each device which serves as a controller encodes
the
<emphasis role="bold"><literal>&#8220;controls-power-domain&#8221;</literal></emphasis> property.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;power-domains-names&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> used to define the user readable names
for the power domains.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: an array of strings, each
encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>, that are the user readable names for
the domains.</para>
<para>The number of strings matches the number of domains and there is a
one-to-one correspondence between the entries in the
<emphasis role="bold"><literal>&#8220;power-domain-controllers&#8221;</literal></emphasis> property and
the entries in this array.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;platform-power-sources&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> defining the platform power
sources.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: an array of integers, each
encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
<para>The array is structured as a number of tuples. Each of these tuples
consists of the values source-voltage, (given in millivolts), peak-power,
continuous-use-power (both expressed in milliamperes supplied at the
stated voltage), and conversion-efficiency (expressed in percent).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;power-sources-names&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> defining the platform power source
names.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: an array of strings, each
encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>, that are the user readable names for
the power sources.</para>
<para>The number of strings match the number of power sources and is in
one-to-one correspondence to the entries in the
<emphasis role="bold"><literal>&#8220;platform-power-sources&#8221;</literal></emphasis> property.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;platform-battery-sources&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> defining the batteries utilized by a
platform.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: an array of integers, each
encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
<para>Each value in this array is the manufacturer&#8217;s rated capacity
of the battery expressed in milliwatt-hours.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;battery-sources-names&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> defining the human-readable identifier
of the batteries utilized by a platform.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: an array of strings, each
encoded as with
<emphasis role="bold"><literal>encode-string</literal></emphasis>.</para>
<para>Each entry in this array corresponds one-for-one with the batteries
defined in the
<emphasis role="bold"><literal>&#8220;platform-battery-sources&#8221;</literal></emphasis> property.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section>
<title>Properties of the power-management-events node</title>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;power-type&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> defining the power management event
types implemented on a specific platform.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: an array of integers, each
encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
</section>
<section>
<title>Device Properties</title>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;power-domains&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis>, indicating the power domains of which
this device is a member.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: List of one or more
<emphasis>domain-id&#8217;s</emphasis> to which this device belongs.
<emphasis>Domain-id&#8217;s</emphasis> is encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
<para>The
<emphasis role="bold"><literal>&#8220;power-domains&#8221;</literal></emphasis> property should only list
the
<emphasis>domain-id&#8217;s</emphasis> of the lowest power domain tree
nodes in which this device has membership. If the device is a member of
the default power domain 0 alone, this property does not need to be
provided.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;device-power-states&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> which describes the power states this
device supports.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: An array of integers, each
encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis> that defines the supported power states
for this device.</para>
<para>This property shall be provided for each physical device which has
multiple power states, if platform firmware provides device power state
information.</para>
<para>The array consists of an integer representing the initial device
power state after reset, followed by the number of power sources from
which the device draws power, followed by an arbitrary number of tuples,
one for each supported power state of the device. Each tuple consists of
the state, followed by an array of tuples (power-source-id, power) giving
the average power consumption from each power source during active use.
This is followed by another array of tuples (power-source-id, power)
giving the idle power consumption for each power source. Each power state
tuple is terminated by the maximum expected power usage lifetime in
seconds for the device if it were to remain in that state. The value
power is stated in the millamperes consumed at the voltage supplied by
the power source.</para>
<para>The value state shall be further constrained to have the following
semantics:</para>
<table frame="all" pgwide="1">
<title>Semantics of device state values</title>
<?dbhtml table-width="75%" ?>
<?dbfo table-width="75%" ?>
<tgroup cols="2">
<colspec colname="c1" colwidth="20*" align="center" />
<colspec colname="c2" colwidth="80*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Value</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Semantics</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<row>
<entry>
<para>100</para>
</entry>
<entry>
<para>This is the device&#8217;s most responsive state.</para>
</entry>
</row>
<row>
<entry>
<para>20-99</para>
</entry>
<entry>
<para>The device is functional. The range represents a range of
performance.</para>
</entry>
</row>
<row>
<entry>
<para>11-19</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
</row>
<row>
<entry>
<para>10</para>
</entry>
<entry>
<para>Device is not operational, but retains its internal
functional parameters.</para>
</entry>
</row>
<row>
<entry>
<para>1-9</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
</row>
<row>
<entry>
<para>0</para>
</entry>
<entry>
<para>Device not functional, may lose internal functional
parameters.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>The semantics of device power states may be further defined by
device type specific bindings.</para>
<para>The interaction of the defined semantics of device power state and
domain power level is defined in
<xref linkend="dbdoclet.50569368_42921" />. Those combinations not marked
are disallowed.</para>
<table frame="all" pgwide="1" xml:id="dbdoclet.50569368_42921">
<title>Combinations of Device Power State/Domain Power
Level</title>
<?dbhtml table-width="80%" ?>
<?dbfo table-width="80%" ?>
<tgroup cols="6">
<colspec colname="c1" colwidth="16*" align="center" />
<colspec colname="c2" colwidth="16*" align="center" />
<colspec colname="c3" colwidth="16*" align="center" />
<colspec colname="c4" colwidth="16*" align="center" />
<colspec colname="c5" colwidth="16*" align="center" />
<colspec colname="c6" colwidth="16*" align="center" />
<thead>
<row>
<entry morerows="0" nameend="c2" namest="c1">
<para>
<emphasis role="bold">&#160;</emphasis>
</para>
</entry>
<entry nameend="c6" namest="c3">
<para>
<emphasis role="bold">Device Power State</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<row>
<entry morerows="3" valign="middle">
<para>&#160;</para>
<para>Domain Power Level</para>
</entry>
<entry>
<para>Full On</para>
</entry>
<entry>
<para>Allowed</para>
</entry>
<entry>
<para>Allowed</para>
</entry>
<entry>
<para>Allowed</para>
</entry>
<entry>
<para>Allowed</para>
</entry>
</row>
<row>
<entry>
<para>Reduced</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>Allowed</para>
</entry>
<entry>
<para>Allowed</para>
</entry>
<entry>
<para>Allowed</para>
</entry>
</row>
<row>
<entry>
<para>Freeze</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>Allowed</para>
</entry>
<entry>
<para>Allowed</para>
</entry>
</row>
<row>
<entry>
<para>Off</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>&#160;</para>
</entry>
<entry>
<para>Allowed</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;device-state-transitions&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> that describes the legal power state
transitions supported by the device.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: an array of integers, each
encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis> that defines the legal power state
transitions for this device.</para>
<para>The array is structured as a number of tuples, one for each
possible transition. Each tuple consists of the starting state, followed
by the destination state, followed by an array of tuples
(power-source-id, power), one for each power source, followed by the time
required to make the transition in microseconds, followed by the maximum
count allowed for this transition. The starting state and destination
state are values defined in the
<emphasis role="bold"><literal>&#8220;device-power-states&#8221;</literal></emphasis> property. The value
power is stated in the millamperes consumed. This property shall be
provided if platform firmware provides device power state
information.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;power-sources&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> which designates this device as a
consumer of power sourced from a defined power source.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: an array of integers, each
encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis> that gives the list of power sources to
which this device is connected.</para>
<para>The values are indices into the platform-power-sources data
structure. This property shall be provided if platform firmware provides
device power state information.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;power-management-mapping&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> that defines device power states and
commands.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: an array of integers as encoded
with
<emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
<para>This optional property provides a device dependent mapping between
device power state and commands which the device driver sends to its
device. Also provides information concerning which device power states
are supported for each of the four domain power levels. See the device
type binding for a definition of the property value.</para>
</listitem>
</varlistentry>
</variablelist>
<section>
<title>Properties for Power Domain Control Points</title>
<para>The following are specific to devices which can act as power domain
control points.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>&#8220;controls-power-domains&#8221;</literal></emphasis> [S]</term>
<listitem>
<para>Standard
<emphasis>property name</emphasis> which designates the domains over which
this device exercises control.</para>
<para>
<emphasis>prop-encoded-array</emphasis>: an array of integers, each
encoded as with
<emphasis role="bold"><literal>encode-int</literal></emphasis> that defines the domains for which this
device can act a power domain control point.</para>
<para>A single device may serve as multiple logical control
points.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
</section>
<section>
<title>Power Management Related Methods</title>
<para>This section defines methods associated with device tree nodes
which serve as power domain controllers (the architecture calls them
control points).</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold"><literal>set-power-level</literal></emphasis> (domain# level -- actual-level) [M]</term>
<listitem>
<para>This method is only present for power domain controllers. The
domain# is the power domain whose power level is altered, and level is
the desired level. actual-level reports the level to which the domain was
actually set.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>get-power-level</literal></emphasis> (domain# -- level) [M]</term>
<listitem>
<para>This method is only present for power domain controllers. The
domain# is the power domain that is being queried. level is the current
level at which the domain is now operating.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold"><literal>system-off</literal></emphasis> (--) [M]</term>
<listitem>
<para>Method to turn the system off. This method is attached to the root
node of the device tree and is only present in a platform with software
control over system power.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
</section>
<section>
<title>Configuration of Platform Resources</title>
<para>Any computer platform is composed of standard components which are
invariant (platform &#8216;built-in&#8217; standard I/O and power
management), optional components which are detectable (a second processor,
for example), and configurable components which are self-identifying
(system memory, for example). Most computer platforms also provide one or
more industry standard I/O buses which allow the insertion of specialized
functional adapter cards. These buses generally support a method for
automatic identification, interrogation, and option selection of installed
adapter cards.</para>
<para>A Platform shall
also have the capability of configuring power
management resources, if power management is implemented by the platform,
as defined in
<xref linkend="dbdoclet.50569368_25051" />.</para>
<section xml:id="dbdoclet.50569368_25051">
<title>Power Management Resource Configuration</title>
<para>For a platform which supports device power management, all platform
power management related information shall be resident in the OF device
tree prior to the transfer phase of software operation (see the
definition of transfer phase in
<xref linkend="dbdoclet.50569327_31987" />). Dummy devices shall be
placed in the device tree for all standard I/O bus connectors which are
not in use to provide a node to assign the slot-names, power-domains, and
power-sources properties.</para>
<para>Ultimately, the goal is that pluggable devices would not only
identify themselves to platform firmware but would also provide all
applicable power management related information. As an interim solution,
a utility shall be provided either in the platform firmware ROM or
supplied as a loadable OF utility on external media. This utility
interacts with a person to obtain power management information concerning
plug-in adapters and peripherals.</para>
<section>
<title>Power Management Information Utility</title>
<para>Any platform capable of being expanded via the addition of
power-managed devices shall provide a device power management information
utility. The purpose of the utility is to allow a person (end-user or
system developer) to enter power management related device properties of
plug-in adapters and peripherals which have no mechanism to automatically
report this information to firmware or system software. The need for this
utility will disappear as standard protocols are developed for
interrogating pluggable adapters and devices to provide power management
related information.</para>
<para>In the most general case, the devices to be added to a node
representing a standard bus or I/O port are in the form of multilevel
subtrees. The root of this subtree specifies the path to the node in the
device tree where the subtree is to be grafted.</para>
<para>The utility determines the path to the node at which to graft the
new devices by interacting with a person to receive the information. The
utility uses the
<emphasis role="bold"><literal>&#8220;slot-names&#8221;</literal></emphasis> property to identify the
location of the device for which it needs information. For example, the
utility might prompt the user with, &#8220;Enter the name of the first
device attached to the external scsi connector labeled
&#8216;SCSI1&#8217;.&#8221;</para>
<para>A data structure describing the subtree is stored in NVRAM. The
root node of this subtree contains an
<emphasis role="bold"><literal>&#8220;in-graft-node&#8221;</literal></emphasis> property which specifies
the path to the parent node where the subtree is to be grafted into the
OF device tree.</para>
<para>As adapters and devices are enhanced to support the automatic
reporting of power management information the parent node would supply a
method query-power-management-attributes which can be used by firmware to
obtain this information without the need for this utility. Any
information obtained by direct device interrogation may update that
supplied via the PM NVRAM partition.</para>
</section>
<section>
<title>PM Configuration Process</title>
<para>When the platform is booted after a configuration change and the
newly inserted adapter does not support the automatic reporting of power
management information, firmware should prompt the user asking if he
wishes to supply this information or potentially forfeit some or all of
the power management capabilities of the device.</para>
<para>The utility records the information it obtains in the NVRAM Power
Management Configuration Partition (NVRAM Signature of 0x71 and name
<emphasis>pm-config</emphasis>). On a subsequent reboot, platform
firmware uses the information saved in NVRAM to fill out the device tree
adding new nodes and their properties, as well as adding properties and
updating the values of properties of existing device tree nodes.</para>
</section>
<section xml:id="dbdoclet.50569368_35341">
<title>PM Configuration Format</title>
<para>The NVRAM power management configuration partition is designed to
be accessed primarily by firmware, but the partition is designated global
and the format is specified to allow a third party to write a power
management information utility which runs on the booted OS.</para>
<para>The data field of the power management NVRAM partition shall be
defined as follows:</para>
<para>The data field is composed of a header, followed by a number of
fixed length data blocks, and finally a variable length property list
area. The length of the header and each data block is 8 bytes. The data
blocks use 16-bit integer offsets into the partition as pointers to the
data blocks and into the property list area. The base of this offset is
the beginning of the partition. This effectively limits the size of the
PM configuration area to 64 KB. If more space is required, additional PM
configuration partitions may be provided. Each pointer into the property
list area locates the start of a NULL-terminated string which represents
a list of property name/value pairs.</para>
<para>The following table specifies the format of the header:</para>
<table frame="all" pgwide="1">
<title>Power Management Configuration Data Header</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="20*" align="center" />
<colspec colname="c2" colwidth="20*" align="center" />
<colspec colname="c3" colwidth="60*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Field</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Size</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<row>
<entry>
<para>Version</para>
</entry>
<entry>
<para>1 byte</para>
</entry>
<entry>
<para>Designates the version of the PM Partition data area
format</para>
</entry>
</row>
<row>
<entry>
<para>Subtree_ptr</para>
</entry>
<entry>
<para>2 bytes</para>
</entry>
<entry>
<para>Pointer to the first data block which describes a device
subtree</para>
</entry>
</row>
<row>
<entry>
<para>Property_ptr</para>
</entry>
<entry>
<para>2 bytes</para>
</entry>
<entry>
<para>Pointer to first data block which describes a property
list to be added to the base platform device tree</para>
</entry>
</row>
<row>
<entry>
<para>Reserved</para>
</entry>
<entry>
<para>3 bytes</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>The PM Partition data area format value shall be 1.</para>
<para>The following table specifies the format of the data blocks:</para>
<table frame="all" pgwide="1">
<title>Data Block Format</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="20*" align="center" />
<colspec colname="c2" colwidth="20*" align="center" />
<colspec colname="c3" colwidth="60*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Field</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Size</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<row>
<entry>
<para>Block_type</para>
</entry>
<entry>
<para>1 byte</para>
</entry>
<entry>
<para>Designates the data block type</para>
</entry>
</row>
<row>
<entry>
<para>Data Block Data</para>
</entry>
<entry>
<para>7 bytes</para>
</entry>
<entry>
<para>Remainder of data block, format specific to data block
type</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>Two data blocks are defined: one defining a device node and a
second defining properties to be added to the base platform device
tree.</para>
<para>The data block type field shall have the value 1 for a data block
which describes a device node. The data block type field shall have a
value 2 for a data block which describes a property.</para>
<table frame="all" pgwide="1">
<title>Node Data Block Format</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="20*" align="center" />
<colspec colname="c2" colwidth="20*" align="center" />
<colspec colname="c3" colwidth="60*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Field</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Size</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<row>
<entry>
<para>Block_type</para>
</entry>
<entry>
<para>1 byte</para>
</entry>
<entry>
<para>This field shall contain the value 0x01</para>
</entry>
</row>
<row>
<entry>
<para>Prop_list_ptr</para>
</entry>
<entry>
<para>2 bytes</para>
</entry>
<entry>
<para>Pointer to a NULL terminated string containing the
property list for this node</para>
</entry>
</row>
<row>
<entry>
<para>Child_ptr</para>
</entry>
<entry>
<para>2 bytes</para>
</entry>
<entry>
<para>Pointer to a data block defining a child node of this
node. This pointer will be equal to 0x0000 if this node has no
children.</para>
</entry>
</row>
<row>
<entry>
<para>Sibling_ptr</para>
</entry>
<entry>
<para>2 bytes</para>
</entry>
<entry>
<para>Pointer to a data block defining a sibling node of this
node. This pointer will be equal to 0x0000 if this node has no
siblings.</para>
</entry>
</row>
<row>
<entry>
<para>Reserved</para>
</entry>
<entry>
<para>1 byte</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<table frame="all" pgwide="1">
<title>Property Data Block Format</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="20*" align="center" />
<colspec colname="c2" colwidth="20*" align="center" />
<colspec colname="c3" colwidth="60*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Field</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Size</emphasis>
</para>
</entry>
<entry align="center">
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody valign="middle" >
<row>
<entry>
<para>Block_type</para>
</entry>
<entry>
<para>1 byte</para>
</entry>
<entry>
<para>This field shall contain the value 0x02</para>
</entry>
</row>
<row>
<entry>
<para>Node_path</para>
</entry>
<entry>
<para>2 bytes</para>
</entry>
<entry>
<para>Pointer to a NULL terminated string giving the path name
of the node to which the designated property list
belongs.</para>
</entry>
</row>
<row>
<entry>
<para>Property_list_ptr</para>
</entry>
<entry>
<para>2 bytes</para>
</entry>
<entry>
<para>Pointer to a NULL terminated string containing the
property list to be assigned to the designated node.</para>
</entry>
</row>
<row>
<entry>
<para>Reserved</para>
</entry>
<entry>
<para>3 byte</para>
</entry>
<entry>
<para>Reserved</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>The first node of a subtree shall have a
<emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis> property equal to &#8220;/&#8221;
and shall specify the
<emphasis role="bold"><literal>&#8220;in-graft-node&#8221;</literal></emphasis> property. The child_ptr
of this data block points to the first in a list of data blocks which
describe the nodes which make up the subtree to be grafted onto the
system tree.</para>
<para>The final area of the partition is a set of NULL terminated strings
which represent property name/value pair lists. The last string in this
area will be terminated by at least two NULL bytes. The property list for
each node shall provide all the required PM properties and their values.
These include
<emphasis role="bold"><literal>&#8220;power-domains&#8221;</literal></emphasis>,
<emphasis role="bold"><literal>&#8220;device-power-states&#8221;</literal></emphasis>,
<emphasis role="bold"><literal>&#8220;device-state-transitions&#8221;</literal></emphasis>,
<emphasis role="bold"><literal>&#8220;power-sources&#8221;</literal></emphasis>,
<emphasis role="bold"><literal>&#8220;power-management-mapping&#8221;</literal></emphasis>, and
<emphasis role="bold"><literal>&#8220;controls-power-domains&#8221;</literal></emphasis>.</para>
</section>
</section>
</section>
<section>
<title>Client Program Requirements</title>
<para>For LoPAR platforms, the client program requirements are defined in
<xref linkend="dbdoclet.50569374_59715" />, with the following
modifications. OF Client Programs for an LoPAR platform shall execute in
32-bit mode with an OF cell size of 1.</para>
<section>
<title>Load Address</title>
<para>The client&#8217;s load address is specified by the value of the
<emphasis role="bold"><literal>load-base</literal></emphasis> Configuration Variable. The value of
<emphasis role="bold"><literal>load-base</literal></emphasis> defines the default load address for
<emphasis>client programs</emphasis> when using the
<emphasis role="bold"><literal>load</literal></emphasis> method.
<emphasis role="bold"><literal>Load-base</literal></emphasis> shall be a real address in real mode or a
virtual address in virtual mode. Note that this address represents the
area, within the first LMB, into which the client program file will be
read by
<emphasis role="bold"><literal>load</literal></emphasis>; it does not correspond to the addresses at
which the program will be executed. All of physical memory from
<emphasis role="bold"><literal>load-base</literal></emphasis> to either the start of OF physical memory
or the end of physical memory, whichever comes first, shall be available
for loading the client program.</para>
<para>
<emphasis role="bold">Note:</emphasis> The load-base address represents the area into
which the client program will be read by load and does not correspond to
the address at which the program will be executed.</para>
</section>
<section>
<title>Initial Register Values</title>
<para>The &#8220;Initial Register Values&#8221; specified in the PA
Binding (see
<xref linkend="dbdoclet.50569374_59715" />) are modified as
follows:</para>
<itemizedlist>
<listitem>
<para>r3 -- shall be 0 on client program entry</para>
</listitem>
<listitem>
<para>r4 -- shall be 0 on client program entry</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>I/O Devices State</title>
<para>With the exception of the stdin and stdout devices, OF shall close
all devices with the following conditions true:</para>
<para>All Devices - no DMA and not interrupting</para>
<para>Normal I/O Devices - not responding to access PCI
Adapter/Devices</para>
<para>HOST Bridges - responding to config cycles and passing through
config cycles to children</para>
<para>RTAS Devices - contract with OF to leave in state to perform
intended function</para>
</section>
<section xml:id="dbdoclet.50569368_14286">
<title>Client Program Format</title>
<para>The data format of a client program compliant with this
specification shall be either ELF (Executable and Linkage Format) as
defined by
<xref linkend="dbdoclet.50569387_38836" />, and extended by
<xref linkend="dbdoclet.50569368_33033" />, or PE (Portable Executable)
as defined by
<xref linkend="dbdoclet.50569387_18190" />. The standard ELF format
contains explicit indication as to the program's execution modes (e.g.,
32- or 64-bit, Big- or Little-Endian). LoPAR only supports the 32-bit
version (i.e., ELFCLASS32) for 32 and 64 bit platforms.</para>
<para>
<emphasis role="bold">Note:</emphasis> Other client program formats may be supported,
in an implementation specific manner, by an OF implementation.</para>
<para>A standard client program shall be statically linked, requiring no
relocation of the image. The program's entry point (e_entry) shall
contain the address of the first PA instruction of the client program. It
is the responsibility of the client program to establish the appropriate
value of the TOC (r2), if necessary.</para>
<para>
<emphasis role="bold">Note:</emphasis> The entry point is the address of the first
instruction of the client program, not that of a procedure
descriptor.</para>
<section>
<title>ELF-Format</title>
<para>This section defines how OF recognizes and prepares to execute an
ELF-Format Program.</para>
<section xml:id="dbdoclet.50569368_33033">
<title>ELF Note Section</title>
<para>Part of the process of loading a client program involves verifying
its environmental requirements (e.g., endian-ness and address translation
mode) against the current firmware configuration. The client&#8217;s
endian-ness can be directly determined by examining the ELF EI-DATA
value; ELFDATA2LSB (1) implies Little-Endian while ELFDATA2MSB (2)
implies Big-Endian. However, the other client requirements (e.g., address
translation mode) are defined by means of an ELF Note Section (PT_NOTE),
pointed to by the program header. The following describes the format of
the Note Section for a client program file.</para>
<para>As defined by
<xref linkend="dbdoclet.50569387_38836" />, an ELF file can be
&#8220;annotated&#8221; by means of Note Sections within the executable
file. A Note Section contains a &#8220;header&#8221; followed by a
(possibly NULL) &#8220;descriptor&#8221;, as follows:</para>
<informalfigure>
<mediaobject>
<imageobject role="html">
<imagedata fileref="figures/PAPR-61.gif" format="GIF"
scalefit="1" />
</imageobject>
<imageobject role="fo">
<imagedata contentdepth="100%" fileref="figures/PAPR-61.gif"
format="GIF" scalefit="1" width="100%" />
</imageobject>
</mediaobject>
</informalfigure>
<para>
<emphasis role="bold">Note:</emphasis> The endian format of the values corresponds to
the endian-ness specified by the EI-DATA field of the file.</para>
<para>The format of a Note Section header can be described by an OF
struct as:</para>
<programlisting><![CDATA[struct \ Note Section header for OF
/L field ns.namesz \ length of ns.name, including NULL
/L field ns.descrsz
/L field ns.type
0 field ns.name \ NULL-terminated, /L padded]]></programlisting>
<section>
<title>1275 PowerPC Note Definition</title>
<para>The ns.name field of the PowerPC OF Note Section shall be
<emphasis role="bold"><literal>&#8220;PowerPC&#8221;</literal></emphasis>; the ns.type field n shall be
0x1275.</para>
<para>Following the Note Section header is a descriptor (desc); the
length (in bytes) of the descriptor is specified by a word in the Note
Section&#8217;s header (descsz). The interpretation of the descriptor
depends upon the kind of Note Section in which it is contained. For the
PowerPC OF note, the format of the Note Section&#8217;s descriptor can be
described by an OF struct, as follows:</para>
<programlisting><![CDATA[struct \ Note Section descriptor for CHRP OF</para>
/L field ns.real-mode
/L field ns.real-base
/L field ns.real-size
/L field ns.virt-base
/L field ns.virt-size
/L field ns.load-base]]></programlisting>
<para>If the
<emphasis role="bold"><literal>ns.load-base</literal></emphasis> value is not -1, then that value is
compared against the current value of the
<emphasis role="bold"><literal>load-base</literal></emphasis> configuration variable. If they are equal
no further action is taken. If they are not equal then the
<emphasis role="bold"><literal>load-base</literal></emphasis> configuration variable is set to the value
of
<emphasis role="bold"><literal>ns.load-base</literal></emphasis> and the system is rebooted.</para>
<para>
<emphasis role="bold">Note:</emphasis> DATA field of the file.</para>
</section>
<section>
<title>1275 IBM,RPA-Client-Config Note Definition</title>
<para>The ns.name field of the LoPAR Client Program Configuration Note
Section shall be
<emphasis role="bold"><literal>&#8220;IBM,RPA-Client-Config&#8221;</literal></emphasis>; the ns.type
field shall be 0x12759999.</para>
<para>The format and requirements associated with this ELF Note Section
are designed to allow for expandability of the section definition (by
adding fields to the end of the section) while retaining forward and
backward compatibility for both the 1275 firmware and Client Program.
When the 1275 firmware code recognizes the
<emphasis role="bold"><literal>&#8220;IBM,RPA-Client-Config&#8221;</literal></emphasis> note, it creates
a property named
<emphasis role="bold"><literal>&#8220;ibm,rpa-client-config&#8221;</literal></emphasis> within the
<emphasis role="bold"><literal>/chosen</literal></emphasis> node reads into this property and interprets
the lesser of the descriptor size or the maximum size of the descriptor
that was defined when the firmware was built. Should the note contain a
smaller descriptor than was defined when the firmware was built, the
firmware assumes default values for the missing descriptor fields. In
this way, new fields may be defined, and the four cases of
firmware/client program work as follows:</para>
<para>New Firmware/New Client Program:</para>
<para>Client Program Header Note contains old plus new fields.</para>
<para>Firmware reads all the new header and places it in
<emphasis role="bold"><literal>&#8220;ibm,rpa-client-config&#8221;</literal></emphasis> property.</para>
<para>Client Program gets feed back that new fields were interpreted by
reading property in
<emphasis role="bold"><literal>/chosen</literal></emphasis>.</para>
<para>Old Firmware/Old Client Program:</para>
<para>Client Program Header Note contains old fields.</para>
<para>Firmware reads all the old definition header and places it in
<emphasis role="bold"><literal>&#8220;ibm,rpa-client-config&#8221;</literal></emphasis> property.</para>
<para>Client Program gets feed back that the expected fields were
interpreted by reading property in
<emphasis role="bold"><literal>/chosen</literal></emphasis>.</para>
<para>New Firmware/Old Client Program:</para>
<para>Client Program Header Note contains only old fields.</para>
<para>Firmware reads only the descriptor length defined in the note
header, and places it in
<emphasis role="bold"><literal>&#8220;ibm,rpa-client-config&#8221;</literal></emphasis> property.</para>
<para>Client Program gets feed back on the fields that were interpreted
by reading property in
<emphasis role="bold"><literal>/chosen</literal></emphasis>.</para>
<para>Firmware uses default values for any missing fields.</para>
<para>Old Firmware/New Client Program:</para>
<para>Client Program Header Note contains old plus new fields.</para>
<para>Firmware reads only the length that it was defined when it was
built, and places it in
<emphasis role="bold"><literal>&#8220;ibm,rpa-client-config&#8221;</literal></emphasis> property.</para>
<para>Client Program gets feed back that new fields were interpreted by
reading property in
<emphasis role="bold"><literal>/chosen</literal></emphasis>, those missing fields indicate function not
implemented by the platform.</para>
<para>Following the Note Section header is a descriptor (desc); the
length (in bytes) of the descriptor is specified by a word in the Note
Section&#8217;s header (descsz). The interpretation of the descriptor
depends upon the kind of Note Section in which it is contained. For the
ELF header note named <emphasis role="bold"><literal>IBM,RPA-Client-Config</literal></emphasis> of type 1275, the format of
the Note Section&#8217;s descriptor can be described by an OF struct, as
follows:</para>
<programlisting><![CDATA[struct \ Note Section descriptor for OF
/L field ns.lparaffinity \= “0/1” (default assumption to be “N”)
/L field ns.min-rmo-size \Minimum size of the Real Mode Accessible Storage
\ Area in MB
/L field ns.min-rmo-percent \Minimum percentage of total storage that must be
\ Real Mode Accessible
/L field ns.max-pft-size \Maximum size of the hardware page frame table as
\ a power of 2
/L field ns.splpar \= “0/1” (default assumption to be “N”)
/L field ns.min-load \The minimum amount of code that must be loaded at
\ load-base.
\ (default value -1)
/L field ns.new-mem-def \Flag to indicate use of
\ ibm,dynamic-reconfiguration-memory definition.
\ (default value 0)
/L field ns.ignore-my-client-config \Flag: 1 = do not change boot configuration
\ variables based upon the values in this
\ header.
\ (default value 0)
/L field ns.large-page-ready \Flag to indicate the partition OS is prepared for
\ large pages.
/L field ns.force_alpha_mode]]></programlisting>
<para><emphasis role="bold">Note:</emphasis> The size of the /L field is based off of
e_ident (EI_CLASS) i.e. is 4 for ELFCLASS32.</para>
<para>The
<emphasis role="bold"><literal>ns.lparaffinity</literal></emphasis> field is a binary flag whose valid
values are 0 or 1. If the field is not one of these valid values the
value is assumed to be 0. If the character value is 1, the client program
requests that the platform provide all available affinity
information.</para>
<para>The
<emphasis role="bold"><literal>ns.min-rmo</literal></emphasis> field specifies the minimum amount of real
mode addressable storage (in bytes times 2
<emphasis>20</emphasis>) that the client program needs to operate. The
<emphasis role="bold"><literal>ns.min-rmo-percent</literal></emphasis> field specifies the minimum
percentage (valid values 0-100) of storage that must be real mode
addressable for the client program to operate. The platform shall start
the client program with a quantity of real mode accessible storage
(starting at location 0) of at least the ceiling of these two
values.</para>
<para>The
<emphasis role="bold"><literal>ns.max-pft-size</literal></emphasis> field value specifies the largest
hardware Page Frame Table (in bytes times</para>
<para>2
<emphasis role="bold"><literal>ns.max-pft-size</literal></emphasis>) that the client program can
support. The firmware shall not start a client program with a PFT larger
than this amount The minimum value is 18, the platform ignores the field
if the value is less than 18 and uses the platform defined default
value.</para>
<para>The
<emphasis role="bold"><literal>ns.splpar</literal></emphasis> field is a binary flag whose valid values
are 0 or 1. If the field is not one of these valid values the value is
assumed to be 0. If the field&#8217;s value is 1, the client program
supports running in shared processor logical partitioning mode. If the
character value is not 1 and the partition is running in shared processor
mode, platform firmware reports a platform-specific error code and halts
the boot. However, if the client-program does not contain an
<emphasis role="bold"><literal>IBM,RPA-Client-Config</literal></emphasis>
note, firmware assumes the OS supports shared
processor logical partition mode. This exception only applies to the
<emphasis role="bold"><literal>ns.slpar</literal></emphasis> field.</para>
<para>The
<emphasis role="bold"><literal>ns.min-load</literal></emphasis> field specifies the minimum amount of the
client program load module that must be loaded at
<emphasis role="bold"><literal>load-base</literal></emphasis>. If this value is a -1 then the entire
load module must be loaded starting at
<emphasis role="bold"><literal>load-base</literal></emphasis> else the client program load fails. The
default value is assumed to be -1. If the value of is greater than the
platform can support client program load fails. Given that the platform
can load the minimum amount of the client program load module at
<emphasis role="bold"><literal>load-base</literal></emphasis>, it loads the amount up to the boundary
specified by
<emphasis role="bold"><literal>ns.min-load</literal></emphasis> starting at
<emphasis role="bold"><literal>load-base</literal></emphasis>, then it loads the rest of the load module
into contiguous storage at a location selected by platform firmware
(default, if possible, is that the residual is loaded immediately
following the first segment resulting in a single segment load).</para>
<para>The
<emphasis role="bold"><literal>ns.new-mem-def</literal></emphasis> field is a flag which indicates if the
ibm,dynamic-reconfiguration-memory representation of reconfigurable
memory may be used. The default value 0x00000000 indicates the new
definition may not be used. The value 0x00000001 indicates the new
definition may be used. The value 0x00000001 indicates the original version of the new definition may be used.
The value 0x00000002 indicates the version 2 of the new definition may be used.
All other values are reserved for future use.</para>
<para>The
<emphasis role="bold"><literal>ns.large-page-ready</literal></emphasis> field is a flag which indicates
if the partition OS is prepared to support large pages. The default value
0x00000000 indicates that the OS is not prepared for large pages. The
value 0x00000001 indicates that the OS is prepared for large pages. All
other values are reserved for future use.</para>
<para>If this variable indicates that the OS is not prepared for large
pages and large pages are present in the partition configuration,
platform firmware reports a platform-specific error code which indicates
this mismatch between the partition configuration and the OS
capabilities, removes all large pages from the device tree, and continues
the OS boot.</para>
<para>If the value of the
<emphasis role="bold"><literal>ns.ignore-my-client-config</literal></emphasis> variable is 0x00000001,
platform firmware must not examine the value of
<emphasis role="bold"><literal>ns.large-page-ready</literal></emphasis> until the client program calls
the PROCESS-ELF-HEADER method. The decision to continue boot should then
be made based on the value of the
<emphasis role="bold"><literal>ns.large-page-ready</literal></emphasis> flag in the updated ELF head
passed by this method.</para>
<para>The
<emphasis role="bold"><literal>ns.force_alpha_mode</literal></emphasis> field is a flag which indicates
that a non-HMC managed I/O services partition with partition management
support (VMC) configuration is being requested. The default value of
0x00000000 indicates that the client expects to run in a configuration
which is not an I/O services partition configuration. If the partition
configuration is not compatible with this setting, the system will be
rebooted as a single partition which owns all of the system resources. On
reboot, the original partition configuration will be reinstated. The
value 0x0000001 indicates that the client is expecting to be executed in
a non-HMC managed I/O services partition with partition management
support (VMC). If the partition is not in this mode, the system will be
rebooted in this mode. In the case that the ns.force_alpha_mode flag is
compatible with the partition configuration, the boot process will
continue. This flag will be ignored when the system is HMC
managed.</para>
</section>
</section>
<section xml:id="dbdoclet.50569368_24653">
<title>Recognizing ELF-Format Programs</title>
<para>The
<emphasis role="bold"><literal>init-program</literal></emphasis> shall recognize client program images
that conform to all the requirements listed below as
&#8220;ELF-format&#8221; programs.</para>
<para>In the description below, field names refer to fields within the
ELF &#8220;file header&#8221; structure, which is assumed to begin at
load-base, and offsets are relative to the beginning of that structure.
Multi-byte numerical fields are interpreted according to the endianess
specified by the &#8220;data&#8221; field at offset 5.</para>
<orderedlist numeration="loweralpha">
<listitem>
<para>The &#8220;e_ident&#8221; field (at offset 0) contains the
string &#8220;\7fELF&#8221;, where '\7f'&#8217; is a byte whose value is
(hex) 7f. This indicates the beginning of an ELF file header.</para>
</listitem>
<listitem>
<para>The &#8220;EI_CLASS&#8221; field (at offset 4) contains the
value 1. This indicates the 32-bit variant of the ELF format.</para>
</listitem>
<listitem>
<para>The &#8220;e-type&#8221; field (at offset 16) contains the
value 2. This indicates that the ELF image is executable.</para>
</listitem>
<listitem>
<para>The &#8220;e_machine&#8221; field (at offset 18) contains the
value 20. This indicates that the ELF image is for the PA instruction
set.</para>
</listitem>
<listitem>
<para>The &#8220;e_version&#8221; field (at offset 20) contains the
value 1.</para>
</listitem>
<listitem>
<para>The &#8220;e_flags&#8221; field (at offset 36) contains the
value 0.</para>
</listitem>
</orderedlist>
</section>
<section xml:id="dbdoclet.50569368_30006">
<title>Preparing ELF-Format Programs for Execution</title>
<para>Upon recognition of the client program image at load-base as an
ELF-format program, init-program shall prepare the program for execution
by performing the following sequence of steps.</para>
<para>In the description below, the fields mentioned by name are within
ELF &#8220;program header&#8221; structures, unless specified
otherwise.</para>
<orderedlist numeration="loweralpha">
<listitem>
<para>Search for an ELF &#8220;note&#8221; section of type
&#8220;1275&#8221; as defined in the section &#8220;ELF Note
Section&#8221;. If one is found, and the values specified by its
descriptor do not match the firmware's current operating mode, set the
appropriate configuration variables to the values specified in the note
section descriptor, and restart the firmware so that it will re-execute
the
<emphasis role="bold"><literal>boot</literal></emphasis> command that resulted in the execution of
<emphasis role="bold"><literal>init-program</literal></emphasis>.</para>
</listitem>
<listitem>
<para>Set the p_paddr field for each PT_LOAD segment equal to its
p_vaddr field value if
<emphasis>real-mode?</emphasis> is false and p_paddr is -1. This
effectively maps these segments v=r.</para>
</listitem>
<listitem>
<para>Allocate and map, if required, sufficient physical memory for
all program segments of type PT_LOAD (i.e. whose &#8220;p_type&#8221;
field contains the value 1) listed in the ELF image's program headers.
Note that all PT_LOAD program segments that have a p_paddr value that
matches their location in physical memory need not be moved, but the
memory that they occupy must be claimed. This special case is added to
allow large program images to be loaded without the 2x memory required to
move the segments.</para>
</listitem>
<listitem>
<para>Copy the program headers to a &#8220;safe&#8221; location to
guard against the possibility of them being overwritten by the following
steps.</para>
</listitem>
<listitem>
<para>For each program segment of type &#8220;PT_LOAD&#8221;:</para>
<orderedlist>
<listitem>
<para>Copy, if required, the initialized portion of the program
segment from its current location in the loaded image to the location
given by the section's &#8220;p_paddr&#8221; field.</para>
</listitem>
<listitem>
<para>Fill the rest of the segment with zero bytes (i.e., fill
&#8220;p_memsz - p_filez&#8221; bytes beginning at the address
&#8220;p_paddr + p_filesz&#8221;).</para>
</listitem>
<listitem>
<para>If <emphasis>real-mode?</emphasis> is false, then map the program segment to
the virtual address specified by p_vaddr.</para>
</listitem>
</orderedlist>
</listitem>
<listitem>
<para>Set the saved program state so that subsequent execution of
<emphasis role="bold"><literal>&#8220;go&#8221;</literal></emphasis> will begin execution at the address
given by the &#8220;e_entry&#8221; field in the ELF file header. The
e_entry field is a physical address if
<emphasis>real-mode?</emphasis> is
<emphasis role="bold"><literal>TRUE</literal></emphasis> and is a virtual address if
<emphasis>real-mode?</emphasis> is
<emphasis role="bold"><literal>false</literal></emphasis>.</para>
</listitem>
</orderedlist>
<para>The implementation need not take precautions to ensure that the
process of copying and zeroing program segments does not overwrite the
portions of the load image that have not yet been copied. In order to
guarantee correct copying, the value of the
<emphasis role="bold"><literal>load-base</literal></emphasis> configuration variable and the destination
addresses of the various sections must be such that such overwriting does
not occur. One sufficient condition is that the region of memory
beginning at
<emphasis role="bold"><literal>load-base</literal></emphasis>, of size equal to the size of the loaded
image, be disjoint from the regions of memory to which the program
segments are copied and zero-filled. Another sufficient condition is to
specify a
<emphasis role="bold"><literal>load-base</literal></emphasis> in the Notes Section (PT_NOTE) that ensures
that the PT_LOAD segments are loaded at the address required by their
program headers and thus are not moved. There are other less-stringent
sufficient conditions, especially for simple ELF images with a small
number of program segments that are to be copied to contiguous
regions.</para>
<para>An implementation shall permit the ELF image to contain other
program segments in addition to those described above, but need not take
any action beyond that defined above as a result of the presence of such
other program segments.</para>
<para>An implementation shall ignore all ELF sections. ELF sections are
intended for binders, not loaders. Note that the CHRP ELF Note Section is
actual an ELF segment of type PT_NOTE and thus the above does not apply
to it.</para>
</section>
</section>
</section>
<section>
<title>Additional Client Interface Requirements</title>
<para>This section describes processor assist callbacks for real and
virtual memory management and a service.</para>
<section>
<title>Client Interface Callbacks</title>
<para>This section describes callbacks for memory management. These
callbacks are provided by the client.</para>
<section xml:id="dbdoclet.50569368_11616">
<title>Real-Mode Memory Management Assist Callbacks</title>
<variablelist>
<varlistentry>
<term>claim_mem</term>
<listitem>
<para>IN: [address] min_addr, [address] max_addr, size, align</para>
<para>OUT: throw-code, error, [address] real_addr</para>
<para>Allocate contiguous physical memory between min_addr and max_addr
of size bytes (128KB max for an area in the 0 to 16MB address range),
with align alignment. The alignment boundary is the smallest power of two
greater than or equal to the value of align; an align value of 1
signifies one-byte alignment. A non-zero error code shall be returned if
the mapping cannot be performed. If error code is zero (i.e. allocation
succeeded) the routine returns the real address (real_addr) of the
physical memory block which was allocated for OF.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>release_mem</term>
<listitem>
<para>IN: [address] phys, size</para>
<para>OUT: throw-code</para>
<para>Free size bytes of physical memory starting at real address phys,
making that physical memory available for later use. That memory must
have been previously allocated by claim_mem.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="dbdoclet.50569368_11616.1">
<title>Virtual Address Translation Assist Callbacks</title>
<variablelist>
<varlistentry>
<term>alloc_virt_mem</term>
<listitem>
<para>IN: size</para>
<para>OUT: throw-code, error, [address] virt_addr</para>
<para>Return the virtual address of a virtual memory area of size bytes
aligned to a doubleword (8-byte) boundary. A non-zero error code shall be
returned if the allocation cannot be performed. If error code is zero
(i.e. allocation succeeded) the routine returns the virtual address
(virt_addr) of the memory block which was allocated.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>free_virt_mem</term>
<listitem>
<para>IN: [address] virt_addr, size</para>
<para>OUT: throw-code</para>
<para>Free memory allocated by alloc_virt_mem. The values virt_addr and
size must correspond with memory previously allocated by
alloc_virt_mem.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>claim_virt</term>
<listitem>
<para>IN: size, align</para>
<para>OUT: throw-code, error, [address] virt_addr</para>
<para>Allocate a memory area of size bytes and alignment align. The
alignment boundary is the smallest power of two greater than or equal to
the value of align; an align value of 1 signifies one-byte alignment. A
non-zero error code shall be returned if the allocation cannot be
performed. If error code is zero (i.e. allocation succeeded) the routine
returns the virtual address (virt_addr) of the memory block which was
allocated.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>release_virt</term>
<listitem>
<para>IN: [address] virt, size</para>
<para>OUT: throw-code</para>
<para>Free size bytes of virtual memory starting at virtual address virt,
making that physical memory and the corresponding ranges of virtual
address space available for later use. That memory must have been
previously allocated by claim_virt.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
</section>
<section xml:id="dbdoclet.50569368_25059">
<title>Client Interface Services</title>
<para>OF shall provide the following
<emphasis>Client Interface Service</emphasis>:</para>
<variablelist>
<varlistentry>
<term>test-method</term>
<listitem>
<para>IN: phandle, [string] method</para>
<para>OUT: missing-flag?</para>
<para>Tests whether the package method named method exists in the package
phandle. missing-flag? is FALSE (0) if the method exists or TRUE (-1) if
the method does not exist.</para>
</listitem>
</varlistentry>
</variablelist>
<para>OF may provide the following Client Interface Service:</para>
<variablelist>
<varlistentry>
<term>ibm,enable-ci64</term>
<listitem>
<para>IN: none</para>
<para>OUT: none</para>
<para>After the successful invocation of this method, all Client
Interface calls will utilize 64 bit cell items in their argument arrays.
This does not affect how the device tree is presented, which will still
assume that a cell is 32 bit in the property values. The method returns
using the cell size in which it was called. This method exists only on
platforms that present the
<emphasis role="bold"><literal>&#8220;ibm,enable-ci64-capable&#8221;</literal></emphasis> property in the
<emphasis>root</emphasis> node.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
</section>
</section>
<section xml:id="dbdoclet.50569368_19625">
<title>Support Packages</title>
<para>This section describes the LoPAR Binding specific requirements of OF
support packages. These support packages are
<emphasis role="bold"><literal>disk-label</literal></emphasis> and
<emphasis role="bold"><literal>tape-label</literal></emphasis>. For &#8220;network&#8221; and/or
<emphasis role="bold"><literal>obp-tftp</literal></emphasis> extensions, refer to
<xref linkend="dbdoclet.50569387_33177" />. These packages support the
loading and executing of a client program. Another means of executing a
Client Program is provided when an OS ROM is a &#8220;bootable
device&#8221; (Refer to
<xref linkend="dbdoclet.50569368_40198" />, as an example).</para>
<section>
<title>&#8220;disk-label&#8221; Support Package</title>
<para>The process of loading and executing a client program is described
in two stages. The first stage determines what partition and/or file (if
one exists) to read into memory. This is done by locating a partition and
a file within the partition (if the partition supports a file system
structure) from the boot device, usually by means of a name lookup within
a directory contained within a disk &#8220;partition&#8221;. The second
stage examines the front portion (header) of the image for
&#8220;well-known&#8221; program formats. When the format of the image
has been determined, the loading is completed in a manner determined by
that format.</para>
<para>The name of the partition (and, a file contained within the
partition) can be explicitly specified by the user via the
<emphasis role="bold"><literal>load</literal></emphasis> or
<emphasis role="bold"><literal>boot</literal></emphasis> command, or can be implicitly specified by the
value of the
<emphasis role="bold"><literal>&#8220;boot-device&#8221;</literal></emphasis>
property of the
<emphasis role="bold"><literal>/options</literal></emphasis> node. The partition and filename are the
ARGUMENTS portion of the final COMPONENT of the PATH_NAME, as described
in section 4.3.1 of
<xref linkend="dbdoclet.50569387_45524" />.</para>
<para>The syntax for explicit partition/filename specification is given
in section
<xref linkend="dbdoclet.50569368_88157" /> below where partition
identifies the partition to be used and filename is the name of a file
within that partition. If partition is omitted, the default partition (as
determined by the partition format) is used. If filename is omitted, the
default filename (i.e., the filename component of the
<emphasis role="bold"><literal>boot-device</literal></emphasis> path-name) is used.</para>
<section>
<title>Media Layout Format</title>
<para>This section describes the media layout formats of Client Program
Images that the disk-label support package for an LoPAR platform shall
support; an implementation
<emphasis>may</emphasis> support additional mechanisms, in an
implementation-specific manner. The
<emphasis role="bold"><literal>disk-label</literal></emphasis> package for a platform shall
support at least four(4) media layout types:</para>
<itemizedlist>
<listitem>
<para>FAT (FAT12 and FAT16 File System)</para>
</listitem>
<listitem>
<para>FDISK (Partitions 4, 5, 6, 0x41 and 0x96)</para>
</listitem>
<listitem>
<para>ISO-9660 (9660 File System)</para>
</listitem>
<listitem>
<para>UDF</para>
</listitem>
</itemizedlist>
<para>An LoPAR platform may choose to support the following media layout
formats for historic reasons:</para>
<itemizedlist>
<listitem>
<para>Mac OS (MAC Binary Image)</para>
</listitem>
</itemizedlist>
<section>
<title>FDISK Partition Types</title>
<para>The following FDISK partition types shall be supported:</para>
<itemizedlist>
<listitem>
<para>Partition Type 4: FAT 12 or FAT 16 File System</para>
</listitem>
<listitem>
<para>Partition Type 5: Extended Chained Partitions</para>
</listitem>
<listitem>
<para>Partition Type 6: Extended Partitions</para>
</listitem>
<listitem>
<para>Partition Type 0x41: Single program image</para>
</listitem>
<listitem>
<para>Partition Type 0x96: ISO 9660 File System</para>
</listitem>
<listitem>
<para>Partition Type 0x??: UDF File System</para>
</listitem>
</itemizedlist>
<para>FDISK partition type 0 is a free partition. Partition type 0x82 is
reserved and should not be used by this architecture.</para>
</section>
</section>
<section xml:id="dbdoclet.50569368_88157">
<title>Open Method Algorithm</title>
<para>The
<emphasis role="bold"><literal>open</literal></emphasis> method of the
<emphasis role="bold"><literal>disk-label</literal></emphasis> support package shall implement a disk
partition recognition algorithm that supports at least the set of disk
formats that are supported by the following algorithm. The following
algorithm is intended to support raw (uninterpreted) disks, raw
partitions of disks beginning with an FDISK partition map, and files on
FAT, UDF and ISO-9660 file systems both within FDISK partitions and by
themselves on disks without a partition map.</para>
<para>That
<emphasis role="bold"><literal>open</literal></emphasis> method shall accept an argument string (as
returned by
<emphasis role="bold"><literal>&#8220;my-args&#8221;</literal></emphasis>) with the following syntax
(according to the algorithm below), where brackets denote an optional
component:</para>
<para>[partition][,[filename]]</para>
<para>If the argument string contains a comma, or if the argument string
begins with a decimal digit, the partition component is deemed to be
present. Note that the arguments above are not the client arguments with
the boot command.</para>
<para>If the partition component is present, it selects the desired
partition, where partition 0 refers to the entire disk, partition 1
refers to the first partition, partition 2 to the second, and so forth.
If the partition component is absent and the disk has an FDISK or Mac
partition map, the first &#8220;bootable&#8221; partition is used. If a
&#8220;bootable&#8221; partition is not found, then fail in an
implementation specific manner with an error.</para>
<para>If the filename component is present, it selects a particular file
within the file system on the disk or partition thereof.</para>
<para>
<emphasis role="bold">Note:</emphasis> For historic reasons, the following algorithm
includes support for the optional MAC OS media layout format.
<programlisting><![CDATA[1 OPEN algorithm
2 Set D.SIZE to -1
2 If ARGUMENT$ is not the NULL string and the first character of ARGUMENT$
is in the range '0'--'9' or is equal to ','
3 LEFT-PARSE (ARGUMENT$) -> PARTITION$, FILENAME$
2 Else
3 Set PARTITION$ to the NULL string
3 Set FILENAME$ to ARGUMENT$
2 If PARTITION$ is not the NULL string
3 If PARTITION$ is not a decimal number
4 Return FALSE
3 DECIMAL_STRING_TO_NUMBER (PARTITION$) -> PARTITION
3 If PARTITION is 0
4 GET_DISK_SIZE
3 Else
4 Read the first 512 bytes of the device into a buffer
4 SELECT_EXPLICIT_PARTITION (PARTITION)
4 If SELECT_EXPLICIT_PARTITION returned an error indication
5 Return FALSE
2 Else \ PARTITION$ is NULL
3 Read the first 512 bytes of the device into a buffer
3 SELECT_ACTIVE_PARTITION
3 If SELECT_ACTIVE_PARTITION returned an error indication
4 Return FALSE
2 \ (At this point, D.OFFSET is set to the beginning of the selected
partition and D.SIZE is set to the size of that partition. If the
entire disk was selected, D.OFFSET is 0 and D.SIZE is the size of the disk.)
2 Call parent’s “seek” method with an argument of 0,0.
2 Return TRUE
1 CHECK_FOR_BPB procedure
2 If the first four(4) bytes are EBCDIC 'IBMA'(hex character string
C9C2D4C1), then the sector does not contain a BPB.
2 If the 16-bit little-endian quantity beginning at buffer offset 510
is 0xAA55, and the 16-bit little-endian quantity beginning at buffer
offset 11 (which is the BPB “bytes per sector” field) is either 256,
512, or 1024, and the byte at offset 16 (the BPB “number of FATs” field
is either 1 or 2, the sector is deemed to contain a BPB. Otherwise, the
sector does not contain a BPB.
1 CHECK_FOR_ISO_9660 procedure
2 Read 512-byte sector 64 (the beginning of logical 2048-byte sector 16)into
a buffer.
2 If the byte at offset 0 contains the binary number “1”, and the 5 bytes
beginning at offset 1 contains the text string “CD001”, the partition
or raw disk is deemed to contain an ISO 9660 file system. Otherwise,
the partition or raw disk is deemed not to contain an ISO 9660 file system.
1 CHECK_FOR_FDISK procedure
2 If the buffer does not contain an FDisk partition map signature of “AA55”
as a 16-bit little-endian number beginning at buffer offset 510, the buffer
is deemed not to contain an FDISK partition map.
2 If none of the partition type code field (the bytes at buffer offsets 0x1C2,
0x1D2, 0x1E2, and 0x1F2) contains a recognizable partition type code (4,5,
6, 0x41, 0x96, or other types that may be recognized by the implementation),
the buffer is deemed not to contain an FDISK partition map.
2 Otherwise, the buffer is deemed to contain an FDISK partition map.
2 The implementation may, at its option, apply additional validity tests to
the partition map information.
1 CHECK_FOR_MAC_DISK procedure
2 If the first (i.e., at the lowest offset) two bytes in the buffer contains
the 16-bit big-endian signature 0x4552, then the disk is deemed to be a Mac
partitioned disk. Otherwise, the partition or raw disk is deemed not to be
a Mac partitioned disk.]]></programlisting></para>
<para>
<emphasis role="bold">Note:</emphasis> Subsequent 512 byte sectors will contain Mac
partition map entries, each of which begins with the 16-bit big-endian
signature 0x504D. Each such partition map entry contains a field (V)
indicating the total number of partition entries in the map.</para>
<para><programlisting><![CDATA[1 INTERPOSE_BY_TYPE procedure
2 If FILENAME$ is not the NULL string
3 If PARTITION-TYPE is 0x96
4 INTERPOSE[11](ISO-9660 File System package, FILENAME$)
3 Else
4 If PARTITION-TYPE is FAT,
5 INTERPOSE (FAT File System package, FILENAME$)
1 SELECT_ACTIVE_PARTITION (PARTITION) procedure
2 CHECK_FOR_BPB
3 If the buffer contains a BPB
4 Set OFFSET to 0
4 Set D.SIZE to the maximum size of the disk in bytes, as indicated by the
information in the BIOS Parameter Block
4 If FILENAME$ is not the NULL string
5 INTERPOSE (FAT File System package, FILENAME$)
4 Return OKAY
2 CHECK_FOR_FDISK
2 If the buffer contains an FDISK partition map
3 Search the FDisk partition map, reading new 512-byte sectors into the
buffer if necessary to “chain” to extended partition entries (i.e. ones
whose type byte at offset 4 contains “5”) for the first (i.e., at the lowest
offset) partition entry whose “bootable” field (at offset 0 in the partition
entry) contains 0x80.
3 If a “bootable” partition was found:
4 Set PARTITION-TYPE to that entry's “type” field (the byte at offset 4)
4 Set D.OFFSET to the byte offset from the beginning of the disk of the
beginning of the partition denoted by that entry.
4 Set D.SIZE to the size of the partition denoted by that entry.
4 INTERPOSE_BY_TYPE
4 Return OKAY
\ (If this point is reached, no partition was marked “bootable”)
3 Search the FDisk partition map beginning in 512-byte sector 0,reading new
512-byte sectors into the buffer if necessary to “chain” to extended
partition entries, for the first partition (i.e., at the lowest offset)
entry whose “type” byte is neither 0 nor 5 (5 is the type code that
indicates a “chained” extended partition entry).
3 If one is found:
4 Set PARTITION-TYPE to that entry's “type” field (the byte at offset 4)
4 Set D.OFFSET to the byte offset from the beginning of the disk of the
beginning of the partition denoted by that entry.
4 Set D.SIZE to the size of the partition in bytes denoted by that entry.
4 INTERPOSE_BY_TYPE
4 Return OKAY
3 Else \ (If this point is reached, the partition map did not contain any
valid partition entries)
4 Return ERROR
2 CHECK_FOR_ISO_9660
2 If it is an ISO 9660 disk
3 GET_DISK_SIZE
3 If FILENAME$ is not the NULL string
4 INTERPOSE (ISO-9660 File System package, FILENAME$)
3 Return OKAY
2 CHECK_FOR_MAC_DISK
2 If this is a Mac partitioned disk
3 Search the Mac partition table for the first “bootable” partition. A
partition is “bootable” when the pmPartStatus flags indicate that this is a
valid, allocated, readable and bootable partition and the pmProcessor field
contains “powerpc” (using case-insensitive matching).
3 If a Mac “bootable” partition is found
4 If FILENAME$ is “%BOOT”
5 If the Nth partition is marked bootable
6 Set D.OFFSET to the byte offset from the beginning of the disk
to the beginning of the boot area, as given by the pmLgBootStart
field.
6 Set D.SIZE to the size of the partition in bytes denoted by
pmBootSize.
6 Return OKAY
4 Else
5 If the FILENAME$ is the NULL string
6 Set D.OFFSET to the byte offset of the “real” partition data
6 Set D.SIZE to the size of the “real” partition data
5 Else
7 INTERPOSE_BY_TYPE
5 Return OKAY
3 Else
4 Return ERROR
3 (If this point is reached, no “bootable” partition was found)
3 Return ERROR
1 GET-DISK-SIZE procedure
2 Set OFFSET to 0
2 If the parent has a “#blocks” method
3 Execute the parent's “#blocks” and “block-size” methods
3 Set D.SIZE to the product of the numbers they returned
2 Else
3 Set D.SIZE to -1
1 SELECT_EXPLICIT_PARTITION procedure
2 CHECK_FOR_BPB
2 If the buffer contains a BPB
3 If PARTITION is 1
4 Set OFFSET to 0
4 Set D.SIZE to the maximum size of the disk in bytes, as indicated by the
information in the BIOS Parameter Block
4 If FILENAME$ is not the NULL string
5 INTERPOSE (FAT File System package, FILENAME$)
4 Return OKAY
3 Else \ Have a BPB, but PARTITION <> 1
4 Return ERROR
2 CHECK_FOR_FDISK
2 If an FDisk partition map is found
3 Search the FDisk partition map beginning in 512-byte sector 0, reading new
512-byte sectors into the buffer if necessary to “chain” to extended
partition entries, for the Nth, where N is the value of PARTITION, partition
entry whose “type” byte is neither 0 nor 5 (5 is the type code that
indicates a “chained” extended partition entry).
3 If the Nth partition is found:
4 Set PARTITION-TYPE to that entry's “type” field (the byte at offset 4)
4 Set D.OFFSET to the byte offset from the beginning of the disk to the
beginning of the partition denoted by that entry.
4 Set D.SIZE to the size of the partition in bytes denoted by that entry.
4 INTERPOSE_BY_TYPE
4 Return OKAY
3 Else \Nth partition does not exist
4 Return ERROR
2 CHECK_FOR_MAC_DISK
2 If this is a Mac partitioned disk
3 Search the Mac partition map for the Nth partition, where N is the value of
PARTITION.
3 If the Nth partition is valid, allocated, and readable
4 If FILENAME$ is %BOOT
5 If the Nth partition is marked bootable
6 Set D.OFFSET to the byte offset from the beginning of the disk
to the beginning of the boot area, as given by the pmLgBootStart
field.
6 Set D.SIZE to the size of the partition in bytes denoted by
pmBootSize.
6 Return OKAY
5 Else \Nth partition not “bootable”
6 Return ERROR
4 Else
5 If FILENAME$ is not the NULL string
6 INTERPOSE_BY_TYPE
5 Return OKAY
3 Else \ (If this point is reached, the partition is invalid)
4 Return ERROR
2 Else \ (If this point is reached, the partition map is not recognized)
3 Return ERROR]]></programlisting></para>
<para>This algorithm can be used to locate the correct partition and/or
file and/or load image from the specified device. The boot device is
selected as described in 7.4.3.2 of
<xref linkend="dbdoclet.50569387_45524" />. A filename can be explicitly
given as the arguments field of the
<emphasis>device-specifier</emphasis> (i.e., the field following the ':'
of the last path component). Other formats
<emphasis>may</emphasis> be recognized in an implementation-specific
manner.</para>
</section>
</section>
<section>
<title>tape-label Support Package</title>
<para>The
<emphasis role="bold"><literal>tape-label</literal></emphasis> Support Package shall
support tape as a standard byte device with the set
of methods specified in
<xref linkend="dbdoclet.50569387_45524" />, Section 3.7.3. Presence of
the bootinfo.txt file is optional.</para>
<para>The
<emphasis role="bold"><literal>open</literal></emphasis> method shall accept an argument string, where
brackets denote an optional component:</para>
<para>[file number]</para>
<para>where the first file on the tape media is located at file number
0.</para>
<section>
<title>Tape Format</title>
<para>The LoPAR tape format shall consist of files ending with a file
mark (FM). The first block of data will be identified as file 0. The
bootinfo.txt file, if present, shall be located on the tape as file 0
(the first file). There shall be only one bootinfo.txt file on the tape
media. Refer to
<xref linkend="dbdoclet.50569368_35854" /> for the LoPAR Tape
format.</para>
<figure pgwide="1">
<title>Tape Boot Format</title>
<mediaobject>
<imageobject role="html">
<imagedata fileref="figures/PAPR-62.gif" format="GIF"
scalefit="1" />
</imageobject>
<imageobject role="fo">
<imagedata contentdepth="100%" fileref="figures/PAPR-62.gif"
format="GIF" scalefit="1" width="100%" />
</imageobject>
</mediaobject>
</figure>
</section>
<section xml:id="dbdoclet.50569368_35854">
<title>Tape bootinfo.txt File</title>
<para>The bootinfo.txt file shall have included for each set
of <emphasis role="bold"><literal>&lt;chrp-boot&gt;</literal></emphasis> tags a set of <emphasis role="bold"><literal>&lt;boot-script&gt;</literal></emphasis> tags that contains
a pointer to the program image to be loaded (Refer to
<xref linkend="dbdoclet.50569368_26165" />). The form for this tape
pointer will be:</para>
<para>device specifier = <emphasis>device</emphasis>:<emphasis>file number</emphasis></para>
<para>EXAMPLE: device specifier = tape:2 (For the specified set of
<emphasis role="bold"><literal>&lt;chrp-boot&gt;</literal></emphasis> tags, load the tape program image from file 2).</para>
<para>A bootinfo.txt file may contain a multiple set of <emphasis role="bold"><literal>&lt;chrp-boot&gt;</literal></emphasis>
tags where each one can point to a different tape file number. If a
bootinfo.txt file is not present, file 0 should be a bootable file. Only
file 0 will be loaded as a bootable image. No other files will be
searched if a bootinfo.txt file is not present unless the file number to
load is specified by an argument.</para>
</section>
</section>
<section>
<title>network Support Package</title>
<para>The
<emphasis role="bold"><literal>network</literal></emphasis> Support Package shall adhere to the
<xref linkend="dbdoclet.50569387_33177" /> documentation functions and
conventions.</para>
</section>
<section>
<title>Program-image formats.</title>
<para>OF must recognize a client program that is formatted as ELF, as
defined in
<xref linkend="dbdoclet.50569387_38836" />, and PE, as defined in
<xref linkend="dbdoclet.50569387_18190" />. Other formats
<emphasis>may</emphasis> be handled in an implementation-specific manner.
<xref linkend="dbdoclet.50569387_33384" /> defines the FCode and Forth
Program-Image Formats.</para>
<para>After locating the file, OF reads the image into memory at the
location specified by the load-base Configuration Variable. Then, OF must
perform the following procedure to prepare the image for
execution.</para>
<programlisting><![CDATA[init-program.
set restart? false
if the image is in ELF format
if the EI_DATA field does not match little-endian?
set little-endian? appropriately.
set restart? true
locate the PowerPC Note Section
if the Note Section’s values do not match
set Configuration Variables appropriately
set restart? true
if restart?
restart the system, possibly by executing reset-all
else
move and/or relocate the ELF image
set GO’s context with initial register values
else if the image is in PE format
if little-endian? is false
set little-endian? to true.
restart the system, possibly by executing reset-all
else
move and/or relocate the PE image.
set GO’s context with initial register values
else if the image is FCode Image (hex characters F1,08)
setup system and do subsequent go and perform a byte load of the FCode image
else if the image is Forth Code Source Image (ASCII characters \”<space>”)
setup system to evaluate Forth Source Image
else if the image is a bootinfo.txt file (i.e., begins with “<CHRP-BOOT>”)
setup system to parse the bootinfo.txt file
else
FAIL, in an implementation-specific manner.]]></programlisting>
<para><emphasis role="bold">Notes:</emphasis> The following comments apply to the above code:</para>
<orderedlist>
<listitem>
<para>For more information on detecting an ELF format, refer to
<xref linkend="dbdoclet.50569368_24653" />.</para>
</listitem>
<listitem>
<para>For more information on relocating an ELF image, refer to
<xref linkend="dbdoclet.50569368_30006" />.</para>
</listitem>
</orderedlist>
</section>
</section>
</appendix>
Reference in New Issue View Git Blame Copy Permalink