Using the device tree to describe embedded ... - Parent Directory

Reprinted from theProceedings of theLinux SymposiumJuly 23rd–26th, 2008Ottawa, OntarioCanada

Conference OrganizersAndrew J. Hutton, Steamballoon, Inc., Linux Symposium,Thin Lines MountaineeringC. Craig Ross, Linux SymposiumReview CommitteeAndrew J. Hutton, Steamballoon, Inc., Linux Symposium,Thin Lines MountaineeringDirk Hohndel, IntelGerrit Huizenga, IBMDave Jones, Red Hat, Inc.Matthew Wilson, rPathC. Craig Ross, Linux SymposiumProceedings Formatting TeamJohn W. Lockhart, Red Hat, Inc.Gurhan Ozen, Red Hat, Inc.Eugene Teo, Red Hat, Inc.Kyle McMartin, Red Hat, Inc.Jake Edge, LWN.netRobyn BergeronDave Boutcher, IBMMats Wichmann, IntelAuthors retain copyright to all submitted papers, but have granted unlimited redistribution rightsto all as a condition of submission.

A Symphony of Flavours: Using the device tree to describe embeddedhardwareGrant LikelySecret Labgrant.likely@secretlab.caJosh BoyerIBMjwboyer@linux.vnet.ibm.comAbstractAs part of the merger of 32-bit and 64-bit PowerPC supportin the kernel, the decision was to also standardizethe firmware interface by using an OpenFirmware-styledevice tree for all PowerPC platforms; server, desktop,and embedded. Up to this point, most PowerPC embeddedsystems were using an inflexible and fragile,board-specific data structure to pass data between theboot loader and the kernel. The move to using a devicetree is expected to simplify and generalize the PowerPCboot sequence.This paper discusses the implications of using a devicetree in the context of embedded systems. We’ll coverthe current state of device tree support in arch/powerpc,and both the advantages and disadvantages for embeddedsystem support.1 BackgroundWe could go on for days talking about how embeddedsystems differ from desktops or servers. However, thispaper is interested in one particular aspect: the methodused by the operating system to determine the hardwareconfiguration.In general, desktop and server computers are engineeredto be compatible with existing software. The expectationis that the operating system should not need to be recompiledevery time new hardware is added. Standardizedfirmware interfaces ensure that the boot loader canboot the operating system and pass it important detailssuch as memory size and console device. PCs have theBIOS. PowerPC and Sparc systems typically use Open-Firmware. Commodity hardware is also designed to beprobeable by the OS so that the full configuration of thesystem can be detected by the kernel.The embedded world is different. Systems vary wildly,and since the software is customized for the system,there isn’t the same market pressure to standardizefirmware interfaces. You can see this reflected in theboot schemes used by embedded Linux. Often the operatingsystem is compiled for a specific board (platform)with the boot loader providing minimal informationabout the hardware layout, and the platform initializationcode is hard coded with the system configuration.Similarly, data that is provided by the boot firmware isoften laid out in an ad-hoc manner specific to the boardport. The old embedded PowerPC support in the kernel(found in the arch/ppc subdirectory) uses a particularlybad method for transferring data between theboot loader and the kernel. A structure called bd_info,which is defined in include/asm-ppc/ppcboot.h,defines the layout of the data provided by the bootloader. #defines are used within the structure to addplatform-specific fields, but there is no mechanism todescribe which bd_info layout is passed to the kernelor what board is present. Changes to the layout ofbd_info must be made in both the firmware and thekernel source trees at the same time. Therefore, the kernelcan only ever be configured and compiled for a singleplatform at a time.When the decision was made to merge 32-bit (arch/ppc) and 64-bit (arch/ppc64) PowerPC support in thekernel, it was also decided to use the opportunity toclean up the firmware interface. For arch/powerpc(the merged architecture tree), all PowerPC platformsmust now provide an OpenFirmware-style device treeto the kernel at boot time. The kernel reads the devicetree data to determine the exact hardware configurationof the platform.• 27 •

28 • A Symphony of Flavours: Using the device tree to describe embedded hardware/ { // the root nodean-empty-property;a-child-node {array-prop = ;string-prop = "hello, world";};another-child-node {binary-prop = [0102CAFE];string-list = "yes","no","maybe";};};Figure 1: Simple example of the .dts file formatEthernet irq: 2 Serial 1 irq: 3 Serial 2 irq: 4 FlashIRQ ControllerPowerPC 440OPB Bridge128MB RAMPLB BusFigure 2: Example PowerPC 440 System2 Description of Device TreesIn the simplest terms, a device tree is a data structure thatdescribes the hardware configuration. It includes informationabout the CPUs, memory banks, buses, and peripherals.The operating system is able to parse the datastructure at boot time and use it to make decisions abouthow to configure the kernel and which device drivers toload.The data structure itself is organized as a tree with a singleroot node named /. Each node has a name and mayhave any number of child nodes. Nodes can also havean optional set of named property values containing arbitrarydata.The format of data contained within the device treeclosely follows the conventions already established byIEEE standard 1275. While this paper covers a basiclayout of the device tree data, it is strongly recommendedthat Linux BSP developers reference the originalIEEE standard 1275 documentation and other Open-Firmware resources. [1][2]The device tree source (.dts) format is used to expressdevice trees in human-editable format. The device treecompiler tool (dtc) can be used to translate device treesbetween the .dts format and the binary device tree blob(.dtb) format needed by an operating system. Figure 1is an example of a tree in .dts format. Details of thedevice tree blob data format can be found in the kernel’sDocumentation directory. [3]For illustrative purposes, let’s take a simple example ofa machine and create a device tree representation of thevarious components within it. Our example system isshown in Figure 2./dts-v1// {model = "acme,simple-board";compatible = "acme,simple-board";#address-cells = ;#size-cells = ;// Child nodes go here};Figure 3: Example system root nodeIt should be noted that the device tree does not need tobe an exhaustive list of all devices in the system. It isoptional to itemize devices attached to probable busessuch as PCI and USB because the operating system alreadyhas a reliable method for discovering them.2.1 The root NodeThe start of the tree is called the root node. The rootnode for our simple machine is shown in Figure 3. Themodel and compatible properties contain the exactname of the platform in the form ,,where is the system vendor, and isthe board model. This string is a globally unique identifierfor the board model. The compatible property is notexplicitly required; however, it can be useful when twoboards are similar in hardware setup. We will discusscompatible values more in Section 2.4.1.2.2 The cpus NodeThe cpus node is a child of the root node and it has achild node for each CPU in the system. There are no ex-

2008 Linux Symposium, Volume Two • 29cpus {#address-cells = ;#size-cells = ;cpu@0 {device_type = "cpu";model = "PowerPC,440GP";reg = ;// 400MHz clocksclock-frequency = ;timebase-frequency = ;i-cache-line-size = ;d-cache-line-size = ;i-cache-size = ;d-cache-size = ;};};Figure 4: cpus nodememory {device_type = "memory";// 128MB of RAM based at address 0reg = ;};Figure 5: Memory nodethe processor local bus is typically a direct child of theroot node. Devices and bridges attached to the local busare children of the local bus node. Figure 6 shows thehierarchy of device nodes for the sample system. Thishierarchy shows an interrupt controller, an Ethernet device,and an OPB bridge attached to the PLB bus. Twoserial devices and a Flash device are attached to the OPBbus.plicitly required properties for this node; however, it isoften good practice to specify #address-cells=,and #size-cells=. This specifies the format forthe reg property of the individual CPU nodes, which isused to encode the physical CPU number.CPU nodes contain properties for each CPU on theboard. The unit name for CPU nodes is in the formcpu@0 and it should have a model property to describethe CPU type. CPU nodes have properties to specify thecore frequency, L1 cache information, and timer clockfrequency. Figure 4 is the cpus node for our samplesystem.2.3 System MemoryThe node that describes the memory for a board is, unsurprisingly,called a memory node. It is most commonto have a single memory node that describes all of thememory ranges and is a child of the root node. The regproperty is used to define one or more physical addressranges of usable memory. Our example system has 128MiB of memory, so the memory node would look likeFigure 5.2.4 DevicesA hierarchy of nodes is used to describe both the busesand devices in the system. Each bus and device in thesystem gets its own node in the device tree. The node for2.4.1 The compatible propertyYou’ll notice that every node in the device hierarchy hasa compatible property. compatible is the key thatan OS uses to decide what device a node is describing.In general, compatible strings should be in the form,. For each unique setof compatible values, there should be a device treebinding defined for the device. The binding documentswhat hardware the node describes and what additionalproperties can be defined to fully describe the configurationof the device. Typically, bindings for new devicesare documented in the Linux Documentation directoryin booting-without-of.txt [3].You’ll also notice that sometimes compatible is a listof strings. If a device is register-level compatible withan older device, then it can specify both its compatiblestring and the string for the older device, so that anoperating system knows that the device is compatiblewith an older device driver. These strings should be orderedwith the specific device first, followed by a list ofcompatible devices. For example, the flash device in thesimple system claims compatibility with cfi-flash,which is the string for CFI-compliant NOR flash chips.2.4.2 AddressingThe device address is specified with the reg property.reg is an array of cell values. In device tree terminol-

30 • A Symphony of Flavours: Using the device tree to describe embedded hardwareplb {compatible = "simple-bus";#address-cells = ;#size-cells = ;ranges;UIC0: interrupt-controller {compatible = "ibm,uic-440gp","ibm,uic";interrupt-controller;#interrupt-cells = ;};ethernet@20000 {compatible = "ibm,emac-440gp";reg = ;interrupt-parent = ;interrupts = ;};opb {compatible = "simple-bus";#address-cells = ;#size-cells = ;ranges = ;serial@0 {compatible = "ns16550";reg = ;interrupt-parent = ;interrupts = ;};serial@10000 {compatible = "ns16550";reg = ;interrupt-parent = ;interrupts = ;};flash@1ff00000 {compatible = "amd,s29gl256n","cfi-flash";reg = ;};};};Figure 6: Simple System Device Hierarchyogy, cells are simply 32-bit values. Array properties likereg are arrays of cell values. Each reg property is a listof one or more address tuples on which the device canbe accessed. The tuple consists of the base address ofthe region and the region size.reg = ;The actual size of each reg tuple is defined by the parentnodes’ #address-cells and #size-cells properties.#address-cells is the number of cells usedto specify a base address. Similarly, #size-cells isthe number of cells used to specify a region size. Thenumber of cells used by reg must be a multiple of#address-cells plus #size-cells.It is important to note that reg defines bus addresses,not system addresses. The bus address is local to thebus that the device resides on, or in device tree terms,the address is local to the parent of the node. Buses inturn can map bus addresses up to their parent using theranges property. The format of ranges is:ranges = ;Where addr is a bus address and is #address-cellswide, parent is an address on the parent bus and is theparent node’s #address-cells wide. size is the parentnode’s #size-cells wide.Buses that provide a 1:1 mapping between bus addressand parent address can forgo the explicit mapping describedabove and simply specify an empty rangesproperty:ranges;In this example system, the Flash device is at address0x1ff00000 on the OPB bus, and the OPB bus specifiesthat PLB bus address 0xe0000000 is mapped to address0x0000000 on the OPB bus. Therefore, the Flash devicecan be found at base address 0xfff00000.2.5 Interrupts and Interrupt ControllersThe natural layout of a tree structure is perfect for describingsimple hierarchies between devices, but is notparticularly suitable for capturing complex interconnections.Interrupt signals are a good example of additional linkages.For example, it is correct to describe the serialdevice in our sample system as a child of the OPB bus.However, it is also correct to say that it is a child of theinterrupt controller device, so how should this be describedin the device tree? Established convention saysthat the natural tree structure should be used to describethe primary interface for addressing and controlling thedevices. Secondary connections can then be described

2008 Linux Symposium, Volume Two • 31with an explicit link between nodes called a phandle. Aphandle is simply a property in one node that contains apointer to another node.For the case of interrupt connections, device nodesuse the interrupt-parent and interrupts propertiesto describe a connection to an interrupt controller.interrupt-parent is a phandle to the node that describesthe interrupt controller and interrupts is a listof interrupt signals on the interrupt controller that thedevice can raise.Interrupt controller nodes must define an empty propertycalled interrupt-controller. They also mustdefine #interrupt-cells as the number of cells requiredto specify a single interrupt signal on the interruptcontroller, similar to how #address-cells specifiesthe number of cells required for an address value.Many systems, particularly SoC systems, only have oneinterrupt controller, but more than one can be cascadedtogether. The links between interrupt controllers and devicesform the interrupt tree.Referring back to the serial device node, the propertyinterrupt-parent defines the link between the nodeand its interrupt parent in the interrupt tree.The interrupts property defines the specific interruptidentifier. Its format depends on its interrupt parent’s#interrupt-cells property and the values containedwithin are specific to that interrupt domain. Acommon binding for this property when the parent’s#interrupt-cells property is 2 is to have the firstcell represent the hardware interrupt number for the devicein the interrupt controller, followed by its level/sense information.2.6 Special Nodes2.6.1 The chosen NodeFirmware often needs to pass non-hardware types of informationto the client OS, such as console port, andboot arguments. The node that describes this kind ofinformation is called the /chosen node. There are norequired properties for this node; however, it is quiteuseful for defining the board setup. If our example systembooted from a USB key and used the serial port asthe console, the /chosen node might look like Figure 7.chosen {bootargs = "root=/dev/sda1 rw ip=off";linux,stdout-path ="/plb/opb/serial@10000";};Figure 7: Chosen nodealiases {console = "/plb/opb/serial@10000";ethernet0 = "/plb/ethernet@20000";serial0 = "/plb/opb/serial@0";serial1 = "/plb/opb/serial@10000";};2.6.2 aliasesFigure 8: Aliases nodeIn order to ease device lookup in client operating systems,it is often desirable to define an aliases node.This allows one to provide a shorthand method for identifyinga device without having to specify the full pathon lookup. This is typically only done for the more commondevices on a board, such as Ethernet or serial ports.Figure 8 provides an example.The types of nodes and properties that can be containedin a device tree are as varied as the hardware that theydescribe. As hardware designers invent new and creativeways of designing components, these unique propertieswill continue to grow. However, the direction is to beas general as possible to allow commonality betweenthe various hardware components across these boards.Given the flexible nature of the device tree concept, thehope is that the client operating systems will be able toadapt to new hardware designs with a minimal amountof code churn and allow the most possible reuse of code.3 Usage of Device Tree in Linux Kernel3.1 Early BootTo understand how the kernel makes use of the devicetree, we will start with a brief overview of thearch/powerpc boot sequence. arch/powerpc providesa single entry point used by all PowerPC platforms.The kernel expects a pointer to the device tree

32 • A Symphony of Flavours: Using the device tree to describe embedded hardwareblob in memory to be in register r3 before jumping tothe kernel entry point. 1The kernel first does some basic CPU and memoryinitialization, and then it tries to determine what kindof platform it is running on. Each supported platformdefines a machdep_calls structure. The kernelcalls probe_machine(), which walks through themachine_desc table, calling the .probe() hook foreach one. Each .probe() hook examines the devicetree and returns true if it decides that the tree describesa board supported by that platform code. Typically, aprobe will look at the compatible property on the rootnode of the tree to make the decision, but it is free tolook at any other property in the tree. When a probehook returns true, probe_machine() stops iteratingover the table and the boot process continues.3.2 Device initializationcannot be probed. Platform code 2 can use the of_platform_bus_probe() convenience function to iterateover a part of the device tree and register a structof_device for each device. Device drivers in turn registera struct of_platform_driver, and the of_platform infrastructure matches drivers to devices.The core of both the platform and of_platformbuses is almost identical, which begs the question ofwhy do two separate software buses exist in the firstplace? The primary reason is that they use differentmethods to match devices to drivers. The platform bussimply matches a device and a driver if they share thesame .name property. The of_platform bus insteadmatches drivers to devices on the basis of property valuesin the tree; in particular, the driver provides a matchtable of name, device_type, and compatible properties’values. When the values in one of the table entriesmatch the values in an of_device, then the buscalls the driver’s probe hook.In most regards, using the device tree has little impacton the rest of the boot sequence. Platform code registersdevices into the device model and device drivers bindto them. Probable buses like PCI and USB probe fordevices and have no need for the device tree. Sequencewise,the boot process doesn’t look much different, sothe real impact is not on the sequence, but rather onwhere the kernel obtains information from about peripheralsattached to the system.The interesting questions, then, revolve around how theplatform code determines what devices are present andhow it registers them with the kernel.3.2.1 of_platform busCurrently, most embedded platforms using the devicetree take advantage of the of_platform bus infrastructure.Like the platform bus, the of_platformbus doesn’t represent a hardware bus. It is a softwareconstruct for manually registering devices intothe device model; this is useful for hardware which1 Actually, this is not entirely true. If the boot firmware providesan Open Firmware-compatible client interface API, then the kernelfirst executes the prom_init() trampoline function to extractthe device tree from the firmware before jumping into the commonentry point.3.2.2 platform bus adaptersWhile the of_platform bus is often convenient, it isby no means mandated or the only way to retrieve deviceinformation out of the device tree. Some driversalready exist with platform bus bindings and the developershave decided not to rework the binding to useof_platform. Rather, a helper function is used tosearch the device tree for nodes with the appropriateproperty values. When interesting nodes are found, thefunction creates a new struct platform_device,populates it with data from the tree node, and registersit with the platform bus. Several examples of this can beseen in arch/powerpc/syslib/fsl_soc.c. As ofthis writing, the Freescale Gianfar, USB host controller,and I2C device drivers work this way.There is some debate amongst the Linux PowerPC hackersover whether to merge the of_platform bus functionalityback into the platform bus. Doing so wouldeliminate a lot of duplicated code between them, but itleaves the question of how to match drivers and devices.The following are some of the options:2 Not to be confused with the platform bus. Platform code in thiscontext refers to the support code for a particular hardware platformand can be found in the arch/powerpc/platforms subdirectory.

2008 Linux Symposium, Volume Two • 33Teach platform bus about device tree matching. Ifthe platform drivers could optionally supply an OFmatch table, it could be used if the platform device alsohad a pointer to a device node in the tree. The downsideis that it increases the complexity of platform devices,but these are intended to be simple constructs. It is uncertainwhether this approach would be acceptable to theplatform bus maintainers.Translate between nodes properties and platformbus names. This approach has a minimal amount ofimpact on existing platform bus drivers. However, itrequires the match table to also supply functions forpopulating pdata structures from the data in the devicetree. Also, device-tree-to-platform-bus translation mustoccur at boot time and not at module load time, whichmeans that the binding data must be contained within thedriver module. Besides, device registration is supposedto be under the control of platform code. It is poor formfor drivers to register their own platform devices.Make drivers search the device tree directly. Thissolves the problem of data about matching devices beingseparate from the device driver, but it doesn’t work sowell because there is no easy way to prevent multipledrivers from binding against the same node. Once again,it is bad form for drivers to register their own devices.3.2.3 Other MethodsOf course, not all initialization fits simply within theplatform/of_platform bus model. Initialization ofinterrupt controllers is a good example, since such controllersare initialized directly from one of the platformcode hooks and do not touch the driver model at all. Anotherexample is devices that are logically described bymore than one node within the device tree. For instance,consider an audio device consisting of a node for theI2S bus and another node for the CODEC device. Inthis case, each node cannot be probed independently byseparate drivers. The platform code most likely needsto interpret the tree data to create device registrationsuseful to the device drivers.The key here is that the device tree is simply a data structure.Its sole purpose is to describe the hardware layoutand it does not dictate kernel architecture. Platform codeand device drivers are free to query any part of the treethey desire to make appropriate decisions.At this point it is worth mentioning that it can be a strongtemptation to design new device tree bindings aroundwhat is convenient for the device drivers. The problemis that what might seem like a good approach when youstart writing a device driver often turns out to be just thefirst of several bad ideas before you finish it. By keepingthe device tree design focused on hardware descriptionalone, it decouples it from the driver design and makesit easier to change the driver approach at some point inthe future. There are literally decades of Open Firmwareconventions to help you design appropriate bindings.4 Case Studies4.1 PowerPC 440 SoCsThe PowerPC 440 chip is a widely used SoC that comesin many different variations. In addition to the PPC440 core, the chip contains devices such as 16550-compatible serial ports, on-board Ethernet, PCI hostbridge, i2c, GPIO, and NAND flash controllers. Whilethe actual devices on the various flavors of the 440 aretypically identical, the quantity and location of them inthe memory map is very diverse. This lends itself quitewell to the device tree concept.In arch/ppc, each PPC 440 board had its own uniqueboard file, and described the MMIO resources for its devicesas a set of #define directives in unique headerfiles. There were some attempts to provide commoncode to share among board ports; however, the amountof code duplication across the architecture was quitelarge. A typical board file was around 200 lines of Ccode. The code base was manageable and fairly wellmaintained, but finding a fairly complete view of the interactionamong the files was at times challenging.When contrasted with the arch/powerpc port for PPC440, some of the benefits of the device tree method arequickly revealed. The average board file is around 65lines of C code. There are some boards that have no explicitboard file at all, as they simply reuse one from asimilar board. Board ports have become relatively easyto do, often taking someone familiar with device treesa relatively short time to complete base support for a

34 • A Symphony of Flavours: Using the device tree to describe embedded hardwarePowerPC 440EMAC0Memory BusMALEMAC1Figure 9: Logical EMAC/MAL connectionsboard. 3 Additionally, multiplatform support makes itpossible to have a single vmlinux binary that will runon any of the PPC 440 boards currently supported today.This was virtually impossible before device trees wereused to provide the device resources to the kernel.However, using a device tree does present unique challengesat times. Situations arise that require the introductionof new properties or using different methodsof defining the interaction between nodes. For PowerPC440, one of those cases is the MAL and EMACnodes. The MAL and EMAC combined comprise theon-board Ethernet. A simplified view of the interconnectsis shown in Figure 9.The MAL device has a number of channels for transmitand receive. These channels are what the variousEMAC instances use for their transmit and receive operations.The MAL also has 5 interrupts, but not all theseinterrupts go to a single interrupt parent. These issuesrequired some more complex concepts and new propertiesto be applied in the device tree.To solve the multiple interrupt parent problem for theMAL, an interrupt map was used. In this situation, theMAL node’s interrupt-parent property is set toitself, and the interrupts property simply lists interrupts0–5. Recall that this is possible because the representationof that property is dependent upon the node’sinterrupt-parent property, which in this case isthe MAL itself. To properly map the real interruptsto the appropriate controllers, the interrupt-mapproperty is used. In this property, each MAL-specific3 The AMCC PowerPC 440EPx Yosemite board support wascompleted in 5 hours, with the majority of the work coming fromrearranging the existing 440EPx support and adapting a new DTSfile.interrupt is mapped to its proper interrupt parent usingthe interrupt domain for that parent. Figure 10 showsthe device tree node for the MAL. Here you can see thatMAL interrupt 0 maps to UIC0 interrupt 10, and so on.MAL0: mcmal {compatible = "ibm,mcmal-440gp","ibm,mcmal";dcr-reg = ;num-tx-chans = ;num-rx-chans = ;interrupt-parent = ;interrupts = ;#interrupt-cells = ;interrupt-map = ;interrupt-map-mask = ;};EMAC0: ethernet@40000800 {device_type = "network";compatible = "ibm,emac-440gp","ibm,emac";interrupt-parent = ;interrupts = ;reg = ;local-mac-address = [000000000000];mal-device = ;mal-tx-channel = ;mal-rx-channel = ;};Figure 10: PowerPC 440 MAL and EMAC nodesYou’ll also notice in Figure 10 that there are some newMAL-specific properties introduced for the total numberof transmit and receive channels. When looking at theEMAC node in Figure 10, you will see that there arenew properties specific to the MAL as well. Namely, themal-device property is used to specify which MALthis particular EMAC connects to, pointing back to thephandle of the MAL node. The mal-tx-channeland mal-rx-channel properties are used to specifywhich channels within that MAL are used. The devicedriver for the on-board Ethernet parses these propertiesto correctly configure the MAL and EMAC devices.While this is certainly not the most complex interactionbetween devices that can be found, it does illus-

2008 Linux Symposium, Volume Two • 35trate how a more interesting setup can be accomplishedusing the device tree. For those interested in further examplesof complex setups, including multiple bridgesand unique address ranges, the arch/powerpc/boot/dts/ebony.dts file found in the kernel would be agood starting point.4.2 Linux on Xilinx Spartan and Virtex FPGA platformsXilinx has two interesting FPGA platforms which cansupport Linux. The Spartan and Virtex devices both supportthe Microblaze soft CPU that can be synthesizedwithin the FPGA fabric. In addition, some of the Virtexdevices include one or more dedicated PowerPC 405CPU cores. In both cases, the CPU is attached to peripheralswhich are synthesized inside the FPGA fabric.Changing peripheral layout is a simple matter of replacingthe bitstream file used to program the FPGA.The FPGA bitstream file is compiled from VHDL, Verilog,and system layout files by Xilinx’s Embedded DevelopmentKit tool chain. Historically, EDK also generatedan include file called xparameters.h which containsa set of #define statements that describes whatperipherals are present and how they are configured.Unfortunately, using #defines to describe the hardwarecauses the kernel to be hard coded for a particularversion of the bitstream. If the FPGA design changes,then the kernel needs to be recompiled.Just like other platforms, migrating to arch/powerpcmeans that Virtex PowerPC support must adopt the devicetree. Fortunately, the device tree model is particularlysuited to the dynamic nature of an FPGA platform.By formalizing the hardware description into the devicetree, the kernel code (and therefore the compiled image)is decoupled from the hardware design—particularlyuseful now that hardware engineers have learned software’strick of changing everything with a single line ofsource code.On the other hand, the burden of tracking changes in thehardware design is simply shifted from making changesin the source code to making changes in the device treesource file (.dts). For most embedded platforms, the.dts file is written and maintained by hand, which isnot a large burden when the hardware is stable and fewchanges are needed once it is written. The burden becomesmuch greater in the FPGA environment if everychange to the bitstream requires a manual audit of thedesign to identify device tree impacts.Fortunately, the FPGA tool chain itself provides a solution.The FPGA design files already describe the systemCPUs, buses, and peripherals in a tree structure.Since the FPGA tool chain makes significant use of theTCL language, it is possible to write a script that inspectsEDK’s internal representation of the system designand emits a well formed dts file for the currentdesign. Such a tool has been written; it is called genmhs-devtree[?] and it is in the process of being officiallyintegrated into the EDK tool chain.Figure 11 shows an example of a device tree node generatedby an instance of version 1.00.b of the opb_uartlite ipcore. As you can see, the node includesthe typical compatible, reg, and interrupt properties,but it also includes a set of properties with thexlnx, prefix. These properties are the ipcore configurationparameters extracted from the FPGA design. Thedevice tree has made it possible to provide this data tothe operating system in a simple and extensible way.RS232_Uart_1: serial@40400000 {compatible ="xlnx,opb-uartlite-1.00.b";device_type = "serial";interrupt-parent = ;interrupts = < 4 0 >;port-number = ;reg = < 40400000 10000 >;xlnx,baudrate = ;xlnx,clk-freq = ;xlnx,data-bits = ;xlnx,odd-parity = ;xlnx,use-parity = ;} ;Figure 11: node generated by gen-mhs-devtreeWith the success of the device tree for Xilinx PowerPCdesigns, Xilinx has decided to also adopt the device treemechanism for Microblaze designs. Since many of theXilinx peripherals are available for both PowerPC andMicroblaze designs anyway, it was the natural choice touse the same mechanism for describing the hardware sothat driver support can be shared by both architectures.

36 • A Symphony of Flavours: Using the device tree to describe embedded hardware5 Tradeoffs and Critique5.1 kernel sizeOne of the often-heard concerns of using the device treemethod is how much larger the kernel binary will be.The common theory is that by adding all the devicetree probing code, and any other “glue” code to makethe board-specific drivers function with the generic kernelinfrastructure, the overall vmlinux binary size willdrastically increase. Combine this with having to storethe dtb for the board and pass it in memory to the kernel,and one could see why this might be a concern forembedded targets.While it is certainly true that the size of the vmlinuxbinary does grow, the actual differences are not aslarge as one may think. Let’s examine the sizes of anarch/ppc and an arch/powerpc vmlinux binaryusing feature-equivalent kernel configs for minimal supportwith a 2.6.25-rc9 source tree. 4 Table 1 shows theresulting binary size for each arch tree.Arch Text Data BSS Totalppc 2218957 111300 82124 2412381powerpc 2226529 139564 94204 2460297Table 1: Section sizes of vmlinux binariesAs you can see, the overhead for the device tree methodin this case is approximately 47KiB. Add in the additional5KiB for the dtb file, and the total overhead for abootable kernel is approximately 52KiB.While to some this may seem like quite a bit of growthfor such a simple configuration, it is important to keep inmind that this brings in the base OpenFirmware parsingcode that would be required for any arch/powerpcport. Each device driver would have some overheadwhen compared to its arch/ppc equivalent; however,this would be a fairly small percentage overall. Thiscan be seen when examining the vmlinux size for amultiplatform arch/powerpc config file. This configbuilds a kernel that runs on 6 additional boards, withsupport for 5 additional CPU types, and adds the MTDsubsystem and OF driver. The resulting vmlinux adds4 Essentially, the kernel was configured for BOOTP autoconf usingan NFS rootfilesystem for the PowerPC 440GP Ebony evaluationboard.approximately 130 KiB of overhead when compared tothe single-board arch/ppc config. A comparison witha similar multiplatform config in arch/ppc cannot bedone, as there is no multiplatform support in that tree.5.2 Multiplatform KernelsAnother question that is often heard is “But why do Icare if I can boot one vmlinux on multiple boards?I only care about one board!” The answer to that, inshort, is that most people probably don’t care at all. Thatis particularly true of people who are building a singleembedded product that will only ever have one configuration.However, there are some benefits to having theability to create such kernels.One group that obviously benefits from this are the upstreamkernel maintainers. When changing generic codeor adding new features, it is much simpler to builda multiplatform kernel and test it across a variety ofboards than it is to build individual kernels for eachboard. This is helpful for not only the architecture maintainers,but anyone doing wider cross-arch build testing.It’s important to note that for most of the embeddedboards, there is nothing that precludes building a singleboard config. Indeed, there are approximately 35such defconfigs for the Freescale and IBM/AMCC embeddedCPUs alone. However, doing a “buildall” regressionbuild of this takes quite a long time, and themajority of it is spent building the same drivers, filesystems,and generic kernel code. By using a multiplatformdefconfig, you only need to build the common bits onceand the board-specific bits are built all together.So while not everyone agrees that multiplatform embeddedkernels are useful, the current direction is to put emphasison making sure new board ports don’t break thismodel. The hope is that it will be easier for the maintainersto adapt existing code, perform cleanups, and dobetter build test regressions.References[1] http://playground.sun.com/1275/home.html, Accessed on June 24, 2008.[2] http://www.openfirmware.org,Accessed on June 24, 2008.

[3] Benjamin Herrenschmidt, Becky Bruce, et al.http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob;f=Documentation/powerpc/booting-without-of.txt,Retrieved on June 21, 2008.2008 Linux Symposium, Volume Two • 37

38 • A Symphony of Flavours: Using the device tree to describe embedded hardware