Device Tree documentation discussion for Cell/B.E. binding DRAFT

Christian Rund Christian.Rund at de.ibm.com
Fri Dec 5 20:08:30 EST 2008


Dear Subscribers and Readers,

below please find the plain text version of a draft of the Cell/B.E. 
device 
tree documentation.
Goal of these reviews should be to finally establish the document as 
Power.org 
PAPR Binding for the Cell/B.E. processor.

A version based on the Power.org template also exists, but let me propose 
to 
base the discussion on the plain text version.

Please review and give us feedback.

Thanks.
_________________________________

DRAFT Power.org Standard for the Cell Broadband Engine architecture device
tree

Draft Version 0.2 - 26 November 2008

© Copyright 2008 Power.org. All rights reserved.



Implementation of certain elements of this  document  may  require 
licenses
under  third-party   intellectual   property   rights,   including without
limitation, patent rights.  Power.org and its Members  are  not,  and 
shall
not be held, responsible  in  any  manner  for  identifying  or  failing 
to
identify any or all such third-party intellectual property rights.

THIS POWER.ORG SPECIFICATION IS PROVIDED "AS IS" AND  WITHOUT  ANY 
WARRANTY
OF ANY  KIND,  INCLUDING,  WITHOUT  LIMITATION,  ANY  EXPRESSED  OR 
IMPLIED
WARRANTY OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS  FOR  A 
PARTICULAR
PURPOSE.

IN NO EVENT SHALL POWER.ORG OR ANY MEMBER OF POWER.ORG  BE  LIABLE  FOR 
ANY
DIRECT, INDIRECT, SPECIAL, EXEMPLARY,  PUNITIVE  OR  CONSEQUENTIAL 
DAMAGES,
INCLUDING,  WITHOUT  LIMITATION,  LOST  PROFITS,  EVEN  IF  ADVISED  OF 
THE
POSSIBILITY OF SUCH DAMAGES.

Questions pertaining to this document, or the terms  or  conditions  of 
its
provision, should be addressed to:


IEEE-ISTO
445 Hoes Lane
Piscataway, NJ 08854
ATTN: Power.org Board Secretary

Introduction

Power.org's mission is to develop, enable and promote Power Architecture®
technology as the preferred open standard hardware development platform 
for
the electronics industry and to administer qualification programs that
optimize interoperability and accelerate innovation for a positive user
experience.  Power.org seeks to solicit the participation of all 
interested
parties on a fair, equitable and open basis.

Power.org's output includes:
           . Open standards and specifications
           . Business guidelines documents
           . Best practices and education
           . Certifications to validate implementations and drive adoption

Power.org's specifications enable:
           . Interoperability between community members
           . Sustainability built on driving open standards and 
convergence

Revision History



|Version |Date       |Editor        |Description |
|0.1     |20 Nov 2008|C. Rund       |Initial draft |
|0.2     |26 Nov 2008|C. Rund       |Ready for first internal review |
|        |           |              | |


Table of Contents



1     Overview   5

  1.1  Scope      5

  1.2  Purpose    5

2     Terminology      5

  2.1  Definitions     5

  2.2  Abbreviations   5

  2.3  Acronyms   5

3     Introduction     6

4     The Cell Broadband Engine  architecture  processor  representation 
in
   the device tree     7

  4.1  "be" node  7

   4.1.1    ioc node   10

   4.1.2    "bic0" node     11

   4.1.3    "bic1" node     11

   4.1.4    "mic-tm" node   12

   4.1.5    "pervasive" node      12

   4.1.6    "ppe-mmio" node 14

   4.1.7    "interrupt-controller" node 15

   4.1.8    "spe" nodes     16


DRAFT Power.org Standard for the Cell Broadband Engine architecture device
tree

   Overview


1 Scope


       This document is intended to apply the Power.org Standard for Power
       Architecture Platform Requirements (Workstation, Server) PAPR on
       Cell Broadband Engine architecture compliant processors. This
       encompasses requirements therein and additional requirements for
       device tree nodes and properties pertaining to Cell Broadband 
Engine
       architecture compliant processors.

2 Purpose


       This document is intended to indicate the architectural option and
       feature set of Cell Broadband Engine architecture processors to
       software via Open Firmware (OF).

   Terminology


        This document uses definitions, abbreviations and acronyms as
        indicated below or in the PAPR specification [3].

1 Definitions


       Device Tree: Open Firmware data structure representing the set of
                   devices attached to a system. See [1] for details.

2 Abbreviations


        Define key abbreviations here (use "paragraph" plus tab), such as

        l.t.s.f.l.r.   Leaving this section for later revisions of this
        document - to be removed if not used !!!!!!!!!!!!

3 Acronyms


        Define key acronyms here (use "paragraph" style with tabs"), such 
as

        EIB       Element Interconnect Bus

        IIC       Internal Interrupt Controller

        IOC       Input Output Controller

        MMIO      Memory Mapped Input Output

        OF        Open Firmware (see [1]).

        PPE       PowerPC Processing Element

        SPE       Synergistic Processing Element



   Introduction


The specific goals of this specification are as follows:

           . To provide the address map for the components in a Cell
             Broadband Engine Architecture processor. Subcomponent address
             information is detected by the OF and passed to the OS in the
             device tree.


           . To build upon the OF boot environment defined in IEEE 1275,
             IEEE Standard for Boot (Initialization Configuration) 
Firmware:
             Core Requirements and Practices.


           . To provide device tree nodes and property values necessary 
for
             access to and configuration of the Cell Broadband Engine
             Architecture processor subcomponents.

The Cell Broadband Engine architecture processors are implemented as
systems on a chip. Besides a PowerPC processor it contains eight
Synergistic Processing Elements (SPEs) in addition. Each SPE has access to
256kB of associated local store. All logic of the non-processor part is
accessed via MMIO. Mapping and structure of the MMIO space are described
with the "be" node. A  nodes' unit address is the MMIO address of that
particular BE. The "be" node is located in the device tree as child of the
root node '/'.

   The Cell Broadband Engine architecture processor representation in the
   device tree


The following contents are outlined according to the hierarchy of the
components in the sub-tree containing the components of the Cell Broadband
Engine processor.

All device tree nodes detailed below contain a "name" property in addition
to the mentioned properties as follows

           . Specifies the name of the node


           . Encoded as with encode-string


           . Default is the name of the node


             Throughout the description below the notation
             phandle(<expression>) is used to retrieve the phandle of a
             node. A phandle of a device tree node is the cell-sized datum
             identifying the particular device tree node.

1 "be" node


The "be" node contains a set of properties and sub-nodes, which describe
the structure of a Cell Broadband Engine Architecture processor. All the
devices are contained, except the Power PC processor core nodes, which are
located under the "/cpus" path according to the PowerPC Processor binding
to the IEEE 1275 standard.

"reg" property

             Standard property name specifying the < address, size > pair 
of
             the Cell Broadband Engine processor's MMIO mapped registers.


             Prop-encoded array: Encoded as with encode-phys for the
             address. The size part is encoded with two encode-ints.


             The array consists of four 32-bit values. Value one and two 
in
             this array correspond to the 64-bit address value the the 
Cell
             Broadband Engine Architecture processor is mapped into. Value
             three and four correspond to the 64-bit size. Both pairs
             represent the < address, size > pair of MMIO mapped registers
             in the Cell Broadband Engine processor's MMIO mapped register
             space.


             Default value is { 0x00000iii 0x00000000 0x00000000 
0x000800000
             }, where iii is the offset defined by the hardware settings.

"ranges" property

             Standard property name which specifies the mapping of the 
child
             of the "be" node within the  "be" nodes' parent address space
             using the < child, parent, size > triple.


             Prop-encoded array: Encoded as with encode-int for the childs
             range, encode-phys for the parents range and encode-int for 
the
             size.


             The array consists of four 32-bit values. Value one in this
             array corresponds to the 32-bit child address encoded as with
             encode-int. Value two and three correspond to the 64-bit 
parent
             address encoded as with encode-phys. Value three in this 
array
             corresponds to the 32-bit size.


             Default value is { 0x00000000 0x00000iii 0x00000000 
0x00080000
             }, mapping address 0 of child to 0x00000iii 00000000.

"device-type" property


             Standard property name which specifies the type of the node.


             Encoded as with encode-string.


             Default value is { "be" }.



"model" property


             property name: Specifies model of node.


             Encoded as with encode-string.


             Default value is { "IBM,CBEA" }.



"ibm,dt-version" property

property name: Specifies the current device tree version number. The
version number format is major.minor.

Whenever the device tree is changed or extended in a way that OS changes
are required the major version is changed.

The minor version is changed when at least one new property is added or
removed.

Encoded as with encode-string

The default value is { 1.1 }



"#address-cells" property


property name which specifies the number of address cells for child nodes
   to the current node.


             Encoded as with encode-int.


             Default value is { 1 }



"#size-cells" property

Standard property name which specifies the number of size cells for child
nodes to the current node.

 Encoded as with encode-int.

Default value is { 1 }



"ibm,associativity" property

property name: Property to define the associativity domains for this
resource.
See Power Architecture Platform Requirements (PAPR) [3], Sections
14.11.2.2, 15.2, 15.3, 18.3 and C.6.2.2 for details on this property.

Set values to { 4 0x00000000, 0x00000000, 0x0000000i, 0x0000000i }; i = 0
for associativity to Cell Broadband Engine processor 0, i = 1 for
associativity to Cell Broadband Engine processor 1.



"interrupt-parent" property

property name: Property that specifies the interrupt handler responsible
for this node.

The value represents a phandle of the interrupt handler node, encoded as
with encode-int.

Default value is { phandle( my-self/interrupt-controller) }



"cpus" property

property name: Porperty to specify the PPE component of the Cell Broadband
Engine architecture processor chip.

phandle of the cpu node, encoded as with encode-int.

Default value is { phandle(/cpus/PowerPC,BE at i) }; i = 0 for Cell Broadband
Engine Architecture processor 0, i = 1 for Cell Broadband Engine
Architecture processor 1.

1 ioc node


The Input/Output Controller (IOC) node contains among others the 
properties
specifying the address range of MMIO register space controlling the IOC.

"reg" property

Default property name: Property to specify the MMIO offset of the IOC,
which are two sets of registers each represented by an < offset, size >
pair.

prop-encoded-array: Encoded as with encode-phys for the offset values,
encode-int for the size values.

The array consists of four 32-bit values to represent two < offset, size >
pairs. Value one in this array corresponds to the first offset value 
within
the child address space, encoded as with encode-phys. Value two 
corresponds
to the size, encoded as with encode-int. Value three in this array
corresponds to the second offset value, value four to the second size.

Default value is { 0x00510000 0x00001000 0x00511000 0x00001000 }.



"device_type" property

Standard property name: Specify the type of this node

Encoded as with encode-string

Default value is { "ioc" }



"interrupts" property

Standard property name: Property which specifies the interrupt number of
the interrupt issued by the IOC for IIC "IO Exceptions"

Encoded as with encode-int.

The property value consists of four bytes each representing a specific
value for a node, an Internal Interrupt Controller Interrupt Service
Routine bit mask, a class and a unit

 0xNN3d010e (NN=node, bit 3d (61) in IIC_ISR, class=1, unit=E for IIC_ISR
interrupt)

Default value is { 0i3d010e }, i = 0 for Cell Broadband Engine processor 
0,
i = 1 for Cell Broadband Engine processor 1.



2 "bic0" node


The Bus Interface Controller (BIC) 0 node describes the address range of
MMIO register space controlling the BIC0.

"reg" property

Default property name: Property to specify the MMIO offset of the BIC0,
which is one set of registers representing an < offset, size > pair.

prop-encoded-array: Encoded as with encode-phys for the offset value,
encode-int for the size.

Default value is { 0x00512000 0x00001000 }



"device_type" property

Standard property name: Property to specify the type of this node.

Encoded as with encode-string.

Default value is { "bic0" }.



3 "bic1" node


The Bus Interface Controller (BIC) 1 node describes the address range of
MMIO register space controlling the BIC1.

"reg" property

Default property name: Property to specify the MMIO offset of the BIC1,
which is one set of registers representing an < offset, size > pair.

prop-encoded-array: Encoded as with encode-phys for the offset value,
encode-int for the size.

 Default value is { 0x00513000 0x00001000 }



"device_type" property

Standard property name: Property to pecify the type of this node.

Encoded as with encode-string.

Default value is { "bic1" }.



4 "mic-tm" node


The "mic-tm" node represents the Memory Interface Controller (MIC) in the
device tree. The main property value is the address range of MMIO register
space controlling the MIC.

"reg" property

Default property name: Property to specify the MMIO offset of the BIC1,
which is one set of registers representing an < offset, size > pair.

prop-encoded-array: Encoded as with encode-phys for the offset value,
encode-int for the size.

Default value is { 0x0050a000 0x00001000 }.



"device_type" property

Standard property name: Specify the type of this node.

Encoded as with encode-string.

Default value is { "mic-tm" }.



5 "pervasive" node


The pervasive node node represents the  pervasive unit in the device tree.
T>he main property value is the address range of MMIO register space
controlling the pervasive unit.

"reg" property

Default property name: Property to specify the MMIO offset of the BIC1,
which is one set of registers representing an < offset, size > pair.

prop-encoded-array: Encoded as with encode-phys for the offset value,
encode-int for the size.

Default value is { 0x00509000 0x00001000 }.



"device_type" property

Standard property name: Property to specify the type of this node.

Encoded as with encode-string.

Default value is { "pervasive" }.



"ppe-throttle-temp" property

property name: Property to specify the minimum temperature the PPE is
throttled.

Temperature in °C, encoded as with encode-int.

Default value is { 0x65 } for 101°C



"ppe-end-throttle-temp" property

Standard property name: Property to specify the temperature below the PPE
throttling is exited.

Temperature in °C, encoded as with encode-int.

Default value is { 0x5b } for 91°C



"ppe-full-throttle-temp" property

property name:  Property to specify the minimum temperature the PPE is
stopped.

Temperature in °C, encoded as with encode-int.

Default value is { 0x7f } for 127°C



"spe-throttle-temp" property

property name: :  Property to specify the minimum temperature the SPEs are
throttled.

Temperature in °C, encoded as with encode-int.

Default value is { 0x65 } for 101°C



"spe-end-throttle-temp" property

property name: :  Property to specify the temperature below the SPEs
throttling is exited.

Temperature in °C, encoded as with encode-int.

Default value is { 0x5b } for 91°C



"spe-full-throttle-temp" property

property name: Property to specify the minimum temperature the PPE is
stopped.

Temperature in °C, encoded as with encode-int.

Default value is { 0x6f } for 111°C



6 "ppe-mmio" node


The "ppe-mmio" node represents the PowerPC Processing Element (PPE) in the
device tree. The main property is the address range of MMIO register space
controlling the PPE part of the Cell Broadband Engine processor.



"reg" property

Standard property name: Property to specify the MMIO offset of the mic.

prop-encoded-array: Encoded as with encode-phys for the offset, encode-int
for the size.

Default value is { 0x00500000 0x00001000 }



"device_type" property

Standard property name: Property to specify the type of this node.

Encoded as with encode-string.

Default value is { "ppe-mmio" }.



7 "interrupt-controller" node


The Cell Broadband Engine Architecture processor contains an Internal
Interrupt Controller (IIC), which is handling all the interrupts from the
PPE, the SPE and the connected IO.

"reg" property

Standard property name: Property to specify the MMIO offset of the IIC, 
one
range for each of the two threads contained in each PPE and one range for
the common MMIO.

prop-encoded-array: Consisting of six 32-bit values. The values form three
< offset,length > pairs of the denoted space encoded as with encode-phys
for the offsets and encode-int for the sizes

   1. for MMIO space of thread one

   2. for MMIO space of thread two

   3. for MMIO space of the common PPE MMIO space.

Default value is
{ 0x00508400 0x00000020 0x00508420 0x00000020 0x00508000 0x00001000 }.



"device_type" property

Standard property name: Property to specify the type of this node.

Encoded as with encode-string.

Default value is { "CBEA-Internal-Interrupt-Controller" }.



"compatible" property

property name: Property to specify the compatiblity of this interrupt
controller.

Encoded as with encode-string.

Default values is { "IBM,CBEA-Internal-Interrupt-Controller" }.



"interrupt-controller" property

property name: Property to specify that this node is an interrupt
controller.

The mere presence of this property denotes the current node being an
interrupt controller.

Zero length property.

The value is {}.



"#interrupt-cells" property

Standard property name: Property to specify the number of interrupt cells.

Encoded as with encode-int.

Default value is { 0x1 }.



"ibm,interrupt-server-ranges" property

property name: Property to specify the threads handled by this interrupt
controller.

Array of threads, encoded as with encode-int.

Default values for



|Cell Broadband Engine    |Property Value           |
|Architecture processor # |                         |
|0                        |{ 0x00000000 0x00000001 }|
|1                        |{ 0x00000000 0x00000001 }|


8 "spe" nodes


The Cell Broadband Engine Architecture processor contains eight SPEs, each
consisting of an SPU, 256kB local store and a Memory Flow Controller 
(MFC).
The SPEs are connected to the EIB (Element Interconnect Bus) ring. The
access to the internal devices is done via MMIO reads, with a fixed offset
to the Cell Broadband Engine processor base address.



"reg" property

Standard property name: Specifies the MMIO offset and size of the SPEs
Local Storage, Problem-State, Privilege 2 Area and Privilege 1 Area.

prop-encoded array: Encoded as four < offset, length > pairs per SPE
encoded as with encode-phys for the offsets, encode-int for the size. The
pairs define the following SPE units:

   1. Local Store (LS)

   2. Problem State MMIO Registers

   3. Privilege State 2 MMIO Registers

   4. Privilege State 1 MMIO Registers

The property exists once in each spe node.

Default values for SPE



|#           |Property Value                            |
|spe at 0       |{ 0x00000000 0x00040000 0x00040000        |
|            |0x00020000                                |
|            |0x00060000 0x00020000 0x00400000          |
|            |0x00002000 }                              |
|spe at 80000   |{ 0x00080000 0x00040000 0x000c0000        |
|            |0x00020000                                |
|            |0x000e0000 0x00020000 0x00402000          |
|            |0x00002000 }                              |
|spe at 100000  |{ 0x00100000 0x00040000 0x00140000        |
|            |0x00020000                                |
|            |0x00160000 0x00020000 0x00404000          |
|            |0x00002000 }                              |
|spe at 180000  |{ 0x00180000 0x00040000 0x001c0000        |
|            |0x00020000                                |
|            |0x001e0000 0x00020000 0x00406000          |
|            |0x00002000 }                              |
|spe at 200000  |{ 0x00200000 0x00040000 0x00240000        |
|            |0x00020000                                |
|            |0x00260000 0x00020000 0x00408000          |
|            |0x00002000 }                              |
|spe at 280000  |{ 0x00280000 0x00040000 0x002c0000        |
|            |0x00020000                                |
|            |0x002e0000 0x00020000 0x0040a000          |
|            |0x00002000 }                              |
|spe at 300000  |{ 0x00280000 0x00040000 0x002c0000        |
|            |0x00020000                                |
|            |0x002e0000 0x00020000 0x0040a000          |
|            |0x00002000 }                              |
|spe at 380000  |{ 0x00380000 0x00040000 0x003c0000        |
|            |0x00020000                                |
|            |0x003e0000 0x00020000 0x0040e000          |
|            |0x00002000 }                              |


"device_type" property

Standard property name: Specifies the type of this node.

Encoded as with encode-string.

Default value is  {"spe" }.



"interrupts" property

Standard property name: Property to specify the interrupt numbers of the
interrupts issued by SPE.

prop-encoded array: List of interrupt numbers issued by the SPE. Each 
value
in the list is encoded as with encode-int.

The property exists once in each spe node.

Default values for SPEs are



|#          |Property Value                                |
|spe at 0      |{ 0x4, 0x104, 0x204 }                         |
|spe at 80000  |{ 0x7, 0x107, 0x207 }                         |
|spe at 100000 |{ 0x3, 0x103, 0x203 }                         |
|spe at 180000 |{ 0x8, 0x108, 0x208 }                         |
|spe at 200000 |{ 0x2, 0x102, 0x202 }                         |
|spe at 280000 |{ 0x9, 0x109, 0x209 }                         |
|spe at 300000 |{0x1, 0x101, 0x201 }                          |
|spe at 380000 |{0xa, 0x10a, 0x20a }                          |


"vicinity" property

property name: Specifies the direct neighbouring componentes on the EIB
ring related to each SPE.

prop-encoded array: Pairs of phandles ( < phandle, phandle >) of the
neighbouring nodes, each phandle is encoded as with encode-int.

The property exists once in each spe node.

Default values for SPEs



|#          |Property Value                                |
|spe at 0      |{ phandle(mic-tm, SPE 3) }                    |
|spe at 80000  |{ phandle(mic-tm, SPE 2) }                    |
|spe at 100000 |{ phandle(SPE 0, SPE 4) }                     |
|spe at 180000 |{ phandle(SPE 1, SPE 5) }                     |
|spe at 200000 |{ phandle(SPE 2, SPE 6) }                     |
|spe at 280000 |{ phandle(SPE 3, SPE 7) }                     |
|spe at 300000 |{ phandle(SPE 4, BIC0) }                      |
|spe at 380000 |{ phandle(SPE 5, BIC0) }                      |


"physical-id" property

property name: Property to specify the physical id of an SPE.

Default values for the physical id is encoded as with encode-int.

The property exists once in each spe node.



|#          |Property Value                                |
|spe at 0      |{ 0 }                                         |
|spe at 80000  |{ 1 }                                         |
|spe at 100000 |{ 2 }                                         |
|spe at 180000 |{ 3 }                                         |
|spe at 200000 |{ 4 }                                         |
|spe at 280000 |{ 5 }                                         |
|spe at 300000 |{ 6 }                                         |
|spe at 380000 |{ 7 }                                         |
 Appendix A - Bibliography

This section lists documents which were referenced in this specification 
or
which provide  additional  information,  and  some  useful  information 
for
obtaining these documents. Referenced documents are listed below.  When 
any
of the following standards are  superseded  by  an  approved  revision, 
the
revision shall apply.

   1. IEEE 1275, IEEE Standard for Boot (Initialization Configuration)
      Firmware: Core Requirements and Practices

      IEEE part number DS02683, ISBN 1-55937-426-8

   2. PowerPC Processor binding  to:  IEEE  1275,  IEEE  Standard  for 
Boot
      (Initialization  Configuration)  Firmware:   Core   Requirements and
      Practices

   3.  Power.org  Standard  for  Power  Architecture  Platform 
Requirements
      (Workstation, Server) Version 2.2, 9th Oct 2007

Christian Rund
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.ozlabs.org/pipermail/devicetree-discuss/attachments/20081205/fdd03822/attachment.htm>


More information about the devicetree-discuss mailing list