Device Tree 101 10:00 AM UTC+1 session

all right um good morning good afternoon good evening uh thank you very much for joining this device 3101 webinar i'm really happy to see that there has been so much interest in this webinar that we are going to organizing at brooklyn in partnership with st so i'm going to introduce myself briefly i am thomas perezoni i am the chief technical officer at bootleg which i joined in 2008 i am one of the embedded linux and kennel engineers in the bootleg team and as such i have been one of the author of the device tree for dummies talk which i gave in 2013 2014 and this webinar is an attempt to be an update of that talk with more details and more content i am also one of the co-maintainer of build root an open source embedded linux build system and i have been contributing to the linux kernel with over 900 patches that have been merged into the linux kernel and this is this experience which i am sharing today in this device 3 talk i also happen to be one of the members of the program committee for the embedded linux conference both us and europe and i'm based in toulouse which is located in the south west of france so today the agenda for this webinar is first to introduce bootlen then to introduce the stm32mp1 platform and finally we'll get to the the bulk of the the topic the device tree so why do we need the device tree what is the basic syntax of the device tree what is the concept of device through inheritance what we mean by device tree specifications and bindings and what is the interaction between device 3 and linux scanner drivers and we will also discuss common device 3 properties and a number of examples and finally we will have a q a session you can ask such questions in the chat throughout the talk and one of my colleagues alex and bellony will be there to moderate the chat and the q a session so first let's introduce brooklyn we've been in business since 2004 we have an engineering team based in france but we serve customers worldwide in in fact less than 20 percent of our revenue comes from france all our other customers are in other countries in european union or outside and our expertise is highly focused we do only embedded linux work so employment schedule development bootloader development and embedded linux system integration our activities our trainings which are about 20 of our revenue and the rest are engineering projects for our customer about 80 percent of our revenue and we are an authorized partner of st since 2019. so our training offer is made of six different training courses uh covering a wide range of topics around embedded linux so we have a first course on embedded linux system developments which is an introduction to embedded linux we have a course around linux kernel driver development which dives into the linux kindle apis to develop known drivers we have a course on yokto to learn how to build embedded linux system using yocto another course around beardroot with pretty much the same idea but focused on the build root tool instead of yokto we have a course around the linux graphics stack which is a pretty complex uh stack and software stack in linux and so we have a complete course dedicated to that and finally a recent course that we announced is around boot time optimization a very important topic for many embedded linux products so why would you choose those courses why they are kind of unique first and our training materials are entirely freely available and this is quite unique there are very few training businesses in the world that do that and they usually kept their training material secret we have chosen a completely different approach which consists it's completely opening our training materials so they are available under an open source license the creative commons by asa license and this allows everyone to verify in detail the contents of the course and it shows our commitment to knowledge sharing another thing that makes us unique is that we have experienced trainers which are not just trainers they are most of the time engineers who work on real engineering projects all year round and from time to time they teach training courses and this allows them to have very up-to-date experience and in-field experience as well and our training courses are worldwide recognized we have taught hundreds of sessions all around the world to thousands of engineers for the past 15 years beyond this training activity we also have an engineering services activity which again is is the the most important part of our work and there what we do is mainly the development of bsp board support packages for our customers so we port bootloaders and the linux keynote we write linux kindle drivers we do system integration with yocto build root and deliver fully functional ready-to-use linux board support packages to our customers for their custom hardware platform we are able to upstream the changes that we make to provide long-term maintenance so we can upstream changes to u-boot to the linux kennel to yokto to build root and other open source projects as well we also offer consulting and technical support around embedded linux topics our customers are mainly silicon vendors who contract us to implement u-boot linux bluetooth or yocto support for their products and usually they ask us to also provide this work in the upstream official projects and the second category of customers are embedded system manufacturers who deliver real embedded products in various industries transportation health care entertainment home automation and many others and for those customers we provide complete bsp or specific drivers debugging optimization and consulting around embedded linux topics woodland is also a major open source contributor we are the 20th contributing company worldwide to the linux kls can be seen on the right of the slides there this is the complete list of companies who have contributed to linux since the linux project started using kit and we have contributed over 7600 patches mainly around hardware support this commitment is not just around contributing but also participating more actively and several of our engineers are maintainers of various subsystems in the linux scanner such as iqc rtc mtd and several platform support we are also a key contributor to billfoot and i am personally one of the co-maintainers and collectively at bootleg we have contributed over 5000 patches to this project we also contribute to the yokta project and we've made contributions to bearbox to u-boot to the linux test project and several open source projects as well in addition to that as i mentioned earlier our training materials are all freely available and we give numerous talks at conferences to share technical knowledge and this webinar is another example of of these contributions that we make to the open source community so with that bootleg introduction out of the way i no need to talk a little bit about the stm32mp1 platform indeed this webinar is organized in partnership with st and all the examples that we will use will be based on that platform um so st has a very strong portfolio in mcu microcontrollers that is very worldwide known and in 2019 they launched a new series of mpu so microprocessors which is called the stm32mp1 family of processors and on this slide you have the block diagram of the stm32mp157f which is one of the socs available in this stm32 mp1 family so this is kind of the the high-end one the 157f it is based around a dual core cortex a7 at 800 megahertz together with a cortex m4 which gives you the ability to run real-time applications next to a linux system running on the a7 and it has a gpu in addition to that plenty of connectivity peripherals for display so rgb interface but also dsi a camera interface hdmi gigabit ethernet can usb um ice qrc spi sdio of course and plenty of other interfaces dacs adcs pwm for motor control lots of security features so it is really a very featureful soc so this stm32mp1 family um as multiple variants of that soc and it is important to describe that as it has an impact on the district discussion that we will have later in this webinar so they have different variants as i mentioned the first one being the one five one the one five one with the kind of the lowest end of the the family it has a single core a7 um and it is available at uh 650 megahertz or 800 megahertz and in this variant there is no gpu there's no can and there's no dsi interface for display um and each of those variants is available with or without security so for example the 151a is without crypto and and secure boot functionality while the 151c is available with security the 153 is an improvement over the 151 it has the dual core a7 and it brings two can interfaces and then finally the 157 brings even more functionality in the sense that it brings the gpu and the dsi interface and each time as you can see there are two variants with without security and at 650 or 800 megahertz um together with do's soc st has put together two very nice evaluation platforms which are available at a very affordable cost there is the dk1 discovery kit 1 and the dk2 discovery kit 2. so let's start with the dk1 discovery kit one it is based on the 157a soc so it is the highest hand one but the variant without security features it has half a gigabyte of memory microsd a gigabit internet connection it has usbc for usb a connectors leds buttons it has hdmi an audio connect codec a dsi connector so that you can connect a pen a display panel it has gpio connectors which are compatible with arduino and raspberry pi shields it also has an onboard st-link so you can reflash and have access to a jtag interface without extra hardware the discovery kit 2 is kind of an improvement on top of the disc brake kit one it uses the 157c soc which brings security features and in addition to that it does a wi-fi and bluetooth chip and as you can see on the picture it has a display and touchscreen so we are on of course all the the other features that the discovery kit one had um so if we look at that discovery kit 2 platform and and as a partial block diagram this block arm is definitely not showing all the blocks that you can find but it is illustrating briefly what it looks like so at the core we have a system on chip which is this grey box it is composed of a number of ip blocks which are all those yellow boxes that are provide features such as gpio mmc i square c gpu uarts dsi crypto and many of those functionalities as well as the cpu cores blue in the middle and then around the system on chip on the board we have a variety of peripherals such as a ddr memory a display panel a pimic connected to ice core c we have a micro sd connector a wi-fi chip an ethernet phi a touchscreen controller an hdmi transceiver an audio codec and all of these peripherals on the board are connected to various ip blocks inside the system-on-chip so this brings us to progressively to the topic of device 3. indeed on hardware platforms there are typically two different type of buses there are some buses that provide what we call discover variability mechanisms mechanisms that allow the system that runs on the cpu to ask the hardware what devices are connected to the platform and what are their characteristics this is for example the case for usb or pcie on usb when you plug a webcam on your system the system doesn't have to know in advance that you will plug this model of webcam on that particular usb port indeed the usb standard in the usb bus includes enumeration mechanism discoverability mechanisms that allows your system to query the usb bus and ask the devices that are connected who they are what are their characteristics their model and and things like that and there is this concept of vendor id product id device class that exists in both usb and pci that allows an operating system to uniquely know which device is connected on the system for usb and pci buses and thanks to that an operating system can easily identify what is the driver that should be responsible for that device and how that driver can actually talk to that particular device so that's very good but unfortunately not all buses provide such discoverability mechanisms and in practice in embedded platforms many of the buses to which we connect peripherals do not support such discoverability mechanisms ice crc spi one wire memory map devices all of these devices that typically don't support discoverability so the operating system that runs on the cpu needs to know what is connected on those buses and how they are connected to the rest of the system and again those embedded systems that we work with they typically make extensive use of such buses so the question is how does the operating system get to know what is the topology of the hardware so the description that we need to provide to the operating system allows the operating system to know things like okay my system on chip is a dual a7 uh cpu it has maybe two uart controller which are uh have their registered mapped at that particular physical address uh and that are using this particular rq lines it has maybe three eyesquasi controller of that specific variant with registers at that address and that interrupt line and maybe taking a clock as input from this particular other ip block in the chip it also allows the the system to know that my board has a particular audio codec which is connected to a given ice core c bus and to a given audio interface of the system-on-chip and that it has a reset signal connected to a particular gpio of the system-on-chip all of those details they cannot be guessed by the operating system indeed we don't use um for ice core c memory mapped spi and so on we don't use buses that provide discoverability mechanisms so we need to know all of those details well ahead of time in kind of a static fashion so really there are three kind of main different ways that are um that are used or i've been used throughout the linux story to provide that sort of detail and information to the operating system these details can be encoded directly into the operating system or bootloader code using a compiled data structure in c so that was typically what was done on on arm and many other platforms in linux you would write c data structure each describing one device of the system in the system so you would write a c data structure for your first qr controller that gives the address and the interrupt lines and the clocks and so on another c data structure for the second uri controller for the third the force and similarly for every ip block in your system and in the soc but also all the peripherals around the system on chip on your on the complete board um so this was done and for mainly arm32 platforms but also other our cpu architecture but for arm 32 specifically uh around 20 10 or maybe a bit earlier and this with the the the increase of arm system on ships and platforms it really became difficult to maintain and so a different solution was um uh was identified to to solve the maintenance of this significant amount of c data structure to describe a wide amount of hardware platforms the second solution that is used is acpi tables this is a solution that is commonly used on x86 intel systems where the bios or uafi firmware provides to the operating system a set of tables acpi tables that gives details about the the hardware topology however on most intel systems a vast majority of the hardware is connected on pci or usb buses which do provide discovery mechanism and so the need to express in a static fashion the hardware is kind of less significant for those loose platforms and so what acpi tables used to allow expressing was not that flexible um so it is it has no grown in in functionality but back back 10 years ago it was less powerful than it is today that being said this is still the the common mechanism for the bios and ufi firmware on x86 systems to provide hardware description to the kennel but it is also used on a number of for example arm64 system especially the ones that are designed for the server space and the last mechanism which is going to be the top of the focus of this webinar obviously is the device stream it is a technology that already originates from open firmware something that was started years or years ago by sun uh used initially on the spark architecture then it it also was used on poor pc so there was many years before it got used on arm in linux and um this open firmware name is the reason why a number of linux you would function that you can find have an of prefix and we will see that in in some parts of that that webinar this off it doesn't stand for the the word the english word off but for open firmware even though the actual firmware that you use maybe u-boot or bearbox or some other bootloader and there is still this terminology of open firmware of that that sticks around in various places of linux and new boot and other software that uses device tree and nowadays the device tree is used for most embedded oriented cpu architectures in the kernel so arm 32 obviously but also arm 64 arc risk 5 power pc many many platform extensor mibs and i think these days if you want to add support for a new cpu architecture in linux it is actually mandatory that it uses the device stream and therefore writing or tweaking modifying a device tree is no always necessary when you want to port linux to a new board or when you want to connect additional peripherals to an existing board and that's what we're going to be discussing in this talk in this webinar so the device tree what it is at the start it is a source file called device resource or dts in short and the file extension is.tts and this source file contains a tree data structure which describes the hardware and this is written by a developer who ports linux or ubud or some other operating system or firmware to a particular piece of hardware so it has to be written by someone with knowledge of the device 3 syntax which hopefully will be you at the end of this webinar this source file is processed by the device 3 compiler dtc it's an open source project that's that's available which will compile that source form into a slightly more efficient representation called the device strip blob dtb actually most projects in addition to passing the device trees through the device street compiler they also pass the device resul through a pass of c preprocessing which allows to use like sharp defined definition to have nice human-relatable micros and things like that but the bulk of the work is actually done by the device three compiler gtc and so the resulting dtb defines three blob uh is a contains the information that accurately describe the hardware platform in an operating system agnostic way and we'll we'll talk more about that bit later to give you an order of magnitude a typical gtb is around a few dozens of kilobytes so it's not it's not huge right it's not a big data structure but it is sufficient for an operating system to understand the topology of the hardware this dtb is also sometime called fdt for flattened device tree so if a device tree that has been flattened it's no longer a tree it's flat and it's the name that we give to a dtb once it is loaded into memory and that's why you will also see a number of commands in your boot called fdt or a number of apis in new boot or linux also called ftt underscore or something something so let's have a look at a quick example um here i have just written a simple food.dts file which of course doesn't represent at all a hardware platform right it's the device 3 compiler has no understanding whatsoever of what is inside a device 3 file it is just a bunch of properties and nodes that that are within each other so this food.dts starts with a mandatory specification of the version of the device 3 language you're using and i think we're still at v1 today so that's pretty much a mandatory specification and then we have the root of the tree which starts at slash very much like the root file system and the next starts at slash here the root node starts at slash and then we have sub nodes and properties so i'm welcoming you with bad coffee i'm sorry but good coffee doesn't work in hexadecimal i would have preferred to offer you a good coffee than bad coffee but bad coffee fits in hexadecimal so we can we can add more properties and more nodes and we'll get back to to that later on obviously then we can compile this device resource with dtc we can say dtc i have an input file dash i which is a device resource and i would like to output a dtb so a device strip blob and i compile it and you can see the device p blob is just like 169 bytes here because that's a very small example once i have this dtb i can also decompile it with dtc i can say tell dtc okay my input is a dtb and i would like as output a dts and it gives me pretty much exactly the same as the dts with a few changes here and there but mostly you can recognize it's the same information so as you can see here dtc is not tied to building devices that represent hardware you can feed into dtc any arbitrary tree of nodes and properties and it will happily build them so how is this blob being used the dtb um for book loaders um like ubud or bearbox or other firmware like a tfa a hand trusted firmware the blob dtb will typically be linked directly into the code indeed at the time of um of the bootloader getting started we don't yet have access to file systems and very flexible ways of loading data so it is typically directly bundled into the bootloader binary for operating systems however it is typically passed to the operating system by the bootloader that's the most common mechanism that is used for the linux scale so for example in ubud if you want to start a linux channel from youboot on an arm32 platform the comment that is used is boot z which takes three arguments the first is the ram address at which your kindle image was loaded and you can see on the diagram on the right that your kindle image has been loaded somewhere into ram then the second argument is the address of the init ram fs which we don't use here so we specify just a dash and then the third argument is the address of the dtb and you can see again on the diagram on on the right that the dtb must have been loaded um in ram prior to that running that command so really when you start a linux scanner you need to have a memory bus the code and data of the candle but also this tiny bit of information the dtb and on arm 32 the bootloader is going to jump to the entry point of the knl code with register r2 containing the address of the dtb so this is part of the boot protocol that is enforced by the linux scale on arm 32 and this will allow the linux scanner to well get its hand on the dtb and parse it and use it of course on on other cpu architectures the boot protocol might be different but there's always this this idea of a boot protocol that allows the operating system to retrieve the device strip blob from the firmware before handing the dtb over to the operating system the bootloader can modify the dtb um unlike compile code that we can hardly modify the dtb can be patched by the by the bootloader or by the vmware and you put actually does that or bear box or must open source bootloaders the parsing of the dtb by linux or by ubud can be done by a library called libfd which is provided as part of the dtc project or simply with other code because well the the the internals of a device blob are not very complicated to parse so that's pretty much how the device free blob gets seen by the operating system know how do you get those debian street files of course you can write them from scratch but it is quite some work to describe new hardware platforms so where do we store and keep track of device resources so they are operating system agnostic so ideally they should be hosted in some kind of central and an operating system neutral project or location and this has been often discussed but never really happened so these days kind of the the most official canonical location for device resource files is the linux kernel source code um for most cpu architecture in arch name of the cpu architecture boot dts this is where you will find the device resource files and there are actually around 4 700 device resource files as of linux 5.10 and most of the other projects that use device trees they end up duplicating those devices sometimes syncing them on the regular basis within their source code so in ubud in their box in tfa so the armed trusted firmware you will also find device trees which are very often duplicated sometimes tweaked a little bit compared to the ones in the linux kernel but they are fairly similar so if we take the example of the mp157a discovery kit one platform and see which device refines get used for the different parts of its boot process and the boot process of the mp1 has multiple stages like is the case on on most system-on-chip the first stage is tfa so the which was named arm trusted firmware in the past and which is really the first stage bootloader for that platform it uses the device tree and the device tree that describes the discovery kit one is in mdt stm32mp1578 and to build uh the arm trusted firmware for that platform you need to specify plat equal stm32mp1 and as you can see this is only like the platform as a whole in the entire system on chip family and what allows the trusted firmware to really know the details of the particular board and soc you're using is the fact that you specify an extra environment variable dtb file name which says i would like to build tfa specifically for that board which is described by that device triplob at the end of the build of tfa you have a single binary tfa stm32mp157a which includes the code data of tfa but also bundles the gtb describing the discovery kit platform for u-boot we have pretty much a similar story we have a device tree which is stored in arch arm dts describing the board and and the peripherals it has and the system on ship etc we configure u-boot with a configuration that is not board specific as you can see it's just named stm32mp15 so you can use this configuration for every board using any of the mp1 system on chips and what tells you about which particular board we are going to run you put on is the device 3 environment variable that you specify at boot time thanks to that ubud will build its code and data into a uboot.stm32 binary which will also bundle the device reblock describing the platform finally for the linux scanner the story is a little bit different because we usually have the kennel image and the device tree blob separated so for this particular platform the device tree is in arch arm boot dts stm32 mp1578-dk1.dts so you can see the location in different projects is not always exactly the same but the principle is similar we can configure then the candle with the multi v7 def config which is a configuration that is supporting all arm v7 platforms so not just the one from st but the ones from many other silicon vendors as well in one single kindle image and so what allows the candle to know what platform is it runs on is the device flip flop so at the end of this build process of the channel you have a z image which contains the kindle code and data supporting a wide range of arm v7 platforms and you have a tiny device 3 blob that gives the description of the hardware to the linux scanner which is available as a separate file so how does it what it looks like when we boot um so we have u-boot that is built for this um stm platform um duboot has two environment variables that we commonly use and in this in this platform to load the candle and the device tree so we have canal addr and fdt adddrr which we respectively use to load the candle image and the device strip blob and you can see a first example of fdt being used to indicate flattened device tree which is the location where we will load the device tree blob so we load our kennel image slash boot slash z image is being loaded at kennel hddr in memory we load the device tree blob at fdt-addr also in memory of course non-overlapping areas and then we boot that using this bootsy command that i mentioned earlier passing the address of the candle in ram dash for saying we don't have an init mfs and then the device three blob and that boots the candle and you can see again the ubud telling us the flattened device tree blob is at c4000 uh booting using the fdt blob so we see this fdt technology over and over again and then it starts the channel and we can see the canal prompting us saying hey i'm linux 5.8.13 and i'm running on our arm v7 processor and we can see also very early in the boot this off open firmware fdt flattened device tree line which indicates the machine model which is a string that is in the device tree itself that identifies kind of the board on which we run once we have booted linux we can also explore the device tree directly on the target and in the csps file system which is typically mounted in slashes there is this sis firmware device three bays folder that you can see into and in there you can see a representation of the device tree where each node of the device tree is a directory and each property of the device tree is a file that you can cut to watch their values and if you have the device three compiler available on the target you can also unpack the device tree using this csfs representation by using dtc-ifs which is my input is the ccfs representation of the device tree located there and it will output you the exact same content as the dts with a few different things that are different but overall it's going to be looking very much like your initial dts and that's very nice because it allows you to check that the dt b you're using on your platform is really the one you think you have passed to the know so as a way of double checking what you're using this csfs interface is very very nice so now that we have um introduced i would say globally this device three concept let's kind of dive more precisely into the syntax of it and it's important to understand the technology that is used to be able to understand the rest of this webinar and generally the documentations that is available around device 3. so device 3 as you've heard again and again is a tree a tree made of nodes so in the diagram on the on the right you have a root node slash and it has two sub nodes which are named node at zero and node at one and these nodes can themselves have sub nodes or child nodes and the first node node at zero has two child nodes child node at zero and child node at one more or less a node is typically used to represent a device or an ip block of your hardware and then those nodes they contain properties which are kind of key value pairs so you can see different types of properties you can have properties that are associated to a string to a list of strings to a list of bytes you can have boolean properties like the first child property that you can see has no specific value it is just the fact that it is present that says this property is true and if the property is not written in the device tree it's false and also you can have properties that reference other nodes and i'm going to get back to that and those properties they typically describe the characteristics of your devices um so things like their memory address inter-appliance and all these information that we will discuss throughout this webinar those nodes they have a name which is the part before the ads so for example in node at zero node is the name of that node and they have a unit address which is the part after the add so at zero the unit address is zero and i'm going to get back to what we typically use as the unit address and what it really means later on in addition to having a name and a unit address nodes can also have a label and this is visible at the bottom of the example here where a node at 1 has a label node 1 which is before the um the colon and this label can then be used to reference this node from other places in the device tree and this is visible in the child node at zero there is a property that is kind of stupidly named a reference to something equal and the value of this property is ampersand node one this is kind of a pointer if you do c programming you can really think of it as a pointer it's a property that allows uh to say okay i would like to say i have some kind of interaction with this other node in the device tree and of course we'll see examples of that being used in in practice so what is important also to realize is that the device free compiler is only doing syntax checking right i have been able to compile see earlier my example with the stupid properties values um they are this the device 3 compiler only verifies that syntactically it is correct but it has no idea what nodes and what properties do make sense in a particular context all right so to know that we have the terminology of the device tree syntax in mind let's have a look at um kind of a top-level look of the device we then we'll dive down into into the details but to kind of get started let's have an overall look of a device tree so here i have kind of written a simplified example of the device tree for the dk2 discovery kit 2 platform and you can see on the right side um the kind of the the limited subset of ip cores and hardware parts that i will be describing that is of course not the full system on ship it has way more ip blocks and and the board has way more hardware peripherals around but well for the sake of making that fit in the slides um i'm kind of limiting myself to a subset of the hardware and so the subset of the hardware i'm going to discuss are the cpu cars dual a7 the fact that this has memory attached to the soc that we have an interrupt controller that we have a nice qrc controller that is used to communicate with an audio codec and that we have an ethernet mac connected to an internet file on the board and again this is very simplified the audio codec is obviously connected to another ip block the audio interface of the soc this is not represented here just for the sake of simplicity so on the the left side you've got the the device tree itself and i've kind of folded the the nodes to make it fit on the slides and throughout the next lines we'll progressively unfold some of those nodes to understand what's beneath those child nodes of the of the device tree so the device tree starts with the root node it has some address cells size cells properties which i'm going to be covering in detail later so i'm going to skip over that for now and then we have this top level model string this is the string that gets displayed when you boot the system that we've seen earlier in the boot example and then it has some compatible properties and i'm also going to discuss that a bit later but briefly these are identifiers that identify the system as a whole this is saying this is the discovery kit 2 platform and it is using an stm32mp157soc and then we have sub-nodes we have a sub-node for cpus for the memory we have a chosen sub-node two subnodes they are defined by the bayes device tree specification which i'm going to cover again in more detail a bit later and then we have other sub nodes which are there to describe more of the hardware itself so we have the node for the interrupt controller and then we have a node that describes the system on ship and all the ip blocks that it contains such as the ice crossing controller and the ethernet controller so let's have a look note by node at what we have in there but i think it's very important to keep in mind this this top-level view of what the device really is it is really a representation of the hardware so it is there to describe the different elements that we have in our system cpu memory ip blocks in the system on chip and peripherals on the bar so the first node that i'm unfolding is the cpus node which has two sub nodes one for each cpu saying at which frequency they run and which specific type of cpu they are so that's pretty simple but that allows the linux scanner to know okay i'm running on an smp system multi processing system so perhaps i need to bring up secondary cars i also need to know what is the frequency maybe on some other platforms there could be ways of adjusting the frequency at runtime that different way different things that the operating system needs to know about these cpus the next node is the memory node which is typically filled in by the firmware so there can be a value set for the memory node in the device resource that you've write but this is anyway going to be updated by the bootloader with the actual amount of ram that is detected so this property this node and its reg property is giving the base physical address of the ram and the size of the ram that you have again that allows linux to start managing your physical memory setting up the mmu the page tables and all these mechanisms the next subnode chosen is an interesting node because it is not a node that is there to describe hardware it is a node that is here to allow the firmware to communicate extra information to the operating system and you've got two properties there i'm going to start with the second one std out pass which is telling the operating system what kind of standard output should be used for the operating system to communicate with the user so this is typically a reference to some kind of serial part that that is the one where with that the candle will use to display the boot logs and and all those kind of messages the other one boot args which is empty there is going to be filled in by the firmware and it will contain the linux kindle command line so this is where you pass things like root equal slash dev mmc blk 0 p3 to indicate where your root phone system is for example so this is specified in the bootloader vmware which needs to pass it to the candle and this is this information passing is done by patching the dtb at the bootloader level so that the canon receives the candle command line from the slash chosen slash bootrx property moving on the next um part is the interrupt controller node which for some reason in this um device tree has been put outside of the soc node i'm not exactly sure why that choice was made but i mean it works to do it that way so this is a node that describes one of the ip block of the system this stm32 mp1 system on chip uses the geek interrupt controller from arm and it describes where its registers are and different informations about it um also the soc node has an intraparent property that reference it i'm gonna talk more about that later but this is an example of this p handle and label mechanism the interrupt controller node its name is interrupt dash controller its unit address is a002100 and it has a label which is intc and this label is used below in the soc node which has an intraparent property which says ampersand in c this is a p handle a pointer that references to the interpret controller using this nc label continuing the next ip block is the iscsi controller so of course the system on chip has multiple of them but i'm only showing one i score c um the squashy controller which has registers at four zero zero one two zero zero zero which is again the unit address of that node the name is ice core c and it has a label which is called i score c1 number of properties in there and obviously we'll get into the details of those properties but what is really important there is that as a sub node we have a description of what is connected to this i square c controller and as you can see on the right side this green box connected to the ice crease controller is the audio codec a cs so i think it's a service logic 42l51 audio codec it is described as a sub-node of the ascrising controller so we've got a node cs42l518 at 4a which describes that audio codec moving on to the ethernet controller we have a node that describes the ethernet controller itself so the ip block in the system-on-chip and as a sub-node we have here something a little bit more complex where we have a representation of the mdio bus so for those not too familiar with um with earthen and mac and files the mdio bus is the bus that allows the control bus that allows the mac to communicate with the fine for like control signaling it's not the data but just the control and this mdio bus has a sub node to represent the ethernet phi itself so the ethernet file at zero is the node that represents the file and it gives an address to that file which happens to be address zero on the mdio bus so thanks to that information the k9 can know okay there is an internet controller and it has an mdio bus controller which connects me to an internet fi at this specific address which the candle wouldn't be able to guess by itself so that gives kind of the top-level view of what the the type of information the device tree contains and how it is overall organized these device tree source files they are not monolithic you don't write you typically don't write a single huge dts that describe your entire board and all the peripherals of your soc because that would be like overwhelming and also between two different boards that use the same system on chip well the description of all the hardware blocks inside the system on ship would be the same so repeating the description over and over again in different source files would be stupid and not very nice from a software engineering point of view so we do something better which is devised through inheritance or inclusion but i like better to refer to it as inheritance so what we can do in fact is split our device three source files into multiple files we can have dtsi files device three source include which contains some common information that is going to be used by multiple platforms and then we have dts files device resource which includes one or several of those dtsi files and only dts files are accepted as input to dtc but they can include an arbitrary number of other dtsi files and so typically we use very heavily dtsi files to contain information such as describing the soc and all the hardware blocks that it contains because that information is going to be used for multiple boards using that system on chip or we also use dtsi to store common informations that are shared between boards that are quite similar but not exactly the same and we will have this example with the dk1 and dk2 because they are really really similar and they share a lot of common aspects they have just a few minor differences and so this mechanism of sharing hardware description information is used to describe the dk1 and dk2 and then the gts would typically contain kind of the board level information that is really specific to your custom hardware platform and this inclusion mechanism works by overlaying the tree of the including file over the tree of the included file so we've got file a and this file a gets included by file b then whatever file b defines will take precedence over what file a defines and we'll have plenty of examples of that so that will allow file b to override things that are defined by file a if need be and this inclusion works by using the c preprocessor sharp include directive so in fact what happens is that when you build your device 3 it gets passed to the c preprocessor you will have multiple trees next to one after the other starting with slash the root node and the device free compiler will kind of fold that entirely and make sure that whatever comes last is kind of the one that has the ability of overriding what comes first let's have a look at examples to make that openly clear and this is a simplified example um the actual gtsi and dts for the stm32 mp1 platforms are more complicated than shown here and and some of the next slide will will show that but this is enough to illustrate the mechanism so we will in many situations have a device three file that describes the system on chip that the one that you the you have on the left of the picture defined definition of the stm32 mp157a soc stored in a file called stm32mp157 again device resource include and in there we have plenty of definition but i've only kept one uh which is the the some part of the definition of the ice crease controller so it defines that the system on chip has some kind of ice cream controller with certain registers certain interrupts and a status that is disabled which means this is ip block is not used this device resource include gets included by the file that is shown in the middle of the picture which describes the discovery kit one platform so this is a dts file describing being a physical board that includes that system on ship as well as peripherals around and those peripherals around there is an audio codec connected on this ice core sequence number one so what we do is that we extend this node this is c1 node with additional properties that describe various things pin maxing we're going to get back later it describes a sub node which describes the audio codec and it also describes the status property and you can see there is kind of a conflict here right because the status property of that same node is described both on the gtsi and in the dts but because the dts comes last it's the one that will win so on the right side of the picture you can see what looks like the compiled dtb of course in real the dtb is binary format so this is more kind of the decompiled version of the gtb if you wish and it gets really the combination of boss information so the final i square c one node that's the operating system will see is the combination of the properties defined in the dtsi and in the dts so that it fully describes the hardware all right so to do this overriding of properties and an extension of of existing nodes with more properties there are two different ways of doing that the first way which was illustrated on the slide before and again here is that you replicate in the dts the hierarchy of nodes that go all the way down to the property you would like to override so let's take the example that we have here we have slash soc and then a serial at 5c000 node which has a property called status this is in the dtsi now in the dts we would like to really enable this uart controller so what we do is we replicate that semi-r key slash soc serial at five c zero zero zero and we say status equal okay this is going to override that status property so that the final dtb has this node with status okay so this is one way of doing of referring to which property of which node we would like to override but we can also do it to achieve exactly the same thing with a different syntax which is no more commonly used and so in the dtsi we have exactly the same and you've noticed that this serial ad5c000 node also has a label useart1 well in the dts we can leverage this label using this syntax and percent use r1 outside of any tree outside of we don't need to be inside slash and and curly brackets just outside of any tree the fact that we use this syntax and person user one says what properties we're specifying there should override whatever properties are inside the node whose level is use art one and again this is no kind of the most preferred solution um kind of in the history of linux kindle of of the device tree i think the the solution to the left was initially the most commonly used one and over time uh people found that that the solution on the right was a bit lighter in in what you need to write a bit more compact and so the one that is the most popular these days is the one you've got on the right so now that we have seen this concept of device tree inheritance let's have a look in practice at how this is used in the linux kernel to represent the stm32 mp1 hardware and as you can see on the picture it's not that simple right there are plenty of funds involved so i think it's it makes sense spending a bit of time um describing what's going on there first we have divided this picture in two parts the top part which is they are separated by the dashed line in the middle the top part of the picture describes this information the bottom part of the picture below this dashed line describes the board level information so i'm going to start with the soc level information at the top on the left side we have a first dtsi which doesn't include any other file which is kind of why i'm starting there it's kind of the start of the story um it's called stm32mp151.dtsi if you remember this table at the beginning of our discussion when i introduced the stm32 mp1 family the 151 is kind of the low end of the the family it has a single core a7 and it has i would say the base set of purple which is already plentiful but it's the one that has the least amount of peripherals so this dtsi file describes this single a7 the cortex m4 and all the base peripherals that are common to all socs in this family then the the next dtsi file stm32mp153 which is just right below is including this 151 because the 153 soc is the same as the 151 plus extra peripherals so we are including the description of the 151 and saying okay the 153 in addition to what the one five on provides also provides a second cortex a7 and two can interfaces so if you look at that 153.dtsi it is not very long because it only includes the 151 and describes one additional cpu and two can interfaces then the story continues with the one five seven which is again a super set of the one five three so it includes one five three but in addition to what the one five three has it has a gpu and a dsi interface for display so it has just two extra nodes in addition to what the 153 was providing then continuing on the soc definition there is the stm32mp1 the dtsi which describes just the crypto block there is a crypto engine in in this soc but if you remember again the presentation of the um the soc family for each soc 151 153 157 there is one version with security and one without security and the one without security doesn't have the crypto engine and so there is a separate device 35 that describes just a crypto engine all right then we have a device profile called stm32mp15-pin control which describes pin maxing configurations that are common to all socs all system-on-chips and we're going to get back to pmoxing later in this discussion then we have on the right side we have extra definition for pin control that depends on the package type that is used indeed there are different packages of physical packages like bga packages that are available for the different system on ships that that provides a different set of pins to the outside world so there is some functionality that is not completely available if you have a two reduced package and so this describes which gpios and which pins are exactly available depending on which package you're using then at the bottom of the picture we have at the center this stm32mp which is a device tree that contains the definitions common to both the discovery kit 1 and the discovery kit 2 platforms indeed as we say they share a lot of commonalities so it makes sense to group that into a single dtsi and finally we have the gts file and i'm no seeing that my diagram is incorrect um not enough review i guess the stm32157a dk1 and dk2 files are dts not dtsi as written in the slides so please excuse me for that mistake we'll fix that up when publishing the slides so these are really dts files and this is quite critical in the explanation these are really the files that you will build with the device free compiler so what starting with the one to the left dk1 what it does is it includes the 157 dtsi file indeed this board is using the 157 soc so i'm including it so that my hardware description describes all the peripherals inside the system on chip then i'm also getting the definition from stm32 mp15 pin control to get all these pin mixing rated configuration that we will discuss later and i'm getting the pin control definition specific to the particular package uh of the the chip that i'm using so it happens to be that the ac package is used on on that particular board and finally i'm including the 15xx dkx dtsi which again is describing the common aspect between the two boards and in addition to that there will be some definitions maybe specific to the dk1 going to the right of the picture describing the dk2 we have a fairly similar story but you can see there is an extra um file being included the 15xc indeed the dk1 is using the a variant of the 157 which doesn't have security so it doesn't have the crypto engine the dk2 board is using the 157c variant of the system-on-chip which has security features so it does have the crypto engine so the description of the dk2 is also including this stm32mp15xc dtsi which allows well the hardware description to also describe the crypto engine and hello auto linux scale and and maybe the book loader and other things to to use it as well and so that's how multiple dtsi files gets all combined together to finally produce a complete and accurate description of our discovery kit one and this correct two platforms so the device stream um has a bunch of design principles of what we put inside the device stream it is there to describe hardware like how the hardware is not configuration not how i choose to use the hardware and this is quite important um and because there are there has been lots of discussions over the years on what sort of information we want to encode in the device tree and what information don't want to encode and because it needs to be operating system agnostic and use case agnostic we don't want to know what is your particular use case or what is your particular configuration of the hardware we want the device free to just accurately and very objectively describe what is the hardware there is this audio codec it is connected to this guy square c bus this is something we can physically see by looking at the schematics this is an objective view of the hardware this goes into the define stream however if you're using this audio codec in in i don't know this mode or this other mode it is maybe your choice for your particular application and this is not a description of the hardware and so it does not belong in a device stream as i mentioned the device 3 should be operating system agnostic the device 3 is used by linux but also by ubud by freebsd by the trusted firmware by bearbox and other projects so there normally shouldn't be os specific details in the device tree also the device tree should describe the integration of the hardware components and not the internal details of those hardware components as we've seen in the various examples what we're describing is we have a nice crazy controller and it's connected to an audio codec for example or a touchscreen controller so we described how they are connected together it is on this particular bus maybe the audio codec has a reset gpio and it is connected to this audio interface of the system on chip this is how components are connected together but we don't describe the inside of those components so we're not going to describe i don't know the list of registers of your um of your audio codec in the device tree at which offset and with bit mask they have and so on this doesn't fit in the device tree because this is the internal details of controlling the audio codec and not the description of the uh the integra integration interaction between the different components of course like all beautiful design principles these principles are sometimes violated we find sometimes things that are not completely hardware description sometimes things that are not completely os agnostic sometimes things that are that go a little bit beyond that describing the hardware integration and interaction but still design principles are there to kind of give a guideline sometimes we deviate a bit from the guideline but that gives a kind of a good direction where to go so how do we know what to write in the device tree what nodes and what properties exist and which one should i use for a given hardware platform and the first foundational document that we have are the device free specifications they're available on devicetree.org and they define really um what is a device tree what are the top level nodes what they should contain a number of common properties so this is a very important body of documentation but this is not sufficient to describe the wide variety of hardware that we have right this spec is not updated every time a new order codec shows up every time a new soc shows up every time a new ip block shows up so this device respect is really kind of foundation and on top of that foundation we have what we call device tree bindings which are documents that each specify our given piece of hardware should be described in the device tree so whenever a new piece of hardware gets supported by newboot or linux or something like that we have to also contribute um a device three binding document that indicates what are the properties that are expected what are the possible values of those properties to describe a given piece of hardware so you contribute a new audio codec driver you contribute c code but you also contribute a device tree binding document that gives details on what is the proper device through presentation for this audio codec these bindings um very much like the linux kindle source code serves as kind of the reference canonical location for device 3 files the device free bindings are also located today in the linux kernel source code so if you go in documentation device 3 bindings in your favorite linux kl3 you will find all the device stream binding documents and there are plenty of them these bindings are reviewed by a team of candle maintainers who kind of ensure that they the bindings that you submit comply with the general guidelines of the device pre-design principles that i illustrated before and as of today we have two formats for documenting device tree bindings the legacy way which is kind of a human readable document and the new norm which are yaml written specification so let's have a look at a couple of examples for the old style where it was just a text format human readable document i took the example of an iep from st but this ip is not used on the stm 32 mp1 simply because on stm32 mp1 they have converted all the device bindings to the new format they are good open source citizens so they've done this job already but i still wanted to illustrate this old binding format that you can still find for other peripherals and other devices um so as you can see this is really just human-readable text right it says what are the required properties compatible rank address sales size cells interrupts clock rate and what other properties and what you should put in them so this is really important if you have one of those ip blocks thanks to that document you know which properties need to be used they are optional properties so you can have them or not and then on the right side you've got an example that shows how usually this device tree binding gets used in a particular device 3 file the problem with this format is that it is nice for humans it is nicely readable but it is not machine possible and as i mentioned before dtc only does syntax checking it only verifies that overall the syntax of your device will make sense but it doesn't have the knowledge of which nodes which property makes sense in a particular context and which values are are correct for a particular property and this is something that the known developers and generally the device free community wanted to improve on and a key to make that possible is to have machine-passable device-to-binding documentations and so that's why nowadays device bindings are written in yaml it's a very popular data representation format it makes the device binding may be a little bit less nice for human beings to read but it makes it machine parsable which means we can have tooling to validate device 3 and i'm going to get back to that so in this ml file we can find pretty much the same information as in the previous text file which properties are available what values are possible how many of values are possible for the different properties which properties are required and so on and it also has examples to again make it kind of easier to get a feeling on on how to use a particular device representation for a given piece of hardware um again dtc does only syntax syntax validation and thanks to yaml bindings we can do semantic validation for example if you have a piece of device tree that uses a compatible string of st comma stm32mp15-i score c we know that this binding applies and so we can check that you have all the required properties that they have correct value and and so on and this is integrated in the linux keynote build system at least possibly in in others as well but that looks in the next scale it's well integrated there is a dt binding check which is validating the binding themselves it's just validating that the yaml file is is correct yaml and that it can be parsed and that it makes sense and then there is a dtbs check rule that you can use as part of the keynote build system that will validate the device three files that describe the platforms that you have selected against the bindings you can also reduce the scope of that validation to just one ml file that maybe you are writing your busy writing you don't want to do the full validation of the entire world you want to validate again a single binding you can also do that as well with dt schema files so this is extract tooling um and and um this is a very active area of development right the bindings are progressively converted to yaml and the tooling is is being improved and so on so this is kind of a maybe not new but still in very active development area of device redevelopment so now it's time to look at actual properties of the device stream and the first property that we're going to discuss and is probably the most important one is the compatible property this compatible property it is a list of string from the most specific to the less specific and it describes the specific binding to which the node complies so it's going to be the identifier to know what this node is representing as a hardware platform and so which device free binding you rely on to represent this particular piece of hardware and the device through spec says that it uniquely identifies the programming model of the device so if you've got a piece of hardware block it has a bunch of register maybe offset 0 4 12 8 12 16 etc and those registers they have bit films that have certain meaning to control the ip block well this is the programming model of the device right this is what defines how you are going to work with that specific hardware block and practically speaking this compatible string is used by the operating system to identify the appropriate driver for the device indeed given a certain programming model a certain set of registers on a set of bit fields that have a certain effect on the hardware block you write a corresponding driver that uses that programming model to do whatever needs to be done with the device so that compatible string is going to be the key to associate a node in the device tree with a driver in the linux scale or a new boot or in barebox and when it describes real hardware the typical form of a compatible string is vendor comma model of the hardware and you've got plenty of examples below like arm coma arm v7 timer is the compatible string to describe the timer from arm found in many arm b7 platforms and this is string is found in device 3 files and in the driver for the arm v7 timer the second example is interesting because it has two entries in this compatible list again i said earlier in the slide from the more specific to the less specific this allows depending on the capability of the operating system to have maybe better support for an extra functionality that a given hardware block is providing compared to a less efficient version of the same hardware block so in that case it is saying okay this is the ethernet mac from designware that is bundled into the stm32mp1 but i mean if you don't have the actual support for this um if you just support snps designware mac 4.20 a it should do fine as well so the linux kernel and generally other opening systems they will match against the first compatible string and see if there is a driver that is available and if they don't find any and they will try with the second compatible string the two last compatible strings they don't have this vendor command model because they are not really tied to a specific honda model for example the first one describes a fixed regulator so this is here to just say okay my hardware has a fixed voltage line that provides maybe 5 volt or 3.3 volt or something like that so it's not really something that comes from a given manufacturer it's just to express that in your in your hardware you've got some um an input voltage at a given um given voltage level a gpio keys is a driver of linux that allows to turn a gpio into a keyboard with just with just one key and so again this is not this kind of a specific piece of hardware from a given vendor it's just an abstraction of the kernel that allows to take one gpio and turn it into a regular keyboard input device there's a special value for a compatible simple bus which indicates that all the sub nodes are memory mapped devices and we're going to see that in the next example so in in linux and this compatible string is again used to identify the corresponding driver so when you take a device string all the top level nodes that have a compatible string and all the sub nodes of simple bus will be turned by the linux scanner at good time into platform devices so if you look at the example on the right side timer is a top level node with a compatible string you are at one thousand and ice cream c at 2000 are child nodes of simple buzz so when the kl boots up gets this gtb from the bootloader parses it it will identify do three notes and we'll say okay i'm going to create a platform device corresponding to each of those nodes then for the subnodes of i square c controllers the linux scale is going to create ice corset devices for sub node of spi controller is going to create ice spi devices and then each driver in the kennel has a table of compatible strings it supports which is a table of of device id entries and when a node in the device tree matches one of the entry in that table then they are kind of bind together right and we have a device we have a driver and it turns out that this device matches what the driver is capable of managing so we kind of bind them together and this way the driver knows okay i'm no taking care of that particular device first example the stm32 ui controller driver it a registers into the kennel a platform driver structure which in inside it as an of match table um property or a member i should say because that's c code which points to this stm32 match table at the beginning of the example and you can see it matches three different compatible string so if there is a node in the device tree that matches one of those three values then this node and the platform device that gets created based on that information will be tied with that platform driver and the probe function of that driver is going to be called as a result of that and of course we can have like four different nodes in the device tree with the same compatible string calling four times the probe function of this driver because we have four different ui controllers in that um in that particular piece of hardware another example uh just to illustrate with another type of bus that the logic is exactly the same the audio codec that we have on the discovery kit platforms is on ice core c so we have a nice question driver this size quasi driver has an of match table and again you can see this off terminology it stands for open firmware which points to cs42l51of match that we have at the top of the the picture and this one supports just one compatible string which is cirrus-cs42l51 so again when an ice core c device in the device tree is encountered and it has a compatible string series comma cs42l51 um and it will be kind of tied with this driver and the pro function of the driver will be called the next property that is important is reg it's probably the most important after compatible it is used for different types of devices but it has different meanings depending on the type of device that you're describing for memory map devices it contains the base physical address and size of the memory map registers and it can have several entries for multiple register areas so here is an extract from the sound interface of the uh mp1 uh it has two register areas uh one that starts as a five zero zero two seven zero zero zero for just the size of four bytes so just one register and there's another one at five zero zero two seven three f zero which is 16 bytes in length for i square c devices this reg property has a different meaning it's same property but different meaning it provides the address of the device on the ice core c bus so in this case there's only one entry um which is there which is the the square c address of the device for spi devices it is the um chip select number so here is an example of the quad spy interface on on the mp1 that on one given board is used to connect to two different flashes and connected to the same quad spike controller but using two different chip selects tip select zero chip select one and the right property indicates which chip select is being used um the unit address which is the part after the add in in the node name must match the address of the first reg entry so if you scroll back in the different examples i had before like here at zero it is kind of matching with reg equals zero at one matching with reg equal one or here at five zero zero two seven zero zero zero is matching the first reg property um then i need to introduce the concept of cells integral values in device tree are represented as 32-bit integers called sales so on the right side of the slides this property called foo is a property that contains just one cell the value dead beef which could have been bad cafe or something like that so if you want to encode a 64-bit value you really need two cells here we have dead beef and bad caffeine and they are properties that indicate how many sales are expected in various other properties so for example the address sales and size sales property and this sharp at the beginning is not making them comments um it is perhaps not very clear on on the diagram which puts them in in green but they are not comments they are actual properties just their name happens to start with a sharp that says number of address cells equal one number of sensors equal one so what these two properties mean is they indicate the number of cells that are used in the right property of child nodes right so here in the soc node we have address cells one size cells one so it means that in every child node of that soc node we want the right property to have one cell to indicate the address of a memory map area and one cell to indicate the size of that area and indeed in ice quality at f100 1000 we have a rank property with one cell for the address one cell for the size and then we are overriding these values saying for my own child nodes the address cell is no one and the size cell is zero indeed i am a nice grassy controller and the child nodes of me will not be memory mapped devices but ice core c devices and for ice quartz devices the right property has just one entry one cell which indicates the address of the device we have this similar concept with many other things like interrupt and we will get back to interrupt examples in in a moment like here we say this interrupt controller says interrupt sales equal to which means that any nodes that refer to that interrupt controller needs to use two cells in its interrupt property and indeed you can see the i square c at f 1 0 0 1 000 node it has an interrupt property with two cells 12 24 that's two cells which matches what the interrupt controller node expects and we have that for clock cells gpio cells phi cells pwm cells dma cells and and so on another property that is key but much more simple is status which we've already encountered it tells if the device is really in use or not so it can be okay or okay which means the device is really in use and any other value but by convention we use disabled then the device is not in used and basically in linux it controls if a device is instantiated or not so when the the canal kind of parses through your dtb if a given node has status disabled and the canal kind of skips it and doesn't even instantiate a device for it so it will not be used a device that has status okay will really be used and there will be an instance of that device which hopefully will be tied to a driver thanks to the compatible string so what happens is that in most dtsi files that describe socs most of the peripherals and devices are defined with status disabled and it is on a poor pair board basis that we are going to say okay on my particular board i am using ice creases controller one and five so i enable those two ones but i leave all the other ones not enabled because i don't use them that's the idea of that property interrupts so we have nodes describing interrupt controllers um the top level node on the right side describes an intro controller which is the geek from r and it says i need three cells to describe interrupts i am an encrypt controller which is defined by this boolean property interrupt dash controller and because this is a hardware block it has registers and then uh below we've got two devices that are connected to this interrupt controller they have interrupt lines that go to this interrupt controller and we describe again this integration between hardware blocks in the system-on-chip and to describe which interrupt given device is using we have two different ways we can use interrupts and interrupt parent or we can use interpret extended so interrupts specifies the interrupt that we need to use and it has three cells right matching the number of interrupt cells here the cells are geek spy which is kind of the type of interrupt 36 the number of the interplay and rq type level high which says okay this interrupt is like happening at the high level um and the information that tells the system to which interpret controller this interrupt belongs is the intrapreneur property and it doesn't have to be filled in for every device because the um the canal paris is recursively the parents of the current node so in this specific case the soc node says intraparent equal ampersand nc so it's a p handle pointing to the interrupt controller node and this statement says for all the nodes below that unless they override this information every interrupt property is going to be referring to that particular interrupt controller the interrupts extended um property um is kind of a improved way i would say which combines the two information you can see in the example of the mailbox so that's a mailbox that is used on on mp1 to for example communicate between the cortex a7 and the cortex m4 it has different interrupts two of them are from the geek which is repented by the nc label but another one is from another intro controller called xi which i couldn't represent on the on the slide for uh due to the lack of space but that's another interrupt controller so this property allows to provide boss which interrupt controller and which interrupt we are using for a particular hardware device and this stories goes on and on for many other resources clocks dmas reset lines and so on and so on the right side i took an example of an spi controller on the mp1 it has a property called clocks which refers to rcc which is a node at the top of the slide which is the clock controller of the mp1 and it says the spi controller is using the clock named spi 3 underscore k this spi controller also has a reset line of course internal to the system on chip right we are inside the chip not not around on the board but there are reset signals and this reset signal is also controlled by the rcc which i think is something like resets and clock control or something like that and so we say my reset signal is controlled by rcc and it is the reset line of reset signal spy 3 underscore r and also as a spy controller i can use dma channels from a separate dma controller so there is a node dma max1 which describes a dma controller and the dma's property of the spy controller at the bottom of the picture is saying okay i can use channel 61 and 62 of that dma controller with those particular flags and and for additional information you can see again sharp dma cells equal three so whenever we make a reference to that particular dma controller we need to specify three cells in those references so that's why we have 61 ox 400 and ox5 so this model is is really repeated for many other type of resources you can find that for gpios for regulators or many other resources that you're present in the device tree another thing that you will often find are dash names properties which are associated to a corresponding type of resources like interrupts and trip names clocks clock names you can find reset reset names dma dma names and what these properties do is they simply give a name to the different resources so for example in here the interrupts you can say okay interrupt zero for that device is zero fifty nine zero and interrupt one is zero seventy zero or maybe a bit more humanitable you can use say okay the mac rq and the mac pmt encrypt and that allows the driver for example to query okay what is the interrupt mac rq what is the interrupt mac pmt so it really just associates a name to one of the different resources used by that specific hardware block another part that is often confusing in the device tree is pin boxing and and their description in dt so for most modern socs including the mp1 we have more features in the soc than we have pins to expose those features to the outside world and due to that we use pin maxing which is a pretty simple technique that consists in saying okay a given pin that goes outside of the the processor package can be used either for a function or another function or another function but it's kind of mutually exclusive and this is illustrated on on the right side where we have two pins that go outside of our package and for example the first pin can either be used as a gpio or as the rx line of a ui controller or as the mizo signal of an spi controller or as the clock line of a nice question controller but it cannot do several of those functions at the same time and there's a specific hardware block in the system on chip that controls this mixing so this is software configurable most of the time and therefore the device stream is here to describe which pin configurations are possible and which one you use in practice in your board um to well use the the features uh inside the system on chip that you need to use on mp1 it looks like this in the dtsi we have two nodes pin control and pin control z that describes two pinmax controllers so for different reasons instead of being just the single drivers they were separated um the first one pin control is the the biggest one it is the one that supports most of the pins and as you can see as sub note it has all the banks of gpio gpio bank a b c d e f and i think it has a bunch of others the last one pin control z is only controlling a smaller bank of gpio and um so this is in the dtsi file and then we've got um another file that gives the definition of the pin mixing configurations that are possible so this is just a small part of that file it is much longer than that but for example the first part i square c one pins a is showing one possible configuration to get the ice crossing controller one signals outside of the chip and it is configuring for example pin t the survey d12 in function af5 and pin f15 in function af15 and to read that correctly you need the datasheet and the if you look at d12 this is visible in that in that table pd12 and if you look to column named af5 for pd2l it's matching it's giving the function i score c1 scl so it means that if you configure the pin maxing uh for that pin to say i would like function number five then the the pad of your soc pd12 will allow you to use the clock of the ice crested controller one so this is exactly what this configuration is describing is saying i would like pd12 to be configured to give me access to the clock signal of that icecrossing controller so this is just uh defining this possible configuration then you need to say i would like to use that configuration and this is done uh usually at the board level because that's at the board level that you say okay the ice cream c1 signals are coming out of those two different pins on on the um on the processor and so you refer to the pin control configuration using pin control 0 pin control 1 pin control x properties you can see pin control 0 is equal to i square c1 pins a this is the label of the ice core scene sqrc one pins a node that we see in this dtsi file and this is going to tell the canal when you bring up the driver for this accuracy controller you need to configure the pins in that particular state the 0 1 pin control 0 pin controller 1 they define mutually exclusive states for the pins and pin control names is giving names to different states so here we have two states default and sleep and when the kernel driver is initialized automatically the default state is is set is is configured so it's going to be ice core c1 pins a but then the driver can on its own decision decide to switch to different different states the pins and here the motivation for using different pin states is that when the platform goes into suspend into a low power mode we need to reconfigure the pins to reduce the power consumption of the platform and this is what the sleep state allows to do it's a different configuration for those pins and the driver when the platform is going to go into low power state will select the sleep state instead of the default and when the platform comes back from a low power state it will restore the default configuration for the pins we'll conclude that um that webinar was a very simple example of connecting an led and a nice question device to the discovery kit one platform just to kind of show in practice how this device stream knowledge can be used so to start we're gonna create our own dts which is stm32mp157adk1-custom.dts and we're simply making it you include the dk1.dts which is already available in the upstream linux channel then we modify arch arm boot dts make file to ask the linux kindle build system to also build this dds into a dtb this is it is this make file that tells depending on which platform is um is selected in the length scanner configuration which dtbs are going to be produced so just next to the dk1 dtb we add our dk1 custom dtp and then if we build the kernel or simply just rebuild the device 3 using make dtbs we can see the kernel build system invoking the device 3 compiler dtc to produce dk1 custom of course at this point because this custom file is only including dk1.dts using one or the other doesn't make any difference right so you can try that out boots with dk1-custom you will see the exact same result as if you were using dk1.dts now if you want to add an led um what we're going to do first we need to see how to connect it and this is in an extract from the datasheet for the board it says that connectors cn14 which are at the back of the board they are the arduino connectors um pin three of that connector um is in fact the signal pe1 of the system-on-chip so on the left side i am adding an extra node in the device tree called leds which uses a linux kindle driver called gpio leds hence the compatible string and this driver is instantiating one led for each subnode of that node and it gives a name to each of those nodes so the the label here is webinar for my led and i'm saying i'm using the gpio of bank e number one and it's active high and then by just doing this i put my candle and it shows in 6 class leds that the gpio led drivers of the next scale has recognized my new device i have a new folder cis class leds webinar and i can control my led like writing 255 into the brightness file will light up my led as can be seen on the picture another example connecting a nice qrc sensor i have this small bme 280 i think it's a temperature humidity and pressure sensor and i would like to connect it to the uh dk1 platform again i look in the datasheet of the board and in one of those arduino connectors cn13 pins 9 and 10 allow me to get access to the iscsi 5 data nsc 5 clock signals so i am going to take that information into my device tree on the left side i'm going to say the ice core c5 controller i extend that node i enable it status okay specify a frequency of operation 100 kilohertz then the pin maxing configuration for default state and slip state and those pin boxing configuration they were already defined in the mp1 device free files so i didn't have to do it by myself and then as a sub-node i describe the sensor itself which is a sensor that already has a driver in the linux kernel that driver uses the bosch coma bme 280 compatible string and i provide its slave ice cream address as direct property which is ox 76 with that done i build my device tree i boot and i go into the shell and this bosch bme 280 is part of the iio subsystem in the linux kennel which is used for industrial input output devices and so if i go into sysbus iio i can find an in-temp input file which i can simply cat and find out it's 24 degrees that's not actually the temperature i know it isn't too loose but it's it's an example and and of course you can also access the humidity measurements the pressure measurements and so on so that really is five well six seven lines of divine stream showing how you can describe an an additional ice cream device connected to your dk1 platform if you want more details on that specific example i have a much more detailed blog post which is linked there which describes the entire process for doing this and this blog post is in fact part of a larger series of blog posts that we've wrote and that describes how to build step by step an embedded linux system for the mp1 platform using bill root from the basics all the way up to having a qt5 application running on the target receiving measurements from a nice courses sensor doing remote updates of the system and so on so i encourage you if you're interested to take a look at that series of blog posts it was long in fact longer than expected but in fact there's more there's lots of other device free topics that we couldn't cover in the time that we had the range property for example for address translation is a more advanced topic there are more complex device tree bindings for audio display camera devices where multiple nodes of the device tree connect to each other to describe a pipeline of of devices we could have discussed the linux kindle api for uh querying the device stream which are used in kernel drivers we could have looked at the ubud tooling for manipulating the device tree there is an fdt common in ubud that you can use to print modify the device tree before ending it over to the know we could have talked about device free overlays and plenty other topics but again it's already been an hour and 45 minutes so we get to put an end to this to this webinar i've put together a list of resources the device pre-specs the device three bindings and my former device tree for dummies talk for a different perspective on the device tree there is a very good page on the linux wiki on device 3 with plenty of resources and also on the illness wiki there is a nice page that references all the talks that were given in the past on device 3 topics so very good source for getting more detailed information on this on this topic so to conclude on the device stream it's a representation of non-discoverable hardware so you will typically not describe your usb and pci devices in the device stream but everything else that is non-disk variable it's a tree of nodes with properties we have standardization of the device three contents based on the device tree binding and it's overall a new description language that has lots of properties sometimes complex bindings so it's definitely something you want to learn for people jumping into the mpedible next well but it's used in numerous cpu architectures and it's basically widely used today for linux but also outside of linux as we've seen with uboot and the arm trusted firmware so it's definitely a must know for all embedded linux developers and i kind of hope that this webinar will have helped you um get the basic knowledge that you need to start working with the device 3 or a better understanding if you've already started playing with device trees to conclude about bootleg i just want to make sure you keep in mind that we are a company providing consulting services having expertise in embedded linux we have trainings and services including trainings that are available online and we have trainings coming up next month registration is open so feel free to check that out we also have engineering services we can help you and your companies or customers put embedded linux into your custom hardware or solve problems and help you in solving those problems we heavily contribute to open source and i think this webinar is another example the slides are all available under creative commons license so don't hesitate to contact us if you want to get in touch and i also want to thank a lot st for supporting the organization of this webinar and i think we are now ready for taking a bunch of questions so i'm gonna switch the scene to something else and hopefully get the um the questions in front of me so just give me a moment all right so let's see what sort of questions do we have here um so there there is a kind of a latency between you and my answers so i'm gonna see if there are a few questions coming up on the chat i don't immediately see any but hopefully there will be a bunch i see there's been lots of discussion in the chat i say thank you so yeah i'm glad i hope that was been useful any um questions or maybe um there's been questions before i'm just picking up some random question can the peripheral be turned off through dt um i would not really well it depends on what you think right there is this there is this status property which is there to statically say this device is not present um so this really it doesn't really turn off the device in this in in the runtime sense of of of um of things right it just says this device doesn't exist at all so the kennel has not even any notion that this device might exist if you're rather talking about turning on and off devices at runtime for example to save power then the device three is not there at all for that there are other mechanisms in linux to to achieve that kind of of logic the device tree is only here to describe um hardware so the piece of android is there whether at some point you would like that hardware to be on or off is is not something that is part of the hardware description let's scroll down and see um and so remaining question was about one dtb per boot stage and why this was needed now so indeed we have seen that tfa is using device stream then your boot is using the device tree and then linux scanner is using the device stream so why is this needed first because every stage needs some information about the hardware right your tfa wants to output some messages on the serial console so it needs to know which uart controller to use at what addresses is available the ur controller so even something really early in the boot chain needs to have some basic view of the hardware it might be a less complex and less complete view than what the linux scale needs i would say typically your firmware most likely doesn't need to know about your camera and display and things like that um so it can do with probably a simpler and reduced view of the hardware but nevertheless it does need to know details about the hardware similarly your u-boot is capable of doing networking loading from sd card from emmc from then flash so it needs to know what your hardware looks like so every piece of the boot chain needs to have a representation of of the hardware topology now perhaps the the other question that can come up is why do we have a duplication of that device through in those different projects and as i mentioned i think this is something that has been often discussed in the community kind of splitting out the device refines from the kennel into some central um us neutral project but that has never happened so far but that would be uh would be nice um is there a reason dt isn't popular on microcontroller architecture as zephyr use it so i was going to bring up that zephyr uses it i'm not sure why it's not so popular on microcontroller architecture maybe because on microcontroller the mindset is is perhaps a bit less on reusability right the point of dt is to create a bootloader or a kernel that is relatively hardware independent and it is the device tree that feeds in the hardware topology to the operating system and i think in most microcontroller applications you have a much more like tight coupling between the application and the hardware itself so it's not such a big deal to have hardware specific details creeping all the way up to the applications i i'd say something like that um when building you boot and linux for an embedded linux platform does the device tree for you boot overrides the device tree for linux um so i would say no um viewport is using its own device stream and linux is using its own u-boot is able to uh override patch adjust the device three that will be passed to linux but not based on on the the device tree that you boot itself is using right you can use device 3a for you boot and then pass a device 3b to the next scale of course they have to be kind of to make sense right for the particular hardware platform you run on but there is no relationship or no direct relationship between the device tree that you boot is using for its own business and the device three that you are passing over to the linux kernel and in fact there are a platform where ubud is not even using the device 3 for its own business but is capable of passing a device three to the linux scanner um is the bootloader using the dtp in any way except just passing it to the kernel so yes in if the ubud is on the platform that uses the device tree for hardware description then the bootloader will use it exactly for the same purpose as the keynote does to understand the topology of your hardware as i've mentioned your bootloader interacts with you over the ceiling part it is able to load data over an sd card or through over an emmc over the network and to provide those capabilities it knows it needs to know a lot of details about your hardware and these details are provided by the device tree it used to be provided in hardcoded c data structures and it is still the case on some platforms in ubud but for most of the more modern arm socs which stm32mp1 is part of um leveraging the device tree even at the u-boot level is possible but it is quite distinct from whether it is used by the canal or not right you can have again a platform where the k9 uses the device tree but not ubud or you can have a platform where both the kindle and you would use the device tree for each for their own business is there a kind of standard for device binding for a class of devices as for example ice crescent control as far as the nursing and dev mining must have deep knowledge of the dev driver um so when you write the binding you typically do so in parallel to writing the driver is generally the the developer of the driver that also defines what information needs to be present in the device stream binding and will therefore write the binding as well um i don't think there is really a kind of standard binding but they are often common properties uh which are shared so if you look at ml files for ice creasing controllers they will include a common ice core c ml which defines very common properties for example the clock dash frequency property in ice crossing controllers is a standardized property that describes at which frequency this isc bus will operate um so and and this is also the case for other subsystems other type of buses that define standard properties which um the the bindings for specific controllers are kind of forced to use in a way i mean if you kind of reinvent clock frequency but name it frequency dash clock and you pass your binding through the review of the device tree binding maintainer they will probably reject it and ask you to use this standard property so yes there is some kind of standardization happening i would say and what happens if we describe a peripheral that doesn't exist on your soc in the dts and use the obtained dtb on your machine well um it's gonna depend right the driver will be probed and it will try to talk to that device and so what happens is it depends really if it's a memory map device and the driver attempts to to ride to a location that really doesn't exist then you might get a kindle panic um right if it's a nice corset device and the there is nothing at that ice cream address then the driver will try to talk to the device will fail and simply probably will fail initialize and will continue booting so i'd say it kind of depends is there any relationship between device pre and yokto well i would say is an embedded linux build system so it's an integration tool that is capable of building the different software components of your embedded linux systems um buzzybugs your c library your toolchain qt volcano your bootloader so as such there is kind of a relationship because youtube is capable of building linux or building new boots including the device defines that they might contain but there is no i would say direct relationship between between the two how can we easily know the modification ban done by you boot in the fdtt passed through the kennel that is a good question and in fact the the cis class firmware entry that you have in systemfs on linux is for that very nice because it allows you to see exactly the fdt that linux has has seen at boot time right including the modification that could have been made by uboot so this is really important to debug maybe the the slide differences that might be between that might exist between the dtb that you pass to your boot and the actual is that the linux kernel has seen um so could you give us more details about slip pin control um is it used by linux directly to save power so the depending on the system on chip you're using the pinmux configuration can be adjusted to save power so this is really depending on your system on chip i'm not exactly sure on the mp1 what the sleep state of those pins is is exactly um doing but it's it's ensuring that there are less current leakage through speed generally and what the canal will do is that when you go into suspend and so enter a low power state for all the drivers the candle

Channel: Bootlin

Views: 3,808

Rating: 5 out of 5

Keywords:

Id: a9CZ1Uk3OYQ

Length: 114min 59sec (6899 seconds)

Published: Wed Feb 10 2021