 Okay, thank you all for coming. This session is identifying and supporting extensible hardware blocks. And my name is Chen Yu. I'm a software engineer and sysadding at VWosa and Taipei. My day job involves managing Linux servers, networking, and running tools to automate this stuff. And in my spare time, I've been working on Medlinix for five years now. And I've been the main trainer of all-winner SOC support in the Linux kernel for two years. Before I start, I'm not an expert in this field, so if you have anything to add or if you have questions, feel free to come up with me. This talk is... The motivation behind this talk is about sharing drivers. So if you have hardware that is mostly compatible, then it makes sense to use one driver and then work around any parts that each variant has. So a sharing driver means the driver as a whole gets more test coverage, and you spend less time and less effort in porting the driver to your platform. Now this talk mainly focuses on the experience we've seen as a community for all-winner support, but it should be general enough to apply to all other platforms. So first we'll talk about what do we mean about compatible, and then we'll talk about how do you identify the hardware blocks and then how do you go about implementing driver support for variants, for you layer around the hardware, and then I'll give you some examples that we've seen over the past few years. So everyone should know about the duck test. If it looks like a duck, it swims like a duck, it quacks like a duck, then we call it a duck. Applying this to hardware, if it has the same interface, if it has the same logic, and if it gives you the same responses or results, then it probably is compatible with something that you know. So if you've been using a personal computer in the late 80s or the 90s, you probably recognize some of these terms. VGA has been around since forever. Warts, 250 eWarts, I need 2,000 ethernet. Adapters, Adlib, and some Justice Shunt cards. These were like, especially in the last two, these were like really popular products on the market, and so everyone ended up just being compatible with them, and this made like software writers, game developers very happy as they only had to support like a couple of hardware variants and everyone could just use them. Supporting these means that you have a lowest denominator, you have a basic function set which you can support in a common interface, and so one driver can apply to all the newer hardware, and it just makes it like easy for us developers like me. If you know most of the hardware is compatible with a Sound Blaster sound card, then you probably only have to write a driver for that instead of like 10 or dozens of different vendor sound cards. Now moving on to the modern today, we see standard control interfaces like for USB, for SATA, for SD cards, HCI, HCI, OHCI, etc. Yeah, but it doesn't appear that much anymore. And then we also see in the embedded world we see licensed IP cores, and for some of these cores we actually see clones of them. Now standard interface means there's a standard that defines what each register means, how you interact with them, what the hardware is supposed to do, how should it respond, and each vendor will just implement the standard and you should be able to just use a common driver for it. Now of course when a vendor integrates it into the SOC there will be a vendor blue layer. The vendor has to provide clock signals, recent controls, other control signals, and probably a five for it. But as we will show, this can be handled outside of the core library, the core driver, and moving on to IP vendors. In the embedded world you probably see at least one of them. Synopsys, as in the design world, product line, mentor graphics, cadence. These vendors provide IP bots for various protocols such as USB, HDMI, Internet, and also a given ADA, and SOC vendors can license individual cores and integrate them into the SOC. So you typically at least see one or two of these. The license ID cores only include the core logic parts. So you might even see license ID cores for the standard post control basis which is mentioned. Again, the SOC vendor has to implement the blue layer for clock signals, resets, post signals, anything platform-specific. And most of the time there's also a client involved in this. And we've also seen clones of... It's possible it's a clone, or maybe it's just a variant of the license ID. It has the same logic. Sometimes it's missing registers, and sometimes the registers are just moved around, it might be just implementation detail or it might be done on purpose for obfuscation or something. Like some vendors really don't want people knowing what IP blocks they're using. So how do we know what hardware block or what IP core your SOC is using? Now, to do this, you really need some resources. Data sheets from your vendor, possibly your vendor BSPs. If you have any contacts at your vendor, if you're in a good relationship with them, you might ask them. Sometimes they won't respond. Most of the time they won't. And also the larger kernel community might be able to help you. Besides your platform's data sheets and BSPs, there are some good public data deditions that you can compare to. The IMX6 reference manuals, this has very detailed information on a couple of design-ware controllers. HDMI, HDMI 5, and Ethernet controllers are all listed, and it's very complete. Also the TI Keystone 2 user guide library has a couple of skills. We use them in community for identifying the DRAM controller in the AADS stock. For identifiers, typically if you get a data sheet, you can look at register layouts or register names. Sometimes you will be able to map them one-to-one to a known example. If your hardware has a DMA engine embedded inside, the DMA logic might be specific to this controller or the descriptor format might be specific to this controller. And also there's the last option or last resort. If you have a BSP, and it doesn't have to have a source, if it's just a blog with symbols in it, dig through the symbol names and find some of the more peculiar ones and just enroll them. Sometimes you'll get a hit with some wheat source. It's probably not that usable in the code sense, but it gives you an idea of what this might be. And last, this really requires a lot of experience in the field and a lot of love. If you have a new SOC and it says nothing about the vendor, the capabilities or possible model of the controller, then you really have to look at everything and you really can't... It's not possible for you to know everything. So you can only recognize something that you've seen before and if you actually do manage to do this, then it's best that you can leave notes for others to follow. Also, experienced members in the community might be able to help with this. We've seen ARN and other people come by and just look at this hardware and look at this data sheet and says, oh, this might be the term graphics at USB. And there's also, like, a good possibility that you can't identify it and then you start writing a driver report and then you finish the driver and you post it on the building list and then someone comes by and says, oh, okay, this... the image structure looks a lot like a design wearer and then you throw out the driver and you start reporting the existing one. So you might want to remain there. Now that you've identified your hardware, you will start to import or implement your platform-specific blue layer for the existing drivers. Now, in the kernel, there are a few ways to go about this. One is for very common hardware control blocks. They will typically have a driver library. The core logic is implemented as a library and then we have different platform drivers implementing platform-specific stuff for each platform. So there might be extra resources, blocks, recent controls, or regulators involved. There might be a few extra registers that need to be poked and then typically the platform driver will implement some callbacks and pass on the callbacks and pick to the library. So this is an example. This is the DW Blue Mac DesignWare Mac in the kernel. It's called STMAC for some reason and it's a driver library. So it also has common functions to handle some common resources and parse some common big options and then you implement a few callbacks and pass it on to the library. Now, if the core driver is not a library if it's just an old driver and you are porting it to something else, then we typically just match by the society such as the platform ID to speak experts the ID or advisory compatible and you will write a code what differences are between all these variants that the driver is supposed to support. Some drivers just check if the ID is something and then you will do X, Y, Z. Unfortunately it kind of works but it's kind of ugly and if you start supporting more than a few variants the list kind of grows a bit and it will be hard to maintain. The preferred way would be to have a data structure with various fields that say there's this feature that features ABC and then the driver code displays and it adds a feature if it doesn't have a feature it will do that and in some cases you have to deal with registered changes. Some hardware we've seen has registered offsets that have been changed or even bit fields that have been moved around we have a couple of ways to deal with this. The first one is registered offsets being moved around you can just use a registered offset table it's basically a data structure using all the offsets that you care about and instead of using defined macro to access you use the offset from the table. Now if you have something more complicated like bit field changes you want something that's cleaner you can use a regmat field a regmat field defines the offset of the register in the regmat and the bit fields parameters like shift the bit fields shift and width and it handles these bit masks and shifts for you so you don't have to have the let's shift there are reg shifts in your code anymore so first you define your register fields and then you instantiate them and then you just use the instantiated regmat fields to do your access and last there are some cases where you can't use these sometimes you have missing registers that you have to provide in defaults so the last resort we need to provide custom IO functions so any IO that the driver does goes to these callbacks and this is common this is found in the USB driver where we have register offsets that have been moved around and the all winner version is also missing a couple so any questions so far those who go through some examples first of all the 8250 UART it's kind of what the factor standard and the kernel has an 8250 driver library and if your UART has nothing special you just use it if it does then it wraps around it so all winners we have the synopsis UART which has an extra interrupt signal and basically it fires if you try to change any settings while the UART is missing and what you get is it's a rapid fire interrupt that no one cares about and the kernel would complain and then it would shut down the IRQ and then your UART would basically be kind of unusable and so the 8250 DW driver basically uses the 8250 library but it provides a custom interrupt handler to handle this I think it's like 50 to 100 lines of code HCI sorry that's so well what happens with that interrupt it's somehow supported knowing that it's an interrupt you just noticed that and so you did nothing about that okay so the question was is this extra interrupt supported in the design work record yes it is supported when we the communities first started doing all winners support we use the standard UARTs in some cases you would get this problem and so Maxime month the other retainer found out about this and he just switched over to the design work driver and everything is fixed so HCI HCI has two libraries HCI handles the core stuff for the satellite core and then with HCI platform handles the extra platform resources like OX, regulators FI's and then there's a generic HCI platform driver which is basically just the wrapper with the driver module going around the HCI platform and some platforms such as all winners implement a platform specific version of HCI drivers they ours has to pull a few extra registers for DMA to work and different platforms have different products okay instead of USB so for OHSCI EHCI and XHCI not sure about UHSCI but these three have like driver libraries for the HCI-HC driver library and these handle all the USB parts of the race and then there's also a generic platform driver which handles all the common FI's FI's and regulators and in some cases there's a platform specific version for this so USB also has a platform driver mentor graphics and USB so this is a USB on the go controller it can do USB host mode or gadget mode and it's seen on something like five platforms and it has all the required control signals for OTG ID pin and web us detection and there's like a driver library for this and it can also add integration time in parts of a separate USB file now the all weather version has rearranged registers and also has specific registers so we support this with custom IO functions and for the register that is visiting which provide the same value unfortunately the missing register is actually the feature register so that's kind of kind of bad and the all weather socks have a very weird USB file base so programming requires bit poking register and basically it's kind of like an embedded bus within the sock and you have to use a very weird sequence access and also the ID and web us detection lines that I just mentioned are not routed outside of the sock so in this case we have to use extra GPL lines to do this and then somehow export the status to the USB driver to the XTCON framework the last two are design worry examples the first one is a design worry mac it has many hardware revisions the later ones have a feature register which is nice but ours doesn't it's found on a dozen or more platforms and it's called STL mac in the kernel I believe this is because STL in electronics was the first platform to open this and it's a driver library and the platform is supposed to provide to fix features and various callbacks to the the library now the old version we've seen in all the stocks is a very old revision and it doesn't have the feature register I just mentioned so I had to like dig out all features supported by this hardware from the USB kernel and then put them into the driver and then there's also a layer around this and it's pretty standard stuff for internet controllers I think all platforms have the same design it's just a different way of accessing them normally it's just on register and later all weather stocks have this weird eMac and it was a d.w. mac with rear-range registers and some of the pitfills have different meanings for the various values yes so do you know that there are two different internet controllers one is solder, STM-9 and newer are QoS so probably they use just a newer similar to the internet controller can you check that I'm sorry the QoS driver could that be the one here I'm not sure actually I'm not the one that did this work this is basically a compilation of stuff that we've done and that might be worth checking out so this controller only supports chain DMA, the old controller supports both ring mode and chain mode it's basically the difference is how you allocate DMA descriptors and the DMA descriptor looks the same a few fields are marked as reserved now at the beginning the guy who was doing support for this did not realize that this was a d.w. mac controller so he wrote a whole driver from scratch and posted it on the mailing list and he got to version 5 and then someone came in and said this is basically a d.w. mac controller and then it only supports chain mode but the DMA descriptor looks the same so he basically threw all that work out in like 6 months or so so now there's a new version of the driver that's in extension of the existing d.w. mac driver and I think we're now at version 9 or version 10 maybe there are some hiccups with the bystree bindings but yeah, you really want to avoid these types of conditions like when you put it all in work and then it gets thrown out last designware hdmi controllers this is found on 5 or 6 black farms half of them use the standard designware hdmi 5 and half of them use custom 5 there's a d.w. hdmi driver in the kernel it's sort of in the library not quite it provides broke and binding functions if you're familiar with the ARM subsystem some drivers use the component framework and some just use the standard driver model so when I say library-ish I mean the library actually pokes with driver-specific data in that it does have a set drive data so you can't have your own private data when you're using this someone might go and clean it up, I'm not sure and again the platform provides some config options and also callbacks in the case of custom cries it provides callbacks in the setup design in the case of hdmi files it provides a table for the settings and on all winter the hdmi controller is obfuscated basically the 32 address lines are scrambled so you get really weird addresses and fortunately someone found out how to disable this and so you write magic numbers and some red register and this gets turned off and you can just use the standard design word driver and it has a custom cry and unfortunately there's no source code for this so the Y settings are limited to whatever we could reverse engineer for the BSP kernels and so to recap we as community would really like to avoid duplicate drivers but identifying hardware is really hard and in cases where you have direct contact with vendor it would be really great to ask the vendor but all winter does not talk to the community at large I know some people might have personal contacts but as a company they really don't talk to the community so it's kind of hard for us to do this and last it would really help others to if everyone doing this could share their experiences how they do it what identifies they're using, how they got their info just put it into commit log but in Wiki in blog post do a presentation it really helps to put this information out there on the web so others can benefit from it and that's all for today any questions? we have one experience in the old manifest form as well one experience in the old manifest form and it's all in our A20 and as I said there are some but they've got sheets you may have some registers I guess all the most of them would be able to do a dual name which for the A20 was described in the features list but nowhere in the user manual so just putting different data sheets for the A13 or the A10 or the A33 at least one of them suddenly has this description which also works for the A20 as well that also obviously we have recommendations you mentioned the experiences in the tables and we kind of don't remain as a situation so the question is whether there should be some kind of central Wiki that people should just gather around because you encourage people in the blog notes and so on but then this information is still very disperse finding out different things that are not correct so what it was an actual Wiki that just kind of had a list of all the SSC people and what parts these SSCs had and what were the responses it could have been a form and so on it shouldn't be extremely hard to do it's more some of that to actually kind of make sure that we mentioned those so I believe we have this for older socks kind of getting them from all different vendors I do believe there is a website that has a list of all SSC controllers and it also lists who is using them but on the other side so like socks and what they're using like SSC and who's using that SSC that could be interesting so the comment was having a type of format for cross-referencing would be nice any other questions? Thanks for sharing I'm just wondering can any of you comment on what other vendors are different to malware is malware typical? not engaging the community making it very difficult on engaging with the community I'm not sure actually like Rockshit was kind of kicked into doing this and Logic has contracts with Belgrade to do mainline stuff and I think some of the Chinese vendors are still kind of locked up and even MediaTek is only doing mainline work and releasing DSheets for a small subset of all the chips so it's I think it's kind of maybe a confirmation any other questions? I think we're about out of time so thank you everyone for coming