Summary
This guide describes how to use the device tree generator. The device tree generator is a Xilinx EDK tool that plugs into the Automatic BSP Generation features of the tool, XPS.
The purpose of the device tree generator is to produce a device tree file (xilinx.dts) that has the information for the hardware design in your EDK project. This alleviates having to create a device tree file with a text editor, which can be quite tedious.
The device tree generator is called device-tree, which is at git://git.xilinx.com/device-tree.git.1
Device Tree Documentation
The Device Tree Generator is a best effort attempt to generate a device tree and some hand editing of the device tree file may be required.
The device tree is documented (somewhat) in the Linux kernel at Documentation/powerpc/booting-without-of.txt and in the dts-bindings directory.
The following link, http://ozlabs.org/~dgibson/papers/dtc-paper.pdf, also has some useful information.
Also, http://www.devicetree.org/Device_Tree_Usage is a wiki with some good information and links to more official documents.
Updates Since 12/20/12
- The device tree generator was merged together with the generator from Petalinux.
Updates Since 1/1/11
- Added support for Little Endian/AXI systems.
Getting the Device Tree Generator From Xilinx
The device tree generator is located in a repository of the Xilinx GIT server. It is not part of the Xilinx SDK. For users without Git, see the page at http://git.xilinx.com as it indicates how to create a snapshot (tar ball) of the kernel.
Now (starting in 14.4, 12/20/12) the device tree repository does not include the paths which are required for the SDK to find it as a BSP. The following command incorporates the required additions to cause Git to create the required directory structure (bsp/device-tree_v0_00_x).
bash> git clone git://git.xilinx.com/device-tree.git bsp/device-tree_v0_00_x
For older device tree repositories, the repository can be cloned with the following command which does not need to create any additional directory structure.
bash> git clone git://git.xilinx.com/device-tree.git
EDK/SDK Setup (for EDK versions 12.4 and newer)
Starting in EDK 12.4, the device-tree generation was moved from EDK/XPS to SDK. It now must be generated in the SDK which can be launched from the EDK (or other ways).
After getting the device tree generator from git://git.xilinx.com/device-tree.git, you will need to unpack and save the 'bsp' directory and contents to any location that can be accessed by the SDK. The SDK requires the user to point it to the directory that contains the bsp folder.
Export the hardware design to the SDK by selecting the 'Project' menu in the EDK, followed by the 'Export Hardware Design to SDK' submenu. Note that a similar operation, exporting a hardware project to the SDK, can be done from the ISE tool for ISE projects that have an EDK project embedded in them. The dialog box which is similar to the one illustrated below will be displayed.
The 'Include bitstream and BMM file' option does not need to be selected for running the device-tree generator.
Select 'Export and Launch SDK' to launch the SDK. After selecting/creating a workspace, the hardware specification will be already defined in the SDK workspace.
Alternatively do 'Export Only' and launch SDK any other way. In this case the hardware specification has to be declared with 'File' —> 'New' —> 'Xilinx Hardware Platform Specification'.
Enter a Project Name and in for the 'Target Hardware Specification' browse to the .xml file that was exported from EDK/XPS before. It usually can be found in the <xps project>/SDK/SDK_Export/hw folder.
After this step the 'Project Explorer' should show the Hardware Platform like for example:
From the SDK, select the 'Xilinx Tools' menu followed by the 'Repositories' submenu. A dialog box similar to the one illustrated below will be displayed.
Select the 'New' button and then browse to the directory where the device-tree downloaded from the Git server has been extracted.
Select the folder containing the 'bsb' subdirectory. Select the 'Rescan Repositories' button. Select the 'OK' button to complete the addition of the new repository.
Note the INFO messages on the SDK console.
Using the Device Tree Generator
Now a Device Tree BSP can be created. Select the 'File' menu, followed the 'New' submenu, followed by the 'Xilinx Board Support Package" submenu. A dialog box similar to the one illustrated below will be displayed to allow the device tree to be selected.
Select the 'device-tree' as 'Board Support Package OS' and the hit the 'Finish' button.
In the next dialog, 'bootargs' and 'console device' can be specified, as described in section 'Device Tree Options'.
Clicking OK adds the device-tree-bsp to the SDK workspace and displays it in the 'Project Explorer'.
In case the SDK project has set 'Project' —> 'Build Automatically', the device-tree generator immediately runs to create the device-tree (xilinx.dts).
If not, right-mouse-click the device-tree BSP in 'Project Explorer' and run 'Build Project'.
The xilinx.dts file is located in <workspace>/<device-tree_bsp>/<processor-name>/libsrc/device-tree_v0_00_x folder.
The device tree data is now ready for building the linux kernel.
EDK Setup (for EDK versions 12.3 and older)
After getting the device tree generator from git://git.xilinx.com/device-tree.git, you will need to copy the 'bsp' directory and contents so that it can be used by XPS. The simplest approach is to copy the 'bsp' directory to the top of your project directory.2
NOTE: Under Centos 5 or Ubuntu, you have to softlink the libdb library. In Centos 5, run "ln -s /lib/libdb-4.3.so /lib/libdb-4.1.so" to get the dts generator to finish under certain circumstances.
cp -r bsp <path to project>/
If your project is currently open in XPS, you will need to close and re-open the project for XPS to notice the changes.
Using the Device Tree Generator
Open the pull down menue 'Software' and proceed to 'Software Platform Settings…' in XPS.
To use the device tree generator, select 'device-tree' in the pull down menu labeled 'OS' in the Software Platform Settings dialog box.
Then select 'OS and Libraries' on the left, and enter the values for 'console device' and 'bootargs'
Finally close the Software Platform Settings dialog box by clicking on the 'OK' button, and select 'Generate Libraries and BSPs' from the software menu. The resulting device tree file (xilinx.dts) will reside in your project directory in <processor instance>/libsrc/device-tree/xilinx.dts.
Device Tree Options
Console Device Option
The 'console device' option lets you select which IP core is to be used for the console. This value is needed by linux for output early during bootup. Put in the name of the instance (e.g. RS232_Uart_1) rather than the type of the core (e.g. not xps_uart16550). The IP instance name can be found in XPS using the 'System Assembly View' tab (in the middle of the XPS window).
Bootargs Option
The 'bootargs' option lets you type in the text for the linux kernel bootargs. The default value (at the time of this writting) is
console=ttyS0 root=/dev/ram
Change the text to what is needed for your system. The following section describes a few of the common options given in bootargs.
console
The value for console=… needs to select the same device given in the 'console device' option. The following is a table showing what device to select in 'console=' based on Xilinx device types commonly used for the console.
| device type | console text |
|---|---|
| xps_uart16550 | console=ttySN |
| xps_uartlite | console=ttyULN3 |
| N is 0 for the first device of the type. N is 1 for the second device of the type etc. | |
ip
The option ip=… specifies the ip address used. To use dhcp to dynamically assign an ip address, specify
ip=on
To specify a static ip address, for example 192.168.1.10, use
ip=192.168.1.10
root
The option root=… tells the linux kernel where to find the root filesystem. The root filesystem can be in ram, on the compact flash disk, or even on an nfs share on a remote computer. Add the option rw after the option if you would like the filesystem to be read/writeable. Please note that for ramdisk images, any changes will be in ram only and lost on reboot.
The following is a table showing various bootarg options for different root filesystem locations.
| root filesystem location | bootarg options |
|---|---|
| ramdisk | root=/dev/ram |
| compact flash disk | root=/dev/xsysace/disc0/partN (where N is the partition number of the root file system.)4 5 |
| nfs | root=/dev/nfs nfsroot=<nfs server>:<nfs share>,tcp (e.g. root=/dev/nfs nfsroot=192.168.1.1:/nfsroots/development,tcp) |
