QorIQ Configuration Suite Device Tree Editor - Freescale ...

Freescale Semiconductor 

Processor Expert Software 

QorIQ Configuration Suite 

Device Tree Editor 

This document introduces the Hardware Device Tree 

component of QorIQ Configuration Suite. The document 

describes how to create a new QorIQ configuration project 

and use the Hardware Device Tree component. 

1 Introduction 

A device tree is a tree data structure with nodes and 

properties that describes the physical devices in a system, 

that is Direct Memory Access, Universal Serial Bus 

Interface, Frame Manager, or Security Monitor. The ePAPR 

standard describes the logical structure of the device tree and 

specifies a base set of required nodes and properties. This set 

is minimal, but complete enough to boot a simple operating 

system. 

• DTS (Device Tree Syntax) is the textual 

representation of a device tree consumed by a DTC. 

• DTC (Device Tree Compiler) is an open source tool 

used to create DTB files from DTS files. 

• DTB (Device Tree Blob) is a compact binary 

representation of the device tree consumed by the 

Uboot and operating system. 

You can find the details of device trees in: 

© Freescale Semiconductor, Inc., 2012. All rights reserved. 

Document Number: QORIQCSHWDEVTREEUG 

Rev. 5, 06/2012 

Contents 

1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 

2. Using Hardware Device Tree Editor . . . . . . . . . . . . . . 2 

2.1.Create New Project . . . . . . . . . . . . . . . . . . . . . . . . . 2 

2.2.Modify Hardware Device Trees . . . . . . . . . . . . . . . . 6 

2.3.Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 

2.4.Search in Device Trees . . . . . . . . . . . . . . . . . . . . . . 22 

2.5.Generate Device Tree Blob . . . . . . . . . . . . . . . . . . 24 

2.6.Known Issues/Limitations . . . . . . . . . . . . . . . . . . . 25

Using Hardware Device Tree Editor 

• Power.org Standard for Embedded Power Architecture Platform Requirements (ePAPR), 

version 1.0 

• Booting the Linux/ppc kernel without Open Firmware 

— 2005 Benjamin Herrenschmidt , IBM Corp. 

— 2005 Becky Bruce , Freescale Semiconductor, FSL SOC and 

32-bit additions. 

— 2006 MontaVista Software, Inc., Flash chip node definition. 

Device trees represent one of the most difficult configuration elements on QorIQ family because of the 

complexity of the processors and its format. Presently, the modification of device trees is done through any 

text editors. From here emerges the need to have a device tree dedicated tool in the form of a GUI editor 

that represents its tree like structure graphically and facilitates its handling. 

2 Using Hardware Device Tree Editor 

The Hardware Device Tree Editor is a graphical tool designed to edit the standard ePAPR device trees and 

to offer assistance. The dts format is complex enough encompassing all the SoC resources, as such, noninitiated 

users find difficult to read or modify it. The Hardware Device Tree Editor offers support for both 

interpreting and writing hardware device trees. 

This section describes: 

• Section 2.1, “Create New Project’’ 

• Section 2.2, “Modify Hardware Device Trees’’ 

• Section 2.3, “Validation’’ 

• Section 2.4, “Search in Device Trees’’ 

• Section 2.5, “Generate Device Tree Blob’’ 

• Section 2.6, “Known Issues/Limitations’’ 

2.1 Create New Project 

The device tree project is created using the New QorIQ Configuration Project wizard. You can import 

an existing device tree file or generate a default one. 

To create a new QorIQ project for device tree configuration, follow these steps: 

1. Select File > New > QorIQ Configuration Project. Follow the steps in the New QorIQ 

Configuration Project Wizard. 

2. Enter project name. 

3. Select the required target SoC. 

4. In the Toolset Selection screen (Figure 1), select Device Tree Editor. 

QorIQ Configuration Suite Device Tree Editor, Rev. 5 

2 Freescale Semiconductor

Figure 1. Select Device Tree Editor 



5. Click Next. The Device Tree Configuration screen appears where you can select from three 

actions: 

— Import configuration from an existing device tree file 

A minimal validation is performed for the imported file. The agreeable files have ".dts" 

extension and are compatible with the selected SoC. A compatible file is a dts file which 

specifies the "model" property containing the selected SoC. Figure 3 shows an example where 

imported device tree file and chosen SoC do not meet. 

— Use default device tree configuration which is the default option 

— Empty configuration 

Freescale Semiconductor 3


Figure 2. Device Tree Configuration Screen 

Figure 3. Import Configuration from Device Tree File 

— The default device trees are dts files from existing BSPs as follows: 



Table 2-1. List of SoC Supported for Device Tree 

P1 

P2 

P3 

P4 

P5 

Supported SOC BSP 

P1010 QorIQ-SDK-v1.2-20120614 

P1011 SDK_20110506 







P2010 SDK_20110506 





P4080_v1_0 QorIQ-SDK-v1.2-20120614 

P4080_v2_0 QorIQ-SDK-v1.2-20120614 





6. If no default device tree exists for the selected SoC, the associated option becomes disabled. 

7. Click Finish. 

The project is created, and the HWDeviceTree component is added to the project under Embedded 

Components folder (Figure 4), and the data from the device tree file is loaded into the component. 



Figure 4. Device Tree Project 

This operation may take time depending on the size of the file. A dialog box appears (Figure 5) on the 

screen indicating the progress of the procedure. 

Figure 5. Device Tree Progress Monitor 

The original file used to create the HWDeviceTree component is added to the Imported_Files folder. A 

new device tree file is generated under the Sources folder based on the imported file. At this moment, the 

two files are identical. You will work with the generated one and the former will remain untouched. There 

can be more than one HWDeviceTree component per project. 

Follow the tips while working on the device tree: 

• Enable Project > Build Automatically setting to always have everything in sync. 

• Save your session before leaving the application in case you still need it. When you close the 

Processor Expert, a pop-up dialog appears allowing you to save the changes. 

• When HWDeviceTree component is removed from the project, the generated device tree file is 

also removed. 

2.2 Modify Hardware Device Trees 

You can perform modifications in the Hardware Device Tree component through the GUI editor or text 

editor or both. 



2.2.1 GUI Editor 



When the HWDeviceTree component is selected in the Project Panel, the Component Inspector opens 

displaying the GUI editor and the device tree properties. This view is split in two parts, a tree structure that 

handles the nodes and the Device Tree Properties view that handles the properties. 

Figure 6. Device Tree GUI Editor — DeviceTree and Device Tree Properties Views 

The device tree nodes are represented in a tree structure. Each node selection makes the corresponding 

properties display in the Device Tree Properties view. The Device Tree Properties view displays a list 

of properties along with the short details of the node. You can activate the dynamic context help by 

pressing F1 key after selecting the required node for which you want to view the dynamic context help. 



Figure 7. Device Tree Properties Custom View 

The Properties table contains three columns: Name, Value, and Type. All values in the Value column are 

discarded of any type-specific symbols. For example, cell list appears as 0x1 0x2, that is 

without the angular brackets. A string list appears without the quotation marks. This is applicable in the 

graphical editor only, the text editor displays all values in the complete form. The supported types are 

shown in Table 2-2. 

Table 2-2. Supported Properties Types 

Type Example 

BYTELIST [AB CD 01] 

CELLLIST 

EMPTY empty value 

PHANDLE &mpic 

STRINGLIST "fsl,p5020", "fsl,p4080" 

U32 

STRING memory 

EMPTY no value 

You can perform the following actions in the GUI editor using the View toolbar (Figure 8). 

Figure 8. View Toolbar 





• Import a new device tree file. 

• Include a device tree file. 

• Perform manual validation against device tree. 

• Tree navigation using Go back and Go forward icons from the View toolbar. 

• Expand/collapse nodes from the toolbar or using the context menu. 

• Sort the nodes in ascending/descending order. 

You can perform the following actions from the context menu. Right-click in the tree structure to open the 

context menu. 

Figure 9. Context Menu 

• Create a new node using the Insert node option. The Insert node dialog box appears. Enter a name 

for the node and click OK. 

Figure 10. Insert Node Dialog Box 

• Delete a node using the Delete node option. The Confirmation dialog box appears, which not only 

deletes the node but also allows you to delete all the node's references that exist in the device tree. 

Figure 11. Confirmation Dialog Box 

• Rename a node using the Rename node option. 

• Open the Device Tree Settings page. 



You can insert a property by pressing New… button in the Device Tree Properties view. The Insert 

Property dialog box appears. Select a name, type and the required value in the respective fields. 

Figure 12. Insert Property Dialog Box 

You can remove a property by selecting it in the Device Tree Properties view and then clicking Remove. 

A confirmation dialog box will appear. 

Some keyboard shortcuts that you can use in the device tree GUI editor are listed in Table 2-3. 

Table 2-3. Keyboard Shortcuts Used in Device Tree GUI Editor 

Action/View Tree Structure View Device Tree Properties View 

Insert node F3 

Delete node DELETE 

Rename node F2 

Insert property 

Remove property DELETE 

Edit property 

Search node/property CTRL+ALT+H CTRL+ALT+H 

• Context help support for device tree nodes: 

Select the required node in the tree structure and open the Eclipse context help by pressing F1 on 

Windows and Ctrl+F1 on Linux host. The nodes that have no documentation available are marked 

in the Device Tree Properties view. 

Figure 13. Node with No Documentation Available 





You can edit existing documentation or add missing documentation by performing the following steps: 

1. Edit existing file or create a new html file at the location eclipse/plugins/ 

com.freescale.processorexpert.doc.qoriq.dt/html keeping the same format; the name of the file 

must be identical with the name of the node, that is .html. 

2. If you are creating a new html file, add a new entry in eclipse/plugins/ 

com.freescale.processorexpert.doc.qoriq.dt/contexts.xml for the new file. 

3. Close the Eclipse IDE. 

4. Open Command Prompt and launch Eclipse using the following command: 

>eclipse.exe --clean 

2.2.1.1 Editing Device Tree Properties 

The Properties table in the GUI editor stores a node’s properties.The Name column in the Properties 

table provides a cell editor which lets you change the name of a property directly in the table cell. 

Figure 14. Content Assistance for Device Tree Properties 

When a cell becomes empty, a content proposals list appears. This list contains all existing properties 

encountered during the process of importing a device tree file. Filtering in the cell editor is also enabled. 

In addition, you can enter the name of a new property. After pressing the Enter key, the name is added to 

the proposals list in the current session. 

The cell editor associated with the Value column allows you to set the value of the property. Click the "…" 

button (Figure 15) to open the Property dialog box (Figure 16), which contains information about each 

cell item. 

Figure 15. Setting Value in Properties Table 



The items are characterized by their name and type. Again, the type symbols are discarded in the Value 

column. The value can be converted to a new radix by selecting a new type from the available combo box 

(in the Type column) within a cell, as shown in Figure 16. 

Figure 16. Property Dialog Box 

You can insert a new item on an empty row. The following types are supported. 

Each action modifies the content of the HWDeviceTree component. Because of that each action is 

followed by a build operation that updates the dts file under the Sources folder. 

2.2.1.2 Include Tree 

Table 2-4. Supported Property Types 

Name Example 

BYTESTRING [AA BB CC] 

CELLLIST* 

DECIMAL 175 

HEX AF 

LABEL label: 

REFERENCE &cpu0 

STRING fsl,p4080 

The Include Tree tab in the Component Inspector represents the hierarchy of the included device tree 

files. The Include Tree tab allows easy navigation among all device tree fragments: dts or dtsi. 



Figure 17. Include Tree Tab in Component Inspector 



The Include Tree tab displays three types of files: 

• merged device tree file, which represents the all-in-one file merging all nodes and properties from 

multiple device trees in a single file. 

• top-level device tree file, which is the first dts including other device tree(s). 

• included files representing fragments with /include/ statement, usually dtsi files. 

2.2.1.3 Interrupts View 

In the Interrupts view of the device tree, a logical interrupt tree exists that represents the hierarchy and 

routing of interrupts in the platform hardware. You can view this interrupt tree in the Component 

Inspector when selecting an existing hardware device tree component. 

Figure 18. Interrupts View in Component Inspector 



The left side of the Interrupts view displays the actual representation of the Interrupt tree, starting from 

the root interrupt controller. When you select an element in the Interrupt tree, a table appears on the right 

side listing the interrupt sources for the selected device tree node. Each row in the table provides a userfriendly 

view of a decoded interrupt specifier, and each column in the table represents a specific cell of the 

interrupt specifier. 

You can edit the Interrupts table for each device tree node selected from the device tree. An interrupt tree 

may contain special nodes called interrupt nexuses that map from one interrupt domain to another interrupt 

domain. When you select an interrupt nexus node in the Interrupt tree, the Domain map table appears 

below the Interrupts table on the right side. The Domain Map table allows you to perform interrupt 

domain mapping for the selected interrupt nexus. 

2.2.1.4 Memory Map View 

Figure 19. Interrupts Tree — Nexus Nodes and Domain Map 

You can view a device tree as a representation of different Local Access Windows (LAWs) within a device. 

For example, according to the P4080 Reference Manual, you can define the p4080 address map using a set 

of maximum 32 LAWs. An example of such window is the Configuration Control and Status Register area 

defined by soc node in the device tree. All LAWs can be relocated within the entire address space of the 

platform. Each of these LAWs maps a programmable 4-Kbite to 64-Gbyte region of the local 36-bit 

address space to a specified target interface, such as DDR Controller, Localbus, and PCI Express 

Controller. 



Figure 20. LAW Defined Inside Device Tree 



Each device tree node having reg and ranges properties defines memory ranges inside or outside CCSR 

window. Figure 21 and Figure 22 shows an example of such device tree node. 

Figure 21. reg Property Definition Inside Device Tree 

Figure 22. ranges Property Definition Inside Device Tree 

In Figure 20, pci2 has one block of memory mapped register starting at F_FE20_2000 with size 4-Kbyte 

in the SoC. There are two pci2 ranges (Figure 22) within the entire address space which can be accessed 

by a load or store operation. The first pci2 memory block starts at 0xC_4000_0000 with size of 512- 

MByte; the second pci2 block starts at address 0xF_F802_0000 with size of 64-Kbyte. 

Once all memory blocks are decoded and gathered, they can be visually represented in the Memory Map 

view. The Memory Map view pops-up automatically with the created memory block areas when a device 



tree component is selected in the Component Inspector. The Memory Map view displays its content 

created on the basis of DTS file that comes with the component. Block highlighting is available in the 

Memory Map view. Moreover, selecting a block in the Memory Map view triggers a node selection in 

the graphical device tree. 

2.2.2 Text Editor 

Figure 23. Device Tree Memory Map View 

The text editor of HWDeviceTree component involves syntax highlighting and folding support. The 

device tree GUI editor and the text editor are synchronized. Therefore, when you select a node in the GUI 

editor, the node is selected automatically in the text editor also. The vice versa is also true. Figure 24 shows 

that after selecting the SoC node in the GUI editor, the corresponding entry in the text editor is 

automatically selected. 



Figure 24. Device Tree Text Editor 



If inclusions exist, the merged file will have hovering support in the text editor. When mouse cursor hovers 

over properties and nodes, a tooltip appears displaying initial locations of the files in the Include Tree. 

The merged file is read-only; it gets updated based on other files. Therefore, you can edit only the top-level 

and included files to automatically propagate changes in the final merged file. 



Figure 25. Origin of Included Files 

Hyperlink detection is also supported for /include/ declarations and device tree references. Use CTRL+left 

click combination on these statements to change the context in the referred file or node. 

Figure 26. Hyperlink Detection 

Tips: 

• To see the line numbers in the text editor, enable: 





Window > Preferences > General > Editors > Text Editors > show line numbers option. 

• Play with the views in the workbench to accommodate your needs and have a better perspective. 

2.3 Validation 

The Device Tree Editor allows you to verify the syntax of a device tree and to check if it conforms to the 

set of defined constraints.There are two approaches to display errors, using markers in Eclipse Problems 

view or using decorators in the Properties custom view table. 

2.3.1 Syntax Validation 

Using markers, the error checking is performed for the following: 

• Syntax errors (inappropriate format) 

• More than one root node 

• Duplicate node labels 

• Undefined node reference 

• Properties do not precede sub-nodes 

• In case of inaccuracies, the text editor is decorated with markers on the faulty lines. The markers 

can also be examined in the Eclipse Problems view. 

Figure 27. Errors Detection Using Markers 

If errors are detected, do not rely on the GUI tree, the hierarchy is broken and cannot display the tree. You 

can turn on/off the validation against the device tree bindings in the Device Tree Settings page 



(Figure 34). If it is enabled, the validation starts automatically whenever changes occur in the device tree. 

You can also perform validation manually using the second option in the View toolbar (Figure 8). 

2.3.2 Property Constraints 

Each device tree node is completed and distinguished by an XML "binding". The binding describes which 

properties are required, which are optional, what each property means and what constraints are to be met. 

The repository of device tree bindings is stored at PEx_Data\Beans\HWDeviceTree\dts_bindings. 

The xml binding keeps information about the list of devices supported by the node, node instances, subnodes, 

properties, constraints, and example. Figure 28 shows the structure of a node and a property. 

Figure 28. Xml Node and Property Schema 

Following are the types of constraints that can be assigned to a property: 

• — specifies the type of a property value 

• — specifies whether or not the property can be modified 

• , — specifies the minimum and maximum number of items allowed 

in a property cell 

• — specifies a set of allowed values for a property 

• — bounds a numeric value between minimum and maximum values; it can also force a 

property value to match a regular expression. 

Take an example where you have the dma-channel@0 node as follows: 

dma-channel@0 { 

}; 

dma-channel@100 { 

compatible = "fsl,p5020-dma-channel", "fsl,eloplus-dma-channel"; 

reg = ; 

cell-index = ; 

interrupts = ; 

compatible = "fsl,p5020-dma-channel", "fsl,eloplus-dma-channel"; 

reg = ; 



}; 

cell-index = ; 

interrupts = ; 

Assume you want to define the following constraints: 

• restrict the type of interrupts property to EMPTY for all dma-channel instances 

• for dma-channel@0, define reg property 

— to have at least 3 items in its value 

— first item to be in [0xA, 0xC] range 

— second item to be in [0x0, 0x400] range 

• for dma-channel@100 

— compatible property to be non-editable 

— to have exactly 3 items in its value 

Then the dma-channel.xml file will be modified as shown in Figure 29. 

Figure 29. Example of Defining a Constraint 



Non-editable properties are disabled in the graphical editor, as shown in Figure 30. They can be changed 

only through the text editor. 



Figure 30. Device Tree Property Constraints for Non-editable Properties 

Setting these constraints produce the following warnings in the Problems view: 

• "interrupts" does not meet constraint for all dma-channel instances from all dma nodes 

(4 instances x 2 nodes) 

• "reg" does not meet constraint at dma-channel@0 and dma-channel@100 

instances (there are 2 items and the constraint requires minimum 3) 

• "reg" does not meet constraint at index 0 at dma-channel@0 instances: item at 

index 0 is 0x0 and the constraint requires a value between 0xA, 0xC 

2.4 Search in Device Trees 

Figure 31. Device Tree Property Constraint Warnings 

Use the Search view to search a particular information in the project’s device tree files. The Search view 

can be opened in three ways: 

• Select Search > Search > Device Tree Search in the main menu bar. 

• Search option from the context menu of the Device Tree graphical editor. 

• Use the shortcut CTRL+ALT+H. 



There are three options that specify the criteria based on which you can search the text: 

• Case sensitive 

• Whole word 

• Regular expression 

Figure 32. Device Tree Search View 



By default, searching is performed in the whole workspace and all encountered dts file. To restrict 

searching to a particular project or working set, use the Scope feature in the Search dialog box, which 

provides the following options. 

• Workspace — is the default option; when selected, searches in all open projects 

• Selected resources — searches in the selected resource if applicable; it is a device tree file or 

contains device tree files 

• Enclosing projects — searches in the selected project only 

• Working set — allows you to create a custom working set with the desired resources 

The results appear in the Search view. 



2.5 Generate Device Tree Blob 

Figure 33. Device Tree Search View Results 

The Device Tree Editor enables you to generate device tree binaries if a device tree compiler is available. 

You can find the DTC settings in the Device Tree Compiler page of the Preferences dialog box 

(Figure 34), which appears on selecting Window > Preferences > Processor Expert > Device Tree 

Compiler. 

You can change the default settings. If this functionality is not required, it can be switched off by clearing 

the Use DTC checkbox. 



Figure 34. Device Tree Settings Page 



To generate DTB files, select Project > Generate Processor Expert Code from the IDE menu bar. The 

code is generated per project, therefore, the device tree blobs are created for all encountered device tree 

sources in the opened projects. The resultant device tree blob files are added to the Generated_Code 

folder, as shown in Figure 35. 

2.6 Known Issues/Limitations 

Figure 35. DTB File Generation 

To see a list of known issues and limitations, refer the ReadMe.html file. 


How to Reach Us: 

Home Page: 

www.freescale.com 

Web Support: 

http://www.freescale.com/support 

USA/Europe or Locations Not Listed: 

Freescale Semiconductor, Inc. 

Technical Information Center, EL516 

2100 East Elliot Road 

Tempe, Arizona 85284 

1-800-521-6274 or 

+1-480-768-2130 

www.freescale.com/support 

Europe, Middle East, and Africa: 

Freescale Halbleiter Deutschland GmbH 

Technical Information Center 

Schatzbogen 7 

81829 Muenchen, Germany 

+44 1296 380 456 (English) 

+46 8 52200080 (English) 

+49 89 92103 559 (German) 

+33 1 69 35 48 48 (French) 

www.freescale.com/support 

Japan: 

Freescale Semiconductor Japan Ltd. 

Headquarters 

ARCO Tower 15F 

1-8-1, Shimo-Meguro, Meguro-ku 

Tokyo 153-0064 

Japan 

0120 191014 or 

+81 3 5437 9125 

support.japan@freescale.com 

Asia/Pacific: 

Freescale Semiconductor China Ltd. 

Exchange Building 23F 

No. 118 Jianguo Road 

Chaoyang District 

Beijing 100022 

China 

+86 10 5879 8000 

support.asia@freescale.com 

For Literature Requests Only: 

Freescale Semiconductor 

Literature Distribution Center 

1-800 441-2447 or 

+1-303-675-2140 

Fax: +1-303-675-2150 

LDCForFreescaleSemiconductor 

@hibbertgroup.com 

Document Number:QORIQCSHWDEVTREEUG 

Rev. 5 

06/2012 

Information in this document is provided solely to enable system and software 

implementers to use Freescale Semiconductor products. There are no express or 

implied copyright licenses granted hereunder to design or fabricate any integrated 

circuits or integrated circuits based on the information in this document. 

Freescale Semiconductor reserves the right to make changes without further notice to 

any products herein. Freescale Semiconductor makes no warranty, representation or 

guarantee regarding the suitability of its products for any particular purpose, nor does 

Freescale Semiconductor assume any liability arising out of the application or use of 

any product or circuit, and specifically disclaims any and all liability, including without 

limitation consequential or incidental damages. “Typical” parameters which may be 

provided in Freescale Semiconductor data sheets and/or specifications can and do 

vary in different applications and actual performance may vary over time. All operating 

parameters, including “Typicals” must be validated for each customer application by 

customer’s technical experts. Freescale Semiconductor does not convey any license 

under its patent rights nor the rights of others. Freescale Semiconductor products are 

not designed, intended, or authorized for use as components in systems intended for 

surgical implant into the body, or other applications intended to support or sustain life, 

or for any other application in which the failure of the Freescale Semiconductor product 

could create a situation where personal injury or death may occur. Should Buyer 

purchase or use Freescale Semiconductor products for any such unintended or 

unauthorized application, Buyer shall indemnify and hold Freescale Semiconductor 

and its officers, employees, subsidiaries, affiliates, and distributors harmless against all 

claims, costs, damages, and expenses, and reasonable attorney fees arising out of, 

directly or indirectly, any claim of personal injury or death associated with such 

unintended or unauthorized use, even if such claim alleges that Freescale 

Semiconductor was negligent regarding the design or manufacture of the part. 

Freescale, the Freescale logo, CodeWarrior, QorIQ, Processor Expert are 

registered trademarks of Freescale Semiconductor, Inc., Reg. U.S. Pat. & 

Tm. Off. 

All other product or service names are the property of their respective 

owners. 

© 2011 Freescale Semiconductor, Inc.

QorIQ Configuration Suite Device Tree Editor - Freescale ...

You also want an ePaper? Increase the reach of your titles

Delete template?

Save as template?