 Welcome to the device tree boff, ELC 2018 version. I'm Frank Carone, I'm one of the device tree maintainers in the Linux kernel. And I'm here to hear from you guys. Not so much to give slides. So I do have a lot of slides. My normal methodology is to have about 150 slides for a 50-minute slot. And I think I have 30 or 40 slides before I get to the end slide, and then like another 20 or 30 backup slides. So if you guys have no questions, I can talk. But really, this is all about you guys. The agenda for today is, first of all, I'm going to collect a list of questions or areas of concern and not address them right away, hopefully. There are a few things that I do want to talk about, but knowing how many questions are coming will tell me whether I should be just going really fast through what I have and glossing over it, or whether I should spend more time and talking more detail. And they actually come back and answer your questions and have you guys say things. If you don't have something added to the list to begin with, don't worry about it, we can always add it in through. So like I was saying, just trying to get a sense of how much you guys have, how much time you all want to take up versus what I take up. I will be talking about what's happened recently, what I see coming in terms of conferences as events. That's nice and short. A little bit about what's been going on, not just in the kernel, but also in the tools area, like the device tree compiler area. And then like I said, back to the questions. So right away, let's get started. If people have areas of concern or questions they want to ask, just to get a list of those just real quickly. Anybody want to jump up? Yes. Just a simple question to start off. I've kind of dug into this, trying to find, hey, for my device, for my system, I need to implement this device. What is a good, where's a good place to look for, hey, this is the documentation. If you're going to implement a new device, this is how you should do it. Because I've just been working off examples and sometimes examples don't match. I don't know the real theory behind it. Got it. Okay, and actually, you did find there, not to dishear or anything, but at this point you don't actually need to ask the whole question just more. Give me a real quick subject area, just so it gets on the list, and then we'll ask the whole detailed question later. Yeah, go ahead. So I recently started working on ARM. I was an exitist earlier. So one of the things which I found while compiling my device tree code was it gave me errors and warnings, but they were not really helpful to find what exactly had done wrong. Okay, so that's the device tree compiler for the device resource. Okay, so error message from DTC. Yeah, it's not really helpful in my opinion to help out find what actually went wrong, and it took me a little while to figure out that. Okay, let's go and get that. Next, back here. I want to talk about, or hear about overlays and overlays management. Okay. How people handle fragments and stuff like that. Okay, so overlays and overlay management. Yeah, I do have some slides on overlays and there is some new stuff that's often a very hot topic. So we'll definitely talk about overlays. There's something further back. Different device tree source formats. Okay. You're thinking potentially YAML. Okay, got that. You don't get to talk back there. Overlay removal and removal in an order that is not the stack order. Okay. Okay, next. Yeah, so negative values or integers for hardware ranges. What's the general, let's say, field or acceptance? Negative values for negative numbers for property values. Okay. Licensing of included DT bindings. Now we suddenly got SPDX identifiers all over the place and before there was no explicit license. Okay. Okay, yeah. So licensing of device resource files. Okay. I would like to hear something about upstreaming support for custom boards. Okay. Let me get that down. Hold on. Almost there. Okay, next one. Device tree and UIO devices. Okay. Okay, so at this point, I know I have enough UIO devices. I know I have enough content, comments and questions that I will go really fast through my stuff and come back and try and spend almost all of our time on your comments and questions. So that's exactly what I need. I've got plenty to do. And we'll come back and click more questions as we get there. So starting just real fast what's happened the last year for conferences and events. There was no session at Plumbers last year because there wasn't enough people interested in it at the time. Last year at ELC Europe, there was a full day event organized by Grant, and this is the crowd that was there. Just in summary, there were four main topic areas. Validation tools was really one of the driving forces for Grant to put the conference together. Runtime usage was a big topic area. Maintenance issues and then a whole bunch of miscellaneous things. The main thing I want to point out here is that on elinux.org there actually is really good documentation of this workshop. There were notes taken by individuals plus notes taken I think in a group effort. Grant does have an audio recording of the entire event if anyone wants it from him but it's a very large file. So I encourage you to go to this website if you're interested in what happened last year. There was a lot of discussion, a lot of areas and that's to give you a sense. There really were a ton of specific sessions listed there. Plumbers this year, we are having a session in Vancouver. If you're at Plumbers, please come and join us. Whether you're coming to Plumbers or not coming to Plumbers, if you have topics that you want discussed in the group, please let us know. Send emails to me and just let me know that you want to get the topic on to the agenda. The agenda is already published but it's fluid. We really are welcoming changing it to deal with whatever the current hot topics are. We're not wedded to our current schedule. This is old news just to remind everyone we no longer are using the ePAPR is our reference source backing up our bindings. We're using the device tree specification. The device tree specification was created by taking the appropriate material out of the ePAPR and excluding chapters that didn't really apply and a little bit of wordsmithing but essentially it's the same document and it's intended to define and provide more bindings information in the central location but it's been really quiet over the last year. Very little progress has been made on modifying this document. A little bit of history on things that have happened the last year technically. The device tree project is separate from the Linux kernel. We actually import their content into the Linux kernel on a periodic basis. Basically whenever Rob thinks there's been a sufficient amount of change or there's a feature out there that we really want to pull in. So if there's a feature out in that project that you're waiting for and you really want it and you're watching and Rob's not doing a poll just speak up and say you'd really like to get a more current version and it does happen fairly frequently already. So just a quick overview and again I'll try and be real fast because I know you guys have lots of questions. Going on the last year answering part of your question about alternative source formats for device trees there is now an option to output in YAML format and that's intended to be used by other automation tools to invalidation. There is no input option for YAML only output at this point. There is a new Python library that's seen a lot of patches and a lot of features added this year and that library is focused at the binary flatten device tree is... I'm pretty sure. I may send the name LibFDT I myself have never used the library so I've not been paying attention to it other than noting lots of commits going into it. There have been a lot of questions and concerns about sizes of device trees both the flattened image on disk or in other storage media and in the bootloaders and in the kernel the actual memory used by them so there are a lot of people trying to reduce how big the device trees are the binaries that we're dealing with one thing that's been implemented is a switch on the compiler to exclude nodes that are not actually referenced so if you have a device resource with a lot of nodes but you have no p-handle references into a bunch of those nodes they can get essentially left out of the compiled device tree so that features in there overlays we used to have to specify a lot of the metadata of what an overlay looks like in the device resource file the compiler's been modified what we'll be calling the syntactic sugar so you can at a very high level I'll give examples later essentially give the compiler enough knowledge that it knows that the nodes you're talking about are overlay nodes and you don't have to provide all that extra metadata surrounding it so that makes the device tree sources a lot cleaner finally there's a new tool that Pantelis wrote this year it's called FDT overlay and the concept behind it is if you have a base a compiled base device tree and you have one or more compiled overlays if you want to apply those overlays to the base device tree and have your output be yet another flattened device tree, the binary you can do that so that's at a build time essentially so you're not waiting until you get to the boot loader or to the kernel you're actually creating a merged device tree out of all the pieces I have not played with this at all I haven't looked at it I'm not sure how evolved it is we pull the source into the Linux kernel we don't build it yet so I think it needs a good bit of auditing since it's so new before we actually enable it in the kernel tree just to make sure how solid it is and one potential concern I have and this is a theoretical concern since I haven't looked at it is there's a lot more flexibility before you boot the system to apply an overlay than there is once the kernel is booted and you're trying to apply an overlay to a live tree just for an example when you when the kernel boots various subsystems will take a look at the device tree and they'll create their data structures and get a sense of what the system is all about if you apply an overlay later that impacts the system's view on the world it's a lot more complex for the subsystem to add that extra knowledge in after the fact than it is for it to do it when it was first booting if you apply your overlay before the kernel even sees it that whole problem just disappears the kernel has no idea that you've applied an overlay and all the subsystems just see the whole big picture from the very beginning because of that difference there are some restrictions on what an overlay that gets applied at runtime can look like it's not quite as wide open as what you can do before a boot so there may be some differences between what this tool and what the boot loaders allow when applying an overlay versus what the kernel will allow at a runtime overlay so that's one issue we just need to be aware of when developing an overlay it may not actually apply in all cases you may actually have to have more restrictive rules at runtime overlay application one thing to be aware of when you're building your source device resources especially if you're a couple of kernel versions back Rob has been very busily adding additional compile time checks and this goes a little bit toward the one comment about the compiler error message can be really cryptic so this is one thing that Rob's been doing to make things a little bit more clear and catch issues a little bit earlier in the build process instead of at the boot time just to give you a sense this is what's gone in since February of last year these are the actual commits so just a ton of new checks so if you're on an old kernel version and you jump forward three or four kernel versions you're going to start seeing a whole lot more warnings when you compile your advisory source potentially so just be aware that those are coming and you might want to when you're planning to jump ahead try and compile with a newer device compiler and work out those warnings ahead of time save yourself some effort overlays oh boy one good thing Uboot has added a lot of support for applying an overlay at boot time I'm not real familiar with it so I can't speak to it authoritatively I can simply say that's a really good alternative to doing a runtime overlay application and I highly suggest looking into that if it's one of your alternatives if you have overlays validation has been going on for years now and it's been moving in fits and starts and not making a lot of progress until this year and Rob has been doing a lot of work on this recently there are patches on the kernel mail list I'm sorry I'm jumping ahead to a different subject this is my patches I've had a lot of concerns about memory leaks from overlays overlays being applied and removed and I thought it would be a good idea to add some validation into the kernel that would try and catch memory leak issues a second major concern I have is pointers referencing data after the memory has been freed and this doesn't deal with that at all this is only dealing with memory leaks I'm going to give you some examples of messages that come out now the messages may change before it gets into the real mainline kernel because the patches are still under development but this will give you a good sense of what's going on if you are using FPGAs and using overlays with FPGAs you will start getting these messages as soon as these patches are accepted into the kernel when you're running against those kernels Alan Toll has been testing them and he's seeing the warnings he found one real problem there was a patch code where there was a mismatch between and the reference counting counts and he already has a patch out to deal with that so it's already been useful the thing I didn't expect was the kernel has some broken code in the device tree core code and this pointed out a bunch of problems and I have patches in the same series now dealing with a lot of those issues and I wouldn't be surprised if there's still some more issues to be found there is the famous out of tree overlay loader which is still being maintained Geert you're maintaining it right forward porting it every release do you publish that somewhere where people see it can grab it okay so it's a branch in Geert's renaissance repository so even though we're not supporting it in mainline if you want to try and follow along and not get too far behind in your kernels just watch what he's doing and he keeps testing as I keep changing the core APIs so that's one good thing in making sure that this code will keep working hopefully moving forward and hopefully we make things continue to work cleanly so here are some examples of warnings and errors and I'm not going to go into any detail at all on these as to why the warning error comes out from a given device tree we can come back and talk about this if we have time at the end or catch me later I'll be glad to talk about this in the hallway these are just examples typically it's warning that either there potentially will be a memory leak when the overlay gets removed so these messages are coming out in this case when the overlay is applied there are messages when the removal occurs which is that third message it's detecting it's gotten to a point in the removal process it expected the ref count to come down to one it's going to get decremented one more time and we're going to free the memory it turns out the ref count was too high still and I'll tell you how high it is where not enough OF node puts are happening the OF node gets and puts are out of balance and this will at least tell you which nodes are at issue and which ones you're going to have a memory leak because of there's some cases of we can create a flattened device tree overlay that will not apply cleanly and in the current kernels you apply it you get errors warning about name collisions and the apply code ends up renaming the property or the node so that's the symptom you see today this is the underlying what's going to catch it and I've created a test case so I understand at least one way to create this problem in the source code so we're starting to get an understanding of why that can happen but at least I have to check so I'm catching the fact that you're going to end up with a corrupt data structure in the kernel and refusing to load the overlay in that case and if you look in my patches or in my slides after the fact these are device tree overlay sources that I've added to the unit tests that show examples of how you can get to those problem areas and finally there's one error code which you cannot cause with your device resource in your overlay it means something's wrong in our internal core code so that's something that we have to deal with one issue I've talked about in the past is metadata and if you're familiar with overlays you'll understand this if you don't know overlays don't worry this is only 30 seconds you'll know that there are fragments there's an underscore symbols node underscore fixups underscore local fixups and if you have metadata you shouldn't have to deal with that's something the compiler should deal with something that the overlay loader should deal with and I was concerned about the amount of space that all of that metadata was taking up in the compiled device trees and so I decided it was going to be a good idea to change the format of the flatten device tree or the dot DTB and I sent out a patch series of this year David Gibson came back with some good ideas I think the end result might be a merge of some of his ideas and some of my ideas but those threads died really quickly we didn't get much engagement and somebody needs to pick this up again hopefully I will pick it up it is one of the plumber's topics if we get enough people talking there is a side effect of going to a new format we can actually gain some new features one feature I don't list here is potentially deleting a node we can't delete nodes and overlays because there is nothing in the format that allows us to do that in the current binary format one thing that I really like is that we will be able to take a blob and decompile it and regain all of our symbolic information all of our p-handle values as not just as integers all of the labels put back into the source code simple matter of programming I am assuming that we will modify the DTC compiler to actually include that in decompiling because it is so obvious that once we have that in the format it is such a useful feature if nobody else does it I will be twisting arms to make that happen there is going to be a lot of overhead here is an example of overhead the green line, the top line is how much how many bytes are used for the overlay metadata for a given device tree I looked at all of the ARM device trees in the kernel so just think of them the horizontal axis device tree number one was some device tree who knows who it was and for everything there are close to a thousand device trees that I compiled and measured this data for so each of these points on the graph is for one device tree once I have compiled with symbolic information what is the overhead and with the current format that is the top green line with the proposed format that I gave in my patches I saved a lot of space and that was the lower line you can see there is a significant amount of space saved by going to a new format and that is just the tabular version these are the things that that metadata is talking about if you have been dealing with overlays you have been having to hand code this stuff it is time to quit hand coding this stuff we have the support in the compiler you don't need to worry about all that extra complexity all that confusion the first time I saw this stuff I was like what the heck is going on it took me a long time to wrap my head around it the metadata part or what is in color up here so the fragment node the nodes that begin with an underscore all those go away so if we take this overlay source and replace all that meta stuff with the new syntax all that stuff this color is going to change to one line which is simply a p-handle reference that is all you need now in the new syntax you don't need to worry about how does that get converted into metadata so it is a lot cleaner a lot easier to code a lot easier to understand question does this then generate all the same nodes as before or is there a binary change in the format at this point it creates exactly the same binary format in the end if we I say if it really better be when if we switch to a new binary format then the same exact source should compile to either the current format or the new format and my expectation is that we are going to have to have a compile switch or a command line switch on the compiler it is going to be either please use the new format or please use the old format one might be the default who knows but we are going to have to support the old format for a long time I don't see any way that we can just do an overnight cut over so that is my expectation I am pretty sure David will agree with that there is going to be a long switch over period another question is that the answer ok so I think I am coming from are people actually going to start fixing the issues of the system on module and baseball combinations that keep coming up right because I think this is a good solution for that at the moment I build six different device trees for like three baseboards and two different modules right so that is the issue where the cpu module is not the base system so for most of us our base system includes the processor and the add-on boards are IO boards and the problem that he is alluding to so our baseboard probably is where your device tree is contained in ROM or disk or wherever but with the system on module all of a sudden your baseboard no longer knows what processor is going to go on it and what the device tree should look like it is going to be the add-on processor module that knows and it doesn't typically have storage for the device tree so that is the underlying problem I think I can add to that if you use the device tree overlays in U-boot then you can probably detect the configuration of the combo system and combine the SoC device tree and the baseboard device tree maybe add-on card device trees together and then pass it to Linux and that is one of the beauties of U-boot having gained this capability to add overlays in so quick question is there a trick to access the root node in this over-level? you are jumping ahead for me just a couple more slides on this so this is simply saying given the old version versus the new version this is the diff between what the old format looked like in the new format, not much and here is this question what if your original base device tree doesn't have the labels that you need for the overlay and the second part of that was we had a solution for that but even then the solution was that you could specify a path for the target going back a slide at the very top you will see target path that is where the node or the overlay gets plugged in to the base device tree so even though we could put a path in there we couldn't put a path of for some reason I think we couldn't put the root path in there pardon? we do have a solution we are good now we can go with this new syntax instead of actually putting a p-handle label as to where your overlay is going to get applied you have this new syntax of ampersand open brace and then the actual path and then close brace and that will actually work for slash as well as for any other path in the device tree so we actually have a solution now the device tree compiler that is in the kernel the mailing kernel already has the support in it so it was really good getting that added in yeah slightly related question to that example so the overlay format allows to like fill in the add the information to a particular p-handle in the tree as well as fill in a p-handle in some property when it's being referenced so is there also some mechanism for actually filling in the like string path to the node hmm I think the answer is going to be no there you have to know where the node is going to be applied independently so essentially you are going to be doing your own fix up on that that's a good question it would be useful for example adding aliases make sure I get this captured correctly at the end of the session because that's an interesting thing I hadn't thought about okay I'll have to top my head I'll have to think about that I have a slightly related question asking for a friend if you have a device tree with properties containing p-handles to some sort of node in that device tree and you want to use a DTO to remove that node my brain just got lost, I'll start at the beginning again you have a device tree full of some sort of properties which have a p-handle to a single node in that device tree and you want to apply an overlay which will remove that node and replace it with some other node can you do that somehow think of reserved memory nodes so the new node will have the same name as the old node that's your example it may not necessarily have the same name if it has a different name but you can still reference it with the p-handle so in the base device tree it will be kind of nameless like memory at zero and you want to overlay it with memory at something else because it's a reserved memory node yeah right now there's nothing that will do that that's going to be a new a new need to capture again make sure I write that down at the end at least capture it let me real fast we're running short of time even I'm trying to go fast and I'll try and jump over okay the last thing that I wanted to capture was there's a lot that needs to be done to make overlays work for the generic case I know that overlays have been working for years and single point cases on lots of boards for lots of people and your use case may work but as I discovered in our core infrastructure when I started looking at validation just because it works on one board doesn't mean it's going to work on any other board and that's one reason we've not allowed the overlay loader into mainline yet we want to have a nice solid foundation before that happens so this web page is where I've started capturing things that I think are issues and before we have entire full run time overlay support in the kernel most are all these need to be dealt with some are more important than others and we can start phasing in partial support for overlays before they're all dealt with and already we have FPGA support in the kernel using overlays and they have some ways of working around some of these issues or ways that we can audit carefully when stuff is added I think we'll be able to add overlay applies with only part of that list dealt with but removal still will not work at all so we just won't allow removals so we'll just phase in as quickly as we can in the full support but there are things that need to get fixed so follow on elinux.org and if you have other things that you know are problems let me know I was just wondering if with some of the memory problems being addressed if you would consider maybe throwing something like Garrett's current version into staging and just more people use stuff we see what breaks and then makes it easier to figure out what to fix yeah basically I don't want the overlay anywhere near to where it could accidentally fall into mainline usage and being in staging that to me it's anybody can use it at that point even if we know there are problems with it people can use it and we have to deal with all of the broken parts of the code at that point so I'd be happy to try and make sure gear's been doing a great job and I don't know if you'd be willing to put something on your plate make sure that there's something that's well documented of with each release we will try or expect to have a new version of the loader following closely or maybe someone else can jump up and take that responsibility but I think it would be good to have that code easily added to anybody's kernel so that people can be doing that testing I myself would like to have a reference board that's running mainline kernel supporting overlays that I can be running the overlay loader on so that's a challenge give me your address I'll send you one awesome okay yeah yeah so anybody who's running boards on old kernels and out of tree stuff try to get your support at least booting and serial console on the mainline kernel yeah so I have a whole list of questions can be prioritized information on how to implement a device that was basically a driver question more than device tree source file or was also how to use structure the source file yeah yeah that's a major whole in our current documentation I would like to point to elinux.org device tree I've been trying to document things there when you see holes in that please speak up and say hey Frank please add that documentation or hey Frank I'll document that for you but yeah that is a known problem we don't have an answer for that question right now we don't have that documentation yeah I feel like I think I'm doing this right you know yeah next one your messages from DTC are not helpful that's incredibly true we're out of time and you've been presenting the whole time instead of answering questions yeah that's what I'm trying to go through the questions I would actually like to ask a sort of fundamental question to the room here how many people here maintain out of tree device trees so you have derivative designs that are in the kernel yeah I think that's something we ignore a little bit too often something we need to keep in mind right so do you want to add more of those trees into the kernel source no I think it's a fundamental thing that people will have devices that are not in mainline and by the fact that we have device tree we've actually set up to make it with the very intention that people should be able to do that yeah and I'm making it incredibly hard for them yeah I actually would encourage people to make those out of tree device trees out of tree device trees more visible no they shouldn't have to that's fine if they don't want to show it fine but if they're going to be useful to other people it'd be nice if other people can find them and maybe we should be setting up a central repository that can just point to where these are so people can find them well if you want those to be publicly visible don't be shy to send them to us we'll take them no problem with that but if you don't want to send them that's fine too and we need to be aware of people not being able to do that maybe for a long time depending on what they're doing in house oh yeah yeah absolutely and I think the expectation is for the in kernel device device trees that some people didn't seem to want to put all of them in the kernel source they just kind of wanted the references in there in the minor variations they didn't want to create all the churn that used to be in there with board files I don't do bindings well the device tree source files kind of live more in the binding half of the world I'm not a maintainer of that section so Rob Herring is the person to really bring that up with but yeah he's not here yeah I'll add to that if you submit your device trees for upstream inclusion the feedback may take a while to arrive back and it may be a little difficult to handle maybe we should do something about that yeah if anyone wants to become a reviewer of bindings and source device please please jump up we don't have nearly enough people working in that area so the questions overlays and overlay management I'm going to dodge for a minute different dt source format I'm definitely going to dodge Merrick overlay removal especially not in stack order that becomes a technical question right now the documentation says that they have to be removed in stack order this is for the runtime linux kernel overlays the reality is when I got to that code that's not what it really did and I cleaned it up a little bit the current check is when you're trying to remove an overlay does it reference any node that another overlay deeper down the stack had created or modified so it's a little bit more liberal but it's still pretty tight I'm not sure how loose we can get on that when you start getting multiple overlays modifying the same data for a driver typically when we remove an overlay to do it cleanly you're going to need to unload the driver to start with so to do things out of order you may have to back things out unload a lot of drivers and then re-forward apply overlays I'm not sure if that's the answer but if that's an important need in order definitely bring it up and start looking at possible ways to deal with it, possible solutions negative numbers for property values that's a bindings question I'm going to dodge that one ask it on the list licensing of device tree source files the device tree source files have always been by default GPL they are sourced in the linux kernel tree we have a lot of dual licensed device tree source files people have been adding the spdx actually meant include dt bindings oh include dt bindings apparently they didn't have a license before but when Greg did the big sweep they got a spdx license in gpl 2.0 because that's the default so you're talking not dtsi files but the include like gig underscore which is a really simple one that apparently is gpl 2.0 only right so the idea is that you want those to be dual licensed last week somebody asked to re-license it but there are probably lots of other files like that the interesting thing about those files are those files are used by both drivers and by the device tree source files talk to the authors if an author is willing to dual license their header file I don't think there's objection to that is anyone else objections to that just in general in the kernel we have had a big push from making the dts files bsd license or mit license and I think that's a good thing in order to be able to reuse them across non-gpl kernels especially the bsd kernels it's completely useless if the header files are different right so it's a sensible request to try and chase those down I don't know what might get in the way of that we certainly have to see what the authors are most of those files are extremely trivial and usually only have one author so it shouldn't be too big a deal and maybe we should be adding that to the source file policies and the bindings policies that we request that you dual license so we should be talking to Rob about that device tree and UIO come talk to me afterwards that's interesting I think I've gotten through all the pre-questions more questions flowing officially we are over four minutes ago there's a break right now and Tim wants to steal the room I'll be here this evening if you want to catch me I'll be at plumbers thank you all for coming