Sopc2dts

[#1]

Sopc2dts

Contents

 [hide] 

• 1 Intro
• 2 Basic usage
• 3 Boardinfo files
• 3.1 Extended Board Info Functionality
• 3.1.1 IRQMasterIgnore
• 3.1.2 alias
• 3.1.3 DTAppend
• 4 Module and Interface Assignments in hw.tcl Influencing Sopc2dts
• 4.1 Protecting Field Names and Value Content
• 4.2 Additional Parameters added to the device tree

Intro

sopc2dts is a java program for generating (amongst others) device-tree sources (dts files) from an sopc/qsys system. You'll need a JDK (1.5 or above) in order to compile it. You can get it from the community git-server by:

git clone https://github.com/wgoossens/sopc2dts

cd sopc2dts

make

If your IT department blocks the git protocol, the git tree is mirrored and available over at rocketboards.org.

git clone http://git.rocketboards.org/sopc2dts.git

Basic usage

In order to actually do anything remotely usefull, sopc2dts needs an (sopcinfo) input file and an optional boardinfo xml-file. For more info on the boardinfo stuff, please read on.

To generate a dts file from an sopcinfo file you can use:

java -jar sopc2dts.jar -i mysystem.sopcinfo

You'll see the devicetree printed on you console.

To write the output to a file:

java -jar sopc2dts.jar -i mysystem.sopcinfo -o mydevicetree.dts

To get some click-and-point action, you can run:

java -jar sopc2dts.jar --gui

For some more explanation on what parameters to pass try:

java -jar sopc2dts.jar --help

Boardinfo files

There are always some settings your board has that need to be encoded in the devicetree but are not present in your sopcinfo file. Examples are: flash-partitions, what memory to execute your kernel from, i2c-devices on your board, mac-addresses etc. They could (theoretically) be passed on the commandline, but that would get ugly real soon. That's where the boardinfo file comes in. The boardinfo file is a simple xml-file that describes everything that's needed for generating a devicetree but cannot be read from the sopcinfo file. A boardinfo file is optional, but highly recommended.

The most critical entry in the boardinfo file is the point-of-view component (pov). You can also specify the point-of-view component by the --pov commandline option. The pov component is the component that's the master from which the system is described. If there's only one avalon-master in your system you can leave this one out and the program will find it out by itself, but if you have multiple processors (or even a processor and another avalon-master, then things might get ugly.

To generate a boardinfo for your board:

• Launch sopc2dts in gui mode (--gui)
• Choose the sopcinfo file describing your system in the "input" tab. (If you specified it on the commandline it's already loaded)
• Look over (and adjust) the various bits in the "boardinfo" tab. Press apply after you've made a change!
• Check the output tab to see the effect on your generated devicetree.
• Once satisfied, or convinced thar it really won't get any better, you can choose a filename in the "boardinfo" tab and press save.

Everytime you run sopc2dts you can specify the boardinfo file (-b) and you get all the settings you've made in the gui.

--THe IkkE 17:57, 16 September 2011 (CDT)

Extended Board Info Functionality

As part of the effort to support the new SOCFPGA line of chips, the type of information that can be put into the board info file has been expanded. At this time much of this new functionality is not in the GUI. To use this new functionality one must edit the board info file by hand.

IRQMasterIgnore

There are cases where interrupt senders are connected to multiple interrupt receivers (e.g. an interrupt controller and an interrupt debug component), but the device tree generated by sopc2dts needs to identify the correct interrupt parent/controller. To help sopc2dts identify the correct interrupt connection, one can use one or more IRQMasterIgnore tags in the board info file like the example below:

<IRQMasterIgnore className="intr_capturer"/>

In the line above, interrupt receivers with the class name, intr_capturer, are ignored. Once can also ignore specific instances of interrupt receiver components by using the label attribute as shown below:

<IRQMasterIgnore label="intr_capturer_0"/>

alias

Device Tree Source syntax supports the notion of alias. Correspondingly, a board info file can contain one or more alias tags. The following alias tags will generate the aliases device tree node that follows:

<alias name="ethernet0" value="/sopc/ethernet@0xff702000"/>

<alias name="serial0" value="/sopc/serial@xffc02000"/>

<alias name="timer0" value="/sopc/timer@xffc08000"/>

<alias name="timer1" value="/sopc/timer@xffc09000"/>

<alias name="timer2" value="/sopc/timer@0xffd00000"/>

<alias name="timer3" value="/sopc/timer@0xffd01000"/>

aliases {

ethernet0 = "/sopc/ethernet@0xff702000";

serial0 = "/sopc/serial@xffc02000";

timer0 = "/sopc/timer@xffc08000";

timer1 = "/sopc/timer@xffc09000";

timer2 = "/sopc/timer@0xffd00000";

timer3 = "/sopc/timer@0xffd01000";

}; //end aliases

DTAppend

Given the speed of change of the Linux kernel and its use of device tree, it is hard to anticipate what fields need to be added to a particular device tree node to get its corresponding driver to work. The new board info tag, DTAppend is intended to help. An example of a simple usage of the DTAppend tag is shown below:

<DTAppend name="status" type="string" parentlabel="hps_0_nand0" val="disabled"/>

The tag above will add a field named, status, to the node with the label, hps_0_nand0, with the string value of "disabled". The valid types are bool, number, string, hex, byte, phandle, and node. When the type is node, the DTAppend tag has a slightly different format:

<DTAppend name="fpga3" type="node" parentlabel="soc_leds" newlabel="led_fpga3"/>

In the example above, a new node named, fpga3, with a label, led_fpga3, will be created under node labeled, soc_leds.

Fields in a device tree can also have multiple values of differing types. The DTAppend tag uses the following format to create such fields:

<DTAppend name="gpios" parentlabel="led_hps1" >

<val type="phandle">hps_0_gpio1</val>

<val type="number">14</val>

<val type="number">1</val>

</DTAppend>

Module and Interface Assignments in hw.tcl Influencing Sopc2dts

The properties and behaviors of a Qsys component are described in a file referred to as a hw.tcl file. Hw.tcl is just an extension of tcl described at http://www.altera.com/literature/hb/qts/qsys_tcl.pdf. Hw.tcl allows for arbitrary name/value pairs to be assigned to modules and to interfaces with the hw.tcl statements, set_module_assignment and set_interface_assignment, respectively. At design generation time, these assignments are put in the resulting sopcinfo file. Sopc2dts looks for these interface and module assignments to the namespace, embeddedsw.dts., when creating device trees.

At it turns out, many of the values for fields in a device tree node may not be finalized until a design's generation phase. So performing these assignments in hw.tcl is quite convenient. Also, if the hw.tcl for an IP component has the minimum required set of assignments, then sopc2dts will just work without additions to the sopc_components_*.xml files included with the tool. This method of driving device tree generation by sopc2dts with hw.tcl assignments has been adopted as a “Best Practice” for Altera IP component authors. Part of this practice also involves working closely with an embedded software engineer to ensure the assignments are correct.

The set_module_assignment statements below are an example of the minimum required set of assignments for a component:

set_module_assignment embeddedsw.dts.vendor "snps"

set_module_assignment embeddedsw.dts.name "dw-apb-uart"

set_module_assignment embeddedsw.dts.group "serial"

The assignments above will produce the device tree shown below. The name, embeddedsw.dts.vendor, is the vendor of the component, typically the stock name of the company. Embeddedsw.dts.name is the name of the component IP, and embeddedsw.dts.group is the type of component.

uart0: serial@0xffc02000 {

compatible = "snps,dw-apb-uart-1.0";

reg = < 0xFFC02000 0x00001000 >;

interrupt-parent = < &hps_0_arm_gic_0 >;

interrupts = < 0 162 4 >;

}; //end serial@0xffc02000 (uart0)

The device tree field name, compatible, helps the Linux kernel associate a driver to the device tree node. Sopc2dts will create a compatible field by combining the values of the embeddedsw.dts.vendor and embeddedsw.dts.name with a version number. In a device tree node, the compatible field is a list of quoted strings. One can add strings to the list by making an assignment to embeddedsw.dts.compatible. The value of the assignment is considered a single string, but the space character inside the string will delineate fields.

set_module_assignment embeddedsw.dts.compatible {snps,dw-uart ns16550}

The assignment stament above will add two elements to the compatible field in the device tree node with the following result:

uart0: serial@0xffc02000 {

compatible = "snps,dw-apb-uart-1.0", “snps,dw-uart”, “ns16550”;

reg = < 0xFFC02000 0x00001000 >;

interrupt-parent = < &hps_0_arm_gic_0 >;

interrupts = < 0 162 4 >;

}; //end serial@0xffc02000 (uart0)

Protecting Field Names and Value Content

TCL is a little vague about strings versus numbers, and special characters can have unintended consequences. In some cases one might need to protect the name a field or the content of a value by surrounding them with a pair of braces, {}, as shown below.

set_module_assignment embeddedsw.dts.compatible {arm,cortex-a9-gic}

set_module_assignment {embeddedsw.dts.params.#interrupt-cells} 3

In the example above, the value of the compatible field is protected because of the comma in the string, and the key specifying the number of values in an interrupt cell is protected because of the comment character, #.

Additional Parameters added to the device tree

Additional key/value pairs can be added to the Device Tree Node by assignments to embeddedsw.dts.params.*. The key in the Device Tree Node will be the text after the “embeddedsw.dts.params.”

set_module_assignment embeddedsw.dts.params.reg-io-width 4

set_module_assignment embeddedsw.dts.params.reg-shift 2

set_module_assignment embeddedsw.dts.params.tx-fifo 1024

set_module_assignment embeddedsw.dts.params.rx-fifo 1024

The assignments above result in the field assignments in the DTS shown below:

reg-io-width = < 4 >;

reg-shift = < 2 >;

tx-fifo = < 1024 >;

rx-fifo = < 1024 >;

The DTS field assignments above are cells of numerical value. The assignment below is a string value: set_module_assignment embeddedsw.dts.params.stringkey value

The example above has a value that is a string which will result in the DTS field being shown as follows:

stringkey = “value”;