 Hello, welcome to my introduction to pinmixing and jpao control under Linux talk for the embedded Linux conference 2021 Would I've preferred to be in person in theater, but it's not possible. So let's keep it virtual next maybe next year so first of all and we're going to start at a hardware level to See what is a pin or pad or what is a jpao from hardware point of view? so when you have your chip or your SOC system on chip you can have multiple ways Multiple package types One common one is the QFP equivalent to a QFN Which has all the pin or pads on the sides and the other type of packages are the BGA ones where the pad of pins are in fact bowls underneath the package and There's two different way of soldering the SOC so the BGA match complexity solder The QFN can be done by hand for example, but you won't find a high-profile SOC in QFP package The really complex and high-profile SOC are All in BGA because you can have much more pins and you can Have them much much better Much better layout layout on the PCB But more complex to to design So if you go further in the package You see the die which it's the part which is actually produced And weathers so the die is Put on the plastic Plastic some small Wires soldered and connected to the external pins you see and afterwards the plastic package is It's closed on top so It's globally how it's done inside It's not always like that, but it's a good good example So when now you see where are exactly the pads on the die What's in the hardware Design what are it's not exactly so this is a typical hardware design of a pad Where you have the physical point where the small wires are connected Connected it's going to me is connected to an analog IP which is here here to Deal with all the other parts like the voltage or grounding the pull ups pull down triggers meet and so on and afterwards we have the all the digital parts you have for example a mix for the input of the output for the input mix it's not Always here some as you see the connect the input to all the functions for example and for the output There's always always a mix With an output enabled so it's not the output so to say for example to put in a boot or not put and Typically as a GPIO so the general purpose input output is Is one generally one of the function Sometime when one's the default function or the fallback function where no function has are selected So the GPIO is only a digital way to control the pad the voltage 1 0 input etc. So in the analog parts you see The typical analog parts of a pad We call it push-pull pad or CMOS pad a We it's a three-state pad. So the three states are the two one and Zero-level so one level is driven to the pad voltage. So VCC or VCC IO Zero is driven to ground and There is a first date called high impedance When it's not driven driven by anyone so no no component on the PCB actual drive Nothing on the on the line I say why the high high impedance has a special drawing To say it's between zero and one but nobody knows what's the value in fact So this is a push-pull pad where you can drive to zero and to one, okay For some special application for example why to see or one wire There are some special pads could call open drain pads They all can only drive to ground only to zero they cannot drive to one. So it's either an input or In output but to ground So when you see the drug as a diagram So you can you can manage to have a one or zero on a bus but you need a pull-up on the PCB and This pull-up will actually pull The level to one when the SOC is Input this is how I to see works in fact None of the I to see components also devices Never a drive to one. They're only drive to zero The reverse is open source pad with it. This one is really rarely used but it exists It's a reverse. The SOC cannot drive to ground but only to VCC So it can be used in some specific Hardware, but it's how you are used So like I said, the analog part and I look bad hardware has optional components like a pull-up This they can add a small resistors on all pads to To add a pull-up or a pull-down to one of the two VCC You can select the drive trams for example to to select the some buses need different drive trams or some buses Only you can lower drive sense or you can lower your consumption And other other possibly possible analog stuff So the functions Okay, so The input in the output can be can be mixed it to a function so usually You have an end-ever individual Selection by pad So each pad has a register when you can put a number and the number Identify the function This is not necessarily a case some other engineers. I Are weird and You can have group Selection, for example, and you will you say the function and when you say the function all the pad of other function We will trigger so it's not always the case and You can have real for example pads of what that are only GPIO we only want function But we were GPIO with only functions The function can that sex or bother at one time or for example, when one bit to sex Multiple plans for a function All these might be must be handled in in software So the software what what did we have 10 or 12 12 years ago So it was energy complete energy the arm I so see we're not really What to say majority in the school does so you had Every vendor was really disparate. You didn't have the same support for example you had for some I so see like some some Router as you see some simple one you had really a Simple hard-coded been set up like a single function like you say set this pin to this function really basic To some really complex framework for example in the Samsung as you see support or a TI with a really complex complex checking Code and What we learned of that is Check checking the conflict actively taking the conflict. It's really complex and and you cannot check it. It's too complex. For example You will need a really to describe the lot of hardware to to know what combination of pin is possible or not and in fact this is less because If you do a good good code review of the board support and testing and You implement a simple check We need the dynamic set up for example for follow-up or device when you go to Suspend for example or runtime suspend or sometimes like for complex buses like SDIO or NMC we need to be to switch as a pin conflict at runtime for specific mode and We don't want art coding of board setup at all. So this is why the best tree is here Because it's what I care So GPIO API was also energy. It was older and control It was even worse. You didn't have a Single GPIO.h in each Board or architecture support. We have had a different GPIO So potentially you had a different API different implementation different types different bearview. So it was completely Same that API was too basic Every implementation was different You couldn't handle multiple GPIO controls. It was really complex you Impossible to understand the controllers like I2C controllers, SPA controllers, extenders and Only some SOCs had advanced API with runtime PMC port and so on and GPIO was Too simple and too so specific So first of all what how did it change? In the with the pin control framework, so it was like 10 years ago in fact nearly nearly 10 years ago It was merged and merged in Linux 3.2 So it created the Linux pin control system to handle pin control races. So Like I said in the other part control different aspect of package pins. So The main goal was to remove all of the sparse the different arm arch implementation And simplify everything to have a simple code base to open the same the same thing in the same way same manner So thanks Linux Welsh for your work And still because you're still maintaining the pin control So the pin controller it was split in different the pin controller the pin mixing the pin control so The pin controller Described hardware that control pins Is that you can multiplex? Bias load capacity times for and developing so group of pin top like you see it's defined Is this it was defined for to cover all the possible use case you find on the field So what is a pin like I said into hardware that kept on it's you can call it a pad a finger ball Or whatever whatever goes out of the package and you can control Okay So Instead instead of using the same GPIO architecture while you have a single number across every controller No, you have a single a number space in each controller So there's no as no every pin won't have a single ID You will have the pin controller Handle and an ID in the controller. So it simplifies a lot the architecture Because you can have a lot of pin controllers not not only the so see controllers You can have multiple controllers as you see and we can have external controllers like for example Jepo extender some of them can can be pin controllers. They can offer some features on some pin And one important The pin space is not It may be can make have gaps in the in this space because when you have for example a QFP package from one to 63 Not all pins are controllable. You can have some voltage pin. We can have some analog pins and ground pins So you must cover make sure if you have gaps It's quite limited so some controllers only work with group of pins, so it's a great part to handle and Finally the pin mixing which Was in the main part of the framework is Sexting actinate functions or some some hardware called in motion mode Which permits to to to select the functions on each pins And a great feature of the framework is this can be changed at runtime actually so how how The pin are described in the framework You'll see on the left you can have a list of pins or like Like I used to a letter and number for example So you can't can have the A pins B pins the G pins not They're not Complete so you can have holes in it You will define pin groups for for example, I to C or your art every function groups And for example, you can have multiple function groups for similar for example, you can add a Variant of art you art with different group from for example, you are one can be Can be routed to multiple different group of pins So you can handle this for example la la I hear I I defined four groups one for I to C one for you art and RTS and CTS pins on different groups because for example these are optional and In the function list I said, okay, I to C zero only has one up But you are too one can have three groups You are too one you are too on RTS and you are too on CTS because the three of them can be set But only one you can you can choose which groups of function can be set at runtime So yeah, so instead of to have a Carnell wide number you have a controller wide number and names associated to everything two pins two groups and two functions It's simpler to associate everything via names than numbers so The name must be unique For pink groups, you can have multiple pins one or more for functions. You can have multiple pink groups and The conflict checking is here is The core we will store What are the functions set for each pin or for groups? So if you set a conflicting Group for example, it will be detected. So it's the simplest way to detect conflict The only thing it doesn't detect is when you set the function on the pin before Linux The core doesn't handle cannot load a state of the current pins. It's only limitation So The the framework is pretty simple for example You have free free structure to To fill first of all the pin the pin list. It's only a table of pin control pin desk Which has the name inside? and three Ops ups pin control pin mixing and pink config The the pin control is pretty simple because it's it's only callbacks You can you can really define your own You can define your own table that really match the hardware and You will need to implement the callbacks To give the framework what you need. So the number of groups and of the name of the groups as a and the pin names and of each each Groups so it's much simple than feeding feeding him tables So you you can compute in fact in these functions So you can really describe the hardware like the vendor Does and in these these functions you can compute and give to the framework some processed information or this is for the The groups and same for the function the function with which associates The different groups to function so you have the count the name Which groups and the final will call Simply sets a function in a group Group in a function. So it's the set mix is the is the main call in fact When as all the other calls that have been calls by the core And when the associate support and the driver probes The driver we ask to set the default pin pin mix and The core we will process all the data and call a set mix to set a function on on different groups So it was designed before the rest tree, but but finally Even it was it was before the mapping in DT works really well and Usage isn't change at all. In fact, it's the same way to To set a pin control. So The the code at least here that the pin control get look up state and select state Now is called by the core. So when you probe device Automatically automatically this will be done in fact under the hood So it don't don't need to do anything to set up control only set the the the right Properties in DT or CPI to actually define What are the needed groups and a function for the particular device and it will be done by default so initially it will Set the unit or default state but You can have some special Power management state in fact Which are here to handle all the runtime PM states to lower consumption So here is a DT the way the D how is the defined DT So the first node is a sub node of the pin controller on node So for example for for the pins I defined earlier If you want to define the UARTs one pins You simply need to have a Node a sub node of this one you can have seeps a multiple and all here. I have seen a single mix sub node but in a single in in a DT mapping node You can have you can set up a lot of different groups and functions here only set one for example I Set the three groups or you are to one your one RTS and you are to one CTS and I said I say this this should be to the UART function Because groups can be in multiple functions. So here is in one function, but I could have Set a different groups in a different function so And in the in the in the device node Of the UART controller, for example, you simply put a P handle To the UART one DT mapping In the default node name and automatically at the probe the UART one pins will be set This is like magic, but it's work where we were so now comes to the GPIO framework so the GPIO framework is here to handle the general purpose IEO, so It's the specific function of Pins that can be controlled by software so you can set In input mode and put one and zero and other optional features So the GPIO provider of literature Which defines a single GPIO.h h was submitted in 2008 first for 2625 so It provides an infrastructure that That that that make a single probing interface. So the this program interface It's still almost valid today Because it defined a finally unified API and implementation So it was named a GPIO lib. So it was more designed like a library than a modern framework Every GPIO on the system so on the board Not only the SoC, but only also on external GPIO controllers you had a unique kernel white number for each GPIO so you need to Hack to know what was a white GPIO number to be used by driver. So it was okay in 2008 when you had like 20 GPIOs But in nowadays as you see like the tegra ones when you can have we can have 200 GPIOs In 20 controllers, it's much more complex and it's it it will be nearly Unimplementable at the time so This technique numbering was really made it really limited So it was replaced in the time by you the new implementation Called GPIO D. So GPIO D It's it's named like this for GPIO descriptor it was the it was a So this new framework Use a descriptor for each GPIO pin in fact instead of you still have an unique number But this unique number is not the the the main processing Component of the framework the framework works with a GPIO desk. So you can have a corresponding correspondence with between a number and a GPIO desk But internally it is only GPIO desk So the consumer now only knows GPIO desk for example and not a number, but you still have Compatibility with the legality as I think at the first with numbers But it's not the main The main idea that drives the framework anymore So you can still use the legacy API even if Linus will age remove some features At every reason But now you have a directory we for example consumer h which are designed only for drivers So drivers should only use the consumer h which is the same as the pin control in fact Pin control as the same split between the consumer functions and the driver and system functions so You have driver.h that is only for GPIO controller drivers and Consumer.h which are for the consumers for the other drivers then it GPIOs to To make for the future for them driver.h Here's an example how to how to registrate a new controller So basically it would need a name for example But the main callbacks of the controller are Direction output Get and set With these three functions You have the main callbacks of the controller. So The core we call will call direction output output when an input when an output mode is requested Get value when the driver of the consumer wants to get the actual value on the on the pad and set to set an output value and The other are base base is a legacy because in the time When you didn't didn't have a proper framework You need to say at which what was the start number of your controller For example for the main controller, it was 0 for the external controller It was 100 and 400 and so on With the new framework, you can still set your base for legacy implementations But for for new modern project, you set minus one saying put me anywhere because We don't need to have fixed number for GPIOs and Number GPIO for to say what are what are the number of GPIOs on the system and finally GPIO chip add data which will which will will register the device to the framework On the other side You have the consumer.h and I will only show how it's Linked with device tree, but with ICP is probably the same For a CPI so for example, let's Look to a simple audio amplifier, which is the most basic Node which only has a GPIO To enable the amplifier So if you look at the node You have first of all the name of the attribute which is which is enable GPIOs so the enable is the function name of the GPIO And you can have multiple GPIO For example, the most of the most used names are Reset GPIOs Shustern GPIOs, but you need to respect the function name GPIOs is the new bindings you must use and In the attribute you have for this sample first of all the PANDAL of the GPIO controller Secondly a number that defines the offset It is completely controller by some specific Here it's for amlogic so see so we have Detail bindings header that define this one But for example some from some with some very complex so see we have a macro Where you can you set the which bank and which position on the So on the package You have the pin and finally for the third one is the GPIO flags So what are GPIO flags? So the GPIO flags they express What are the characteristics of the GPIO on on the system and on the How it's interconnected on the board? for example The bit zero which express What is the actual polarity of the GPIO? when When At each which level the as a function is active for example for reset Often you it will be active low So for that active low for enable for example enable it's active high. So you put active high And you have other defines for push pull which will default Open source up and rain like we saw on the hardware the description You have An other specific option for suspend resume and pull up pull down Pull up pull downs can be set ever GPIO often is done in the pin controller in fact So on the consumer side the driver only need to do two calls to use a GPIO So for example simply GPIO GPIO get With the name of the GPIO lock here enable the name of the function and an optional flag Which is which is says how the GPIO must be initialized It says now here we need we want to enable But we want it to be a default to low. So for example, we don't we wanted to be disabled Probe of the device and later We will set the value. So set value 01 So the DT flags will invert automatically the polarity for example So if you set GPIO active low for example, and you do GPIO set one The the framework we set to GPIO to zero so This must be taken in account when you write to your the DT bindings and the driver you you must know how in you want the GPIO to be defined as you want to The active polarity to be taken in account or not So for example for active low if you pass zero to set value, it will be set one and zero in the reverse so In terms of relationship in with pink control GPIO pink control was designed to to take in account GPIO in fact you can link the pin controller to the GPIO controller because in fact in some SOS you you have a common hardware for pin controlling and GPIO so Often you will need to we have a single driver in fact for both Not a problem. It's it's it's designed like that so and On other design you have a different IP for a pin control and GPIO so you can specify what ranges Of pick controller and led by the GPIO controller So for example, you can have a single pin controller for the whole SOC, but different GPIO controllers for example and In DT or in the driver, you can say okay pin 0 to 10 It's this is a GPIO controller pin 11 to 20 this GPIO controller so everything it will go through the pin controller IPI and When you request The GPIO for example it will it will request the mode the GPIO mode in the pin controller This is really handy in fact So thank you for listening for this introduction you can scan the QR code for the slides and I'll be happy to answer to all your questions in the chat