 Welcome everybody. My name is Darren Hart and I work for Intel's open source technology center. I work primarily on the Yachto project But today I'm going to be talking about how not to write x86 platform drivers I'm a core kernel guy by I Guess experience mostly I spent about seven years at IBM doing some real-time Linux work schedule or work if you saw a recent announcement about the Latest zoom Walt Destroyer with Raytheon in the US Navy that was some work. I was involved in for a while It's kind of coming to fruition. It's kind of neat to see but that was all core core stuff So a few Texas real-time Locking primitives and now with the minnow board that I was involved in I started doing some driver work So this is a bit of a different talk for me. So rather than talking about something that I've been doing for a decade I'm going to talk to you about something I've been doing for six months and some of you in here are probably more of an expert in specific things that I'll be talking about that I am so I welcome your input and very interested to see where this goes so I'm going to talk about some of the mistakes that I made and Some of the approaches that work better and also some of the gaps that we have in the current technologies and where We're looking to get those improved so we've got a few folks in the audience that I know of that have been involved with minnow as well and Just to help me get an idea for Who's composing the room? How many of you have written a Linux kernel driver? Okay, so next door they're talking Wow, that's great Okay, that actually answers my question. We'll just we'll just go forward then So this is what we're going to talk about today I want to talk about the term platform a little bit and then we're going to go in specifically to using the minnow board as an example for how not to write x86 drivers platform drivers specifically We'll go once we've gone through the initial phase We'll talk about the lessons that can be learned from that process and then we'll do it again the right way And then as I said, there's a few next steps few gaps. We'll go over those Throughout this discussion If you have questions, please raise your hand. We've got 50 minutes. I've got 35 slides. I Did 55 slides at the last ELCE and 45 minutes, so I think we'll be okay But I'm more interested in the feedback and the discussion. So please feel free to raise your hand It's probably best that we use the mic because it's here, but if it's awkward for you to get there I will repeat the question So first of all platform This has got to be the most singly overloaded term in the Linux kernel and industry that I've come across in a decade So out of curiosity What is platform do you want to want to offer up definition Tim? Yeah, right platform. All right anyone else it's actually a really good definition Tongue-in-cheek, but also very good So platform defines a lot of things platform can be a computer architecture. So we hear PC compatible. That's a platform It's a software framework and OS application framework at Intel. Of course Intel has to redefine everything So Intel ease me for a platform is the combination of a CPU and the chipset Of course, we're doing so sees now. So it's kind of the chipset in the CPU. So it could be the SOC or anyway Linux platform driver. So what is a platform driver a platform driver within Linux doesn't even mean one thing? So there's two plot two kinds of platform drivers in the Linux kernel You've got pseudo bus drivers and I'll refer to them this way But this is the actual documented if you go into documentation and read about platform drivers This is what we mean. We're talking about not a real bus This is something that gets enumerated separately from PCI USB But then there's also Drivers platform slash architecture slash all the stuff that really shouldn't exist at all board files So that's another definition. So we're going to call those pseudo bus drivers and board files rather than platform drivers and platform drivers Some other examples of platforms PC BIOS UEFI Android Just a little bit of room for confusion in this term. So we're going to be talking about platform drivers today And it's kind of a mix of all of these things but primarily the ones we don't want to write our board files And the ones we should be writing our pseudo bus drivers, but there's a lot more to it than that which we'll get into Okay, so the minnow board. Let's talk about why this got us here. There's a minnow board up here It's probably not very visible to everybody. Hopefully people can see those little green lights because those are going to come in to play during the discussion The minnow board is Kind of unique it is to my knowledge one of the first Completely open designs for an atom CPU of the current current set of generations The the board is built by circuit co a lot of design work by David Anders David Albert The rest of the team there at circuit co with fame with the Beagle board and some of those other popular community boards The the Gerber files the schematics all the hardware Design for the board is released under the creative commons license All the parts are available through distributors So you can literally download the designs order all the parts build your own board You can duplicate the design The the minnow board is a little different than some other designs out there just for conceptual awareness For folks is this is one of those things that can be a little confusing But the minnow board has derivative works as one of its primary goals What that means is you can download all this stuff make tweaks rebuild the board into whatever you want it to be Matter of fact circuit co will do that happily for you So that's the minnow board It is an atom e6 xx. It's called a tunnel Creek design It uses the the CP. It's a two-chip solution currently So it uses the the e6 xx CPU and the e g20 t which is the the pch which adds some additional The nick the GPIO a few other components like that to enhance the platform And then together as I mentioned earlier tunnel Creek plus top cliff equals Queens Bay Which Intel calls a platform Queens Bay is the platform. We're talking about building on top of so some Properties of the minnow board. It's 32 bit UEFI. It's one of the first Queens Bay platforms to make use of all of its GPIO So this is one of the things that actually was quite a bit of work for us to get this thing going So despite the fact that Queens Bay had all these GPIOs in the past hadn't actually really been used on on a platform in this way the UART is a little bit special on every release of this platform and The the ethernet itself This was interesting We ended up using a fi that was not quite as common in some of the original Intel designs Which threw us for a few loops that we had to fix up in the software So that's these are some of the problems that we're going to address but more fundamentally to the minnow board And this is this is where it deviates from a lot of Intel architecture designs that are out there today most Intel designs that I'm aware of Tend to have a static base board a static mother board a system board It doesn't change and then you expand that to do what you want with PCI PCIe USB Sata all of these self-discoverable connections The minnow board has an expansion slot Actually, I've got it covered up because there is a secondary board on the top here and it exports PCIe It exports Sata it exports USB all Self-discoverable, but it also exports I-square C spy can non-discoverable buses that need to be described in some way, but because they're here When people build out this board to do things with it the base board is dynamic So it changes one person's minnow board is going to be different from someone else's minnow board the way the GP Ios are mapped or it's going to be different from Instance to instance of how the board is used and that is sort of a fundamental fundamental shift for Ia designs All right, so let's talk about how do we deal with this for the minnow board on the GP IO So there's three sources of GP IO on the minnow board the CPU itself has got a core well Which means it's powered when the CPU is powered and it's got a suspend well Which means these lines are available when the device is in resume It's also got another 12 GP IO lines on the platform controller hub on the PCH or the chipset Both of these are PCI enumerated and the kernel already knows about them We fixed had to fix like three bugs or something in there Again because those GP Ios had not really been Heavily used in the past there were problems like it assumed only eight bits, but as you can see we've got You know 13 and 12 so you kind of actually access the upper bits of the things There's some simple things like that those are easy to fix the cinema stream to get pulled into the stable trees done But how are we using these so if you look on the front of the minnow here there are How many people can see this very well there are four buttons here And then there's a series of LEDs and two of those are just tied to GP IO So we've got four user buttons tied to GP IO and two LEDs tied to GP IO This is not exactly interesting driver stuff, but it is representative And so if they serve good exam serve as good examples to talk about something you can't really see here Is the PHY has a physical reset line and one of the GP IO's is used to Tag that reset line to be able to wake the PHY up and we'll talk about that when we get into the to the Ethernet side of things and then of course we took another eight GP IO lines and we sent them out the expansion header So that people can build GP IO lures the daughter cards for the top of the minute. I'll call I'll call the lures So how do we how do we make use of these well, there's there's There's something called a board file which I mentioned earlier It's what you'll find in the kernel sources driver platform architecture Splat These are are non enumerating drivers So you just load them with mod probe right and and they load up and they do their thing Hopefully they do some sort of validation as to I should really be running here But they don't have to which makes them a little bit dangerous and make some assumptions about hardware there Yeah, we'll we'll get into this a little bit more but there's some great examples in the kernel on how to do this and They're really easy to write so you basically open up a driver You do your boilerplate driver stuff You've got your net your exit and then during a net you reserve a few GP IO lines You create the arrays that you need to do for the platform drivers and by now. I'm talking about the good kind so So for example GP GP IO keys or leds GP IO those are examples of platform drivers and what you do is you you take a platform structure platform data structure and you fill it in with The things that are relevant to that so for the leds for example, you need to give it a GP IO line You need to give it a trigger And then you just create that platform driver and you now have a leds GP IO driver. You do the same thing for GP IO keys Export a few GP IO's to the CISFS and you're done board works. It's great How many people have written a board file? Yeah Okay So they look something like this, right? They're really easy to do Up here. I really I tried to get it to fit on here in the back. Can people read this font? nice So in green is where I tried to highlight the interesting bits so At the very top is the list of files and to do everything that we've talked about to do the GP IO to do the Leads to do the buttons to do the fire reset board detection type sit out the hardware ID It's 462 lines all of which have a header about like this at the top of four different files and it's that's it So first for me to do this for my single board. This was easy There are requests for example, you can request an array of GP IO's You can request a single GP IO I should have highlighted there says Mino Phi reset right and then I registered the platform device that I had populated for Mino GP IO leads And that has a compatibility to work with the leds GP IO driver and it loads up and it's done I even have my own little functions for the Mino board so Mino detect for example It'll go and check the SM bio string DMI board name Make sure it's Mino board and if it is it returns true and if it's not it returns false So now I can just include my header file that has the Mino detect Declaration in any driver that I want if I have to do special stuff. I just check am I a Mino board? Yes, do this stuff right great No And actually I knew this was wrong when I did it But we didn't have really a solid way to handle this the right way So I went ahead and sent it out anyway and got some really great feedback. So Linus W Gave us some really good feedback great cage, of course Anybody that discussed this with me on LKML in the room? No, okay, I can say whatever I want No No, honestly Really great responses, but mostly let's not add anything to platform drivers x86 splat. Okay, nothing goes there. No more board files, please Okay, so why why is this bad? As I said, they're not Self-enumerating so they make assumptions and even though I had a Mino detect in there where I checked the DMI string Not everybody necessarily would have and so if you do that, let's say you just grab a GPIO line set it to an Input or no. Yeah, you set it to an input No, how's that work? Anyway, you can fry your board. I can't think up here You could really do some damage to your hardware if you make assumptions about the way it's supposed to work You start randomly writing to registers because those are yours, right? Unless it runs on another system and then they're not So it's really bad design practice It doesn't leverage code that already exists Worse yet for the kernel maintainers that you're talking to it adds more files that they have to maintain So that doesn't tend to make them happy it also Impacted every one of those drivers there along the bottom so the PCH you are the PCH GBE the the LPCSech GPIOCH the GPIO PCH all of these drivers now had to be Mino board aware That's great for me, but it doesn't scale So how many of you have supported a board? Okay, so now we have 50 if this is my board do this if this is your board do that so This doesn't scale well and it leads to evil vendor trees. Oh So that's not how you do it and we'll get back to what does work But in the meantime, let's talk about some others that that highlight things like enumeration Identification device description so the Mino board you are this is actually something I had to solve for a previous device called the Fisher River Island to but because of the way this You are it works is the firmware gets to decide the clock at which the you are it is driven So it's PCI enumerated. I know what the device is. I know the vendor I know the product. I still have no clue what the clock runs at So how do I check? There's a few options There's already Existing precedent in the driver to check for the SM bio string So that's what the previous systems did before I added these systems So we continued with that. I actually ended up rewriting it to use the DMI match infrastructure when Greg said hey There's a DMI match infrastructure. Why are you doing all this string compares yourself? So we rewrote it and made it and made it do that But it's pretty simple you can see what the old one did checks the product name if it's Fisher River Island 2 Then you set it to the 48 megahertz clock if it's the Mino board Then you set it to the Mino board you are clock which happened to be 50 megahertz just enough to You know give you garbage on the screen I wouldn't recommend using SM bio strings on new designs. It's not bad it works It's not really necessary and there's better ways to go about it and we'll talk about those Now the ethernet is fun and this is a really good example of Some of the complexity about driver writing which is not immediately obvious to a core kernel guy And I'll talk about that and in a little bit in more detail But what some summarized up here these are the things that we had to do special for our special thigh Basically There's two two things that are special about the fight first of all it's narcoleptic So it goes to sleep every opportunity it gets you pull the cable out it goes to sleep I'm sure that's great for some reasons, but it was really frustrating for us. The other thing is a lot of fies have Strapping involved which will allow you to either Use a two nanosecond clock delay in the traces on the board meaning you route the traces just so So that it takes some time for that signal to propagate or you can force it to use a software delay inside the fire This is this is technical stuff about the way max and fires work Is everybody comfortable with the difference between a Mac and a five because that's important today Okay, so worth covering so the Mac talks all of the Okay, somebody can describe this better than me But I'm gonna summit summit summarize it like this the Mac does all of the sort of digital aspect of the networking This is where the ethernet frames go. This is how we order the bits This is this is what it looks like and then the fire takes that and pushes it into the real world Okay, okay, so You can use various fies with a Mac. They don't necessarily have to be matched up But that doesn't mean that the drivers are necessarily aware that you can match them all up differently A fire hangs off the Mac and it can communicate over something called our gmi I and you can talk to it and say Hey, which fire you and it says oh, I'm this ID and say okay. I know how to talk to you These are the things we need to do in order to talk to this fire First of all we got to flip the the five reset line that we talked about so that's what the top four lines are doing Right, we just hold it low pull it back high wait. Okay. It's awake. Let's move forward The next block is to configure that two nanosecond delay. This is really easy You set the register you read the register you set the flag you write the register done Then you do it again for to say disable hibernate because I don't know when the same is going to sleep again And basically I just want to keep the thing awake so that I can use the the network right now This is not the ideal way to do this but Again set the register read the register set the flag right the register basic stuff The first patch we had to do this took these three blobs and then they stuck them in a knit probe and fi setup Done it works for my board doesn't work for anyone else's board How do I detect that I'm running on a minimal board? How do I make this acceptable to David Miller, right? Well, you just read over our gmii right you go to the fire you say which fire unit gives you its ID And then you can talk to it, but it's asleep. So it's not talking to you So you don't know who it is because it's not responding over our dream. I Okay, so we need another way to identify the platform. We could use SM bios and that would have worked We could use device tree But pulling in device tree onto an x86 board just for the fi It's kind of doesn't really seem right Could it could have used a CPI except this is a PCI enumerated device and it's already got all the infrastructure in place for PCI I've learned later. Actually this this could have worked. We could have used a CPI to do this But something I didn't know about was a PCI subsystem ID. So in addition to a PCI vendor ID and a PCI Product ID, there's also such thing as a PCI Subvendor ID which also subsystem ID which also gives you a vendor and a product for a subsystem Which means I took this chip from Intel. I put it on my board and now I'm treating it a little bit differently So here's my ID. This is really cool It took me a couple of months to find out track down all the people that I needed to track down to actually get an ID Assigned so if you're going to start working with an Intel device And you want to do some derivative work with a PCI device get yourself signed up for the PCI So it's cheap. You can get your IDs manage your own IDs save yourself some time This is really great now now when the miniboard device probes It sees the circuit co subsystem IDs and it knows which device it is So now what do we do we could we know we have three things that we need to do we need to wake it up We need to set the two nanosecond clock delay and we need to disable hibernation Some of those can actually be abstracted So rather than saying if I'm a miniboard do this if I'm a miniboard do that if I'm a miniboard do this in several places What if we were to have a platform in it structure? So now there's a little blob for the miniboard or any other device that wants to use this that is a little bit special And it can just set up do I need to nanosecond clock delay because this is not a miniboard specific thing That's a standard thing and someone could use this phi and not need it Or they could use a different phi and not need it So does it need to nanosecond does it need to have hibernation disabled and do you need to do anything special to initialize it in The first place so now we can make one of those structures for every device that uses this So now we we've been able to do something a little more generic So this is how we'd go about that so at the top is the priv data for the miniboard specifically So clock data true hibernate true platform in it function callback right so it calls that during in it Then we set up the PCI device table and so in green there you can see the delta right below it is the old one Right that was for the old Intel And you'll notice the vendor and device are the same for two blocks It just adds the sub vendor and the sub device So now we switch on that and we identify it and then we just create Yeah, I didn't flush them out for you because you already saw the code earlier in the bigger blob Right, so there's the three functions down below the platform in it, which does the GP IO Flip the clock delay and the hibernate so there's our three functions and That basically works okay But what about the mac so The mac has typically max typically have an ee prom and on the ee prom you can store various things including your ethernet address e problems cost money and A lot of hobbyist boards will just use one of the locally allocated Max right iEEE whatever that's called iEEE locally locally allocated. There's a little block that you can use for this Problem with that is if you have a lot of these boards on a network, obviously they will collide because they're eventually they'll be conflicting on max and The the the people we were working with with an intel thought, you know, we really should not be doing This for for an intel board. It's it's not going to be what people are expecting of an iA board So let's go ahead and get some max and do this right But we still didn't want to put an ee prom on the device keeping the cost down was really important And we just couldn't we just couldn't justify the ee prom So we went through some various ways of doing this. So so how do you store a mac? We actually got to the point where we said well, we've got the firmware We we could just stick it in a certain region of the spy flash and then you could go read it But while that's fairly doable from firmware. It's actually a lot more complicated from the os than you might like to think Well, okay, if the firmware knows it we're running a 32 bit efi firmware EFI firmware variables are actually really well suited to storing hex strings And we actually had a patch that did this we stored it in an efi variable If you were on the miniboard you loaded that efi variable. There was your mac Ethernet adder as you loaded it We would have definitely received some criticisms of it. I wasn't looking forward to sending that patch to david miller But what eventually at peter anvin had recommended this Typically the way the driver works as it boots up it reads the ee prom it finds the mac it sticks it in the pc i configuration register Well, there is no ee prom. So that read fails But that's okay because now what we can do is before we booted in the firmware We read it from the location on the spy flash, which was easy to do in firmware And then we just cram it in the pc i register from firmware So when we boot up it goes ahead and looks at the ee prom it doesn't find it it goes back It's got a valid one in the pc i register already And we didn't have to make any driver changes So that was great. If you don't have to do anything at all to your driver to support your device. That's That's the best way to go Okay So we've had a few successful changes the uart the mac the five those all worked The gpio was a disaster. Um, so let's talk about what we learned a little bit. Okay, so Does anyone have any questions this point? Yeah How do you mean So there is a tool on that we ship with the firmware that allows you to set the mac address again But if you did want to change your firmware you you certainly can but you would be responsible to populating the PCi register with the mac address. However You choose to store it, right? That would that would just be one of the requirements of your firmware So platform has become a pretty important thing for ia boards As something that is a block upon which you build other things the less you change it the more reusable it is Um a good platform reduces time to market for people building derivative works of your of your product and x86 is actually a really strong platform And so as driver riders it is our responsibility to uphold defend and continue that platform So we do not fragment it. We do not create evil vendor trees Right we we do this is this is how we should be doing this We preserve the platform So I mentioned something about complexity. So as a core kernel guy, I spent most of my Kernel development looking at really small sections of code and how they related to other really small sections of code Lots of them at a time hundreds of threads. How how do how do these parallel Algorithms run together. Does the locking work? Do you have my memory barriers in the right place? This was brain bending complexity for me. It was a lot of work and it was it's a lot of fun When I start if you start looking at drivers you take any one driver you take any one function and you look at it and it's Dead simple right read the register set the bit write the register Really simple stuff until you back out a little bit And you start to realize how all these devices interact with each other How many classes of devices there are how they enumerate? Um, it actually gets really complex as you back out and look at it from far away So the complexity of core kernel development versus driver development is inverted Great curl Hartman once said that a great dry. I don't know if he said software developer if he said driver developer But I think we can say It's true for a driver developer One of the best thing one of the things you want to look for in a great driver developer is organizational skills And I think that is especially true with drivers as I look at the complexity Of the all of the subsystems put together And greg has done a phenomenal job Organizing drivers and and everyone that works with him and it sounds like a lot of you. Um, so I was really impressed actually. I think it's um pretty clean code so On the front end this was this was something that we learned working with circuit code So this is the intel's yachter project folks the UEFI team that worked with us with circuit co together as we built this board one of the things we learned is that Typically the way ia products are designed. I but when I say ia I mean intel architecture Typically the way ia products are designed is there is a single reference design And then lots of companies take that single reference design and they make a product from it But they don't deviate very much from it Meaning they don't go out and use the cheapest fi they could find that suited their needs Or the one that they could get Quickly or the one that they could get in the quantities that they needed They use the one that we used in the reference design So if you have the opportunity to influence the design of the board before you start writing your drivers consider what the drivers support already And if you can select a part that already works with the drivers, that's a great way to go In the case of the ethernet on the minnow board one of the problems that we had was That particular driver probably could have been written better in the first place Probably could have used philib Which it doesn't use it should use and we have somebody volunteering to actually Migrate the changes that we made to make the driver use philib and incorporate the changes that we made He's doing that as a side project just to contribute. I think that's great Um Yeah, so if you have an opportunity to influence the design spend the time to research How the drivers that you plan on using already work and what they support Um, do they need special layout and configuration? For example, should you go ahead and run that long trace to get your two nanosecond clock delay between the tx and the And the output on the fi Is it okay, so maybe you can't do that, right? I didn't realize it was quite so long Um But those are some things to consider So identification and description As we as we started looking through all those drivers. There were two things that really came That this really boils down to is how do you identify your device and how do you describe your device? You can identify it in a number of ways that we talked about pc i provides vendor product subsystem IDs You've got firmware description either via acpi the device tree You can do s and bios there's probably some others um, but The those are the basics. Um, and then how do you describe it? So pc i of course has got register blocks for every single device and it's all there in hardware for you Um, and then there's big tables about what all of that means Um, it can be hard coded by id which is what we saw with the board files where Well, not necessarily the board. Well, anyway, you can hard code it in the driver But the problem with hard coding it in the driver is it's not particularly flexible So one of the things that I mentioned on the miniboard, right? You've got these leads and these buttons So the leads do things like run a heartbeat show you mmc activity stuff like that Well, what if I didn't want to show the mmc activity of mmc zero? I wanted to show it of mmc one that is the device that I added to my lure Now I have to change the kernel driver to do that Or at least by default. Yeah, I can do it through ssfs But it's going to boot up showing the wrong thing and maybe I care about what it's showing during boot um well Right, so you can describe it in firmware and on an x86 system. They typically have acpi already So you could try and take acpi and you can marry it with device tree and you could try to Cram them together onto the system and get them to work and you could do it But should you do it? I don't want to spend we could spend the next hour talking about device tree We could spend the next three hours talking about acpi and device tree. We could bike shed on this all day um, what i'm going to say As my stance from the experience that I had the people that I spoke with this is what I believe to be the right thing acpi and device tree try to accomplish some of the same things and it's not going to be easy or clean to take those two things and try and cram them both in the driver's seat so Really what I think we need is a way to be able to say hey firmware, whoever you are I need this device property Give it to me now if you're acpi give it to me this way if your device tree give it to me that way I'm seeing some skepticism. Let me show you what we've got working now um, so The biggest lesson I think about this is when when we're focusing on a board and we're working to get it out It's really easy to think about our delivery dates and all of that. It's not just about you When you're writing a device driver, you're contributing it to the linux kernel It's going to have to be maintained by people It's going to be used by your customers to do other things. Do you want to lock your customers into a specific kernel version? There's a lot of really good reasons to not write board files Do you want to make these things as flexible as possible as easily maintained as possible and um, Yeah, actually, I think that that sums it up um And of course linux decided yesterday or two days ago to go ahead and re-emphasize that for us So I had I got to add that slide this morning. So thank you linux All right, so let's take another approach to looking at the gpao drivers for the miniboard How how could we do this in a way that might be acceptable upstream? By the way, all the other drivers for the miniboard are now in 3.12 um The gpao drivers are not So from the lessons learned we want no device. We want no board files Matter of fact, if we could add no new files at all that reduces long-term maintenance reuses the most code that would be ideal um And then let's continue to support the platform on ia we have uef i On i'm sorry on the miniboard. We've got 32 bit uef i and on ia systems. We tend to have acpi So we're going to take a look at how can we do what we want to do with acpi Is device ring option sure it could be made to work So identification and description, what does acpi 5 do today You can create hids readily hardware hardware ids, right? So there it's it's Enumerable, it's actually very easy to take acpi bindings and add them to a pc i device so you can get added configuration that way um ACpi already knows about as as a 5.0 can already describe gpi. Oh, it can describe Pins it can describe interrupts It can describe the address and ranges and things like that what it does not do is provide a standard mechanism to be able to give you arbitrary device properties And i said standard mechanism. Can it be done? Yes apple does it now They have device specific methods for example that they Query in a certain way it sends them back a buffer for how big the result is and then they Send another query and then they get the big buffer back from acpi and then they do whatever they want with that It works, but it works in a very limited environment and it's not generally safe Is the summary again, that's probably something we could talk about a lot So in the next few slides i'm going to go over how we went ahead and made this work on the miniboard with acpi In a way that we're hopeful will be acceptable into the standard And acknowledgements to everybody here That had a lot to do with making this work wrote some of the code into acpi Did a lot of the brainstorming to help make this a reality so I want to make sure that everyone sees that the following slides are not all my work. It's Taken in with a lot of input from these folks Okay So a dsdt, um, I forget the d. I think it's device, but uh system descriptor table This is the big blob that you can dump out of any system running acpi with the right with with the iacpi tools You can just dump them out So with acpi 5 as it stands today, we can do something like this acpi is a heavily scoped Sorry asl is a heavily scoped language And what you're seeing here in green sb pci zero lpc. So this takes us down on the p on the system Bus the on the pci on pci zero. There's a low pin count device. It already knows about this So we're just going to scope it to there And now if we go below that we're going to create our own hid for the purposes of the demo. We're calling it minnow three here And then We're going to set up a couple of gpio resources So in this case, I want to take suspend line five and suspend line six And I want because I want to use these as the two gpio lines that are driving my leds So I've set up 10 and 11 here But once I've sent that up to the kernel I wouldn't necessarily be able to do anything with it because I don't know what the trigger is I don't know, you know, if these were gpio buttons. I don't know what the key codes are Right. These are all things that you can do today with the vice tree Really easily couple of lines you send it in right and the the platform drivers know how to use it Well acpi has something called a package And a package is basically a typeless array and you can use any kind of type that you want strings integers additional packages what It seems like we really want for device description is a dictionary You basically want a label and some data And it should be in received in some standard way that You you can readily parse it. You can readily validate it that it's what you want So we could just do A dictionary that would be just a you know string value string value string value And that you could make the code parse that and use it as a dictionary But if you wanted to add a little bit more structure to it If you wanted to make it a little more formal you could create a package of packages Which has each package is a tuple All right, and you've got a you've got a label and a value Um, so here's an example of that in the middle there So you've got string hello world number gives you 10 list has a package of one and two integer one and two um so if You wanted to throw that into acpi you could create a method called say properties And you could create a package and return that package that had a set of key value pairs But it really needs to be standardized So we should use a reserved word in acpi So we could come up with something reserved reserved words in acpi. I'll start with an underscore so You could have for example an underscore prp method, which would be the properties method Um, and it would look something like this So you'd have the device again. We're in the same scope system bus PCie zero lpc same device. This is leds, right? So up here in here, you would also have the gpio description that we had on the previous slide Just adding to that the prp method and then here's a dictionary that returns label um, so for instance with um with gpio lines It's generally helpful to be able to identify them and in sys kernel GPio no sys kernel debug gpio It'll list the name for each gpio line. So it'd be great if we can label those right So you can do that here on that first line. You just say label I don't want it to be minnow led zero minnow led one and then for The triggers I want to use heartbeat and mmc zero and then there's some other arbitrary Excuse me arbitrary properties that you need for this particular platform driver So you add that to your dsdt you compile the dsdt And then the only thing you need to do is add your ACpi hids to the acpi platform dot c and that's what's being done there. You add minnow two and minnow three This is yeah with this one or Okay, I think I okay, so the question is How how do these changes get onto the board so that you can use them? I think you're asking What is the equivalent to the lib firmware flattened device tree thing, right? Okay um That Is not a gap that I thought I didn't think it was a gap and then I found out it kind of is a gap and It's not a big gap though The way it works currently is you can you can take out the device You can take out the dsdt then you modify it and then you replace it And you can do that one of two ways you either compile it into the kernel Or you can set it up in an initial ram disk The way it should work is you should be able to Use what's called an ssdt, which is a secondary system descriptor descriptor table And as long as that augments information, this is in the acpi spec as long as that augments information not replaces it You can layer them right the The the the fact is because we haven't been doing this the tooling in the kernel today doesn't allow you to Augment it only allows you to completely replace the dsdt Um, that's a gap that needs to get fixed five minutes. Okay So In order to use this information We have to set the we have to set the hardware id so that the device drivers can recognize them And then we have to set up a ACpi parsing function So if you were to take a look at the leds gpio or their gpio keys You will see an of parsing function which reads device tree. So we add one that reads acpi And basically you Look and see which one you have and then you pop you basically just populate the platform structure That's empty and then you create your device with that and that's it it it parallels exactly how The open firmware model works and the acpi model works Okay So once you've done that in the acpi properties driver, then you augment your ledge gpio driver or your and I just meant This is actually what I just mentioned So you can see here I'm going to walk away for a second So that was one of the the strings that we had set in the acpi properties function So it works just like it does in device tree. You say hey, I want that function and I need You know these many of them and it reads an array and it sets it into the array and then you walk through the platform device Which has an array of of leds and it fills them in it's pretty straightforward um, and with that So there's the min and board. It's running 3.12 orc 5 right now and if we were to Watch uh debug gpio Um, you can see that we pulled in all the labels So you've got them. We did it for the buttons. We did it for the lads. We did it for the fi reset So they're all there. Um, and as I i'm going to push the wrong button. I know it Yeah, exactly So you can see Right those have been mapped into the driver They're working and if you look closely here um You'll see an le view that's blinking and so that's basically the heartbeat. So we've set up the trigger for the heartbeat um In the future i'm going to cut this a little bit short. I'm not cutting a lot off, but um, let's go to next steps there um There's a few things left here to be done the prp method needs to be formalized We really need one more layer of abstraction rather than having every device driver Have to say this is how you do open firmware parsing. This is how you do acpi parsing should just do device property collection I want to I need this property for this device if i'm open firmware. I'll go over there if i'm acpi I'll go over there. I'll collect the information. I'll make it work. Um So that that's been discussed on lkml. Um, there should be some more talk about it today at kernel summit There was another discussion at linux plumbers Um in new orleans about a month ago and this seems to be generally accepted as a good way to go So there's more detail that needs to be discussed, but it seems to be going in the right direction One thing you may have noticed Adding the mino 002 mino 003 ids. That's kind of a pain especially for generic drivers So what we'd really like to have is a set of standardized reusable Keys and or ids and then you don't have to add them at all You just just like in device tree you would say this is compatible with this driver In acpi you would say this is hid You know Linux 0 5 6 0 and that's the leds. Yes You you could add as many as you wanted. Yeah Full for the single device I suppose you could I don't Right, I don't see any reason why you couldn't do that. Um because you would just add to Yeah to the acpi match table you would add the two ids And then as you parse those ids you would get different information and configure the device I don't see why that wouldn't work. It's not something I've explored fully though As was asked about firmware one of the other gaps here is we need to continue to make the firmware more open Because this will make it more and more useful to people to be able to rebuild Reconfigure changes ds dts in the firmware and go So, um, I am out of time I hope we'd have a few more minutes for questions towards the end But I do have time scheduled at a chalk talk at the intel booth and basically That talk is answer questions and go into more depth So if you have questions you want to talk about it more detail come see us at the booth And I hope this was helpful. Thank you