 Hello everyone, a very warm welcome to this session. I am Thamsil Shams, currently working as senior engineer in Samsung semiconductor India. Today I will be talking about PWM subsystem and its usage in embedded devices. We will look how the PWM subsystem is present in the Linux kernel and how it is used in different devices. Let's get started. This is the agenda for today. First we will see what is PWM, how does it works. Then we will get an overview of PWM subsystem in the Linux kernel. Then we will see that PWM driver implementation in the Linux kernel. Then we will see the two ways of driver implementation. One of them is the generic PWM framework and the other one is legacy PWM driver framework. Legacy PWM driver framework we will discuss based on the Samsung PWM driver. After that we will see how to use the PWM subsystem with the CCFS interface. That is how to use the PWM subsystem from the user space. Then at the last we will see the different use cases of PWM in details. Let's start our presentation. PWM stands for pulse width modulator. It works on the principle of modulating the pulse width. That is some method of changing how long the square width remains on. It is also a technique of delivering partial power to the load. It is done via the digital means. Basically we control the analog devices that how much power needs to be given to that. We do it via the digital means. It can also operate like a switch. Since there is continuous on and off in the PWM signals as we can see where the waves then so it also acts like a switch in many of the control circuits. So based on whatever the principles of the techniques PWM uses, it has found its use in the LED bulbs, in the LCD back lights, in the vibrators and cell phones, in the fan coolers, in the inverters, in the motors, in the robotics industry and etc. We'll see these use cases in details afterwards. Before moving on to the PWM subsystem, we need to look at few of the keywords of PWM signals. One of them is modulating frequency. So modulating frequency is the ratio at which the on and off is switched in the PWM signal. It affects the average power being transferred to the load. And also if we have some specific use case or we have some usage according to which we want to set up a modulating frequency, we can do the same. Then the next topic is duty cycle. So duty cycle is the ratio of total active time by the total time period of the PWM signal. So how much time the wave remains on that's time period and by total time period of on plus time period of off. And it is represented in percentage. It affects the average power being transferred to the load. And based on our use case, we can adjust our duty cycle. As you can see in this diagram. There is a wave, which has its time, it's remain on and the time till which it remains off. So the time till it remains on is T on and the time till it remains off is T off. And the formula for duty cycle is T on by T on plus T off. We can see that here the system on is slightly bigger than T off the duty cycle will be more than 50%. Also, you can see as there are three different pulse with the one is for 50% duty cycle, we can see that T on is equal to T off in those. When the duty cycle percentage is greater than 50% that is around 75% it is that T on is greater than the T off. And when the duty cycle is less than 50% to be specific when it is 25% we can see T on is less than T off. Also we can see like when the duty cycle value changes how the power which is being supplied to the load differs by the brightness of the bulb. If you see in the 10% duty cycle the bulb is very deep for 40% duty cycle is a slight brightness in the bulb. Then for 80% duty cycle the brightness of bulb is very much. So these was how the duty cycle affects the PWM signal. So these are some of the use cases of PWM as I said earlier it's used in the fans it's used in the LED bulb is also using the telecommunication industry. It's used in the robots and it's used in sound amplification. So we will see for all of these use cases in details later in the slides now that just given an overview of those. Yeah, so this is the new topic it's PWM subsystem in kernel. Here we will see the how the PWM subsystem is implemented in the Linux kernel different types of APIs in the system and how to identify the PWM that is to before doing device driver binding. How do we identify the PWM which helps us to do the driver device driver binding. So first type of API is in kernel APIs in kernel APIs are the PWM kernel driver API. These APIs are the basically the main APIs with the PWM devices are using to be functional. These are present in the core file of PWM that is core dot seen the drivers PWM directory. And also there are many platform specific driver files for PWM so though all those IPs APIs in those files are having in kernel API is only one of those example is Samsung PWM driver file, which is PWM Samsung dot see it's also present the drivers PWM directory. We will see this in kernel API is in details in the PWM driver implementation section. Then the next type of API is our user space API. These are the APIs which helps us to use the PWM device from user space. These are present as CFS interface in the Linux kernel. The file for this is CFS dot see in the drivers PWM directory. And also when the kernel is booted, this user space API is commands are exposed at CIS class PWM directory. We will see this in details in the using of PWM subsystem with CFS interface section. Okay, so now before moving to the driver implementation part, we need to take a look at a small topic called identifying PWM. Basically this topic is related to how do we do the device driver binding of PWM devices in doing the probe. So there are two ways of doing so the legacy approach of doing so is using the unique ID which refers to the PWM device and we try to match this unique ID. We present within the board files or the DT files and we do the device driver binding is in there. Another approach to do is like whichever is what this current approach is being used is to that the driver files contain some kind of static mapping. And this helps us to match the PWM device and driver and help us to have the device driver binding. So now we will see the PWM driver implementation how the driver implementation is there in the Linux kernel. So again there are two ways to implement PWM driver one is the legacy approach in this the APIs in the files are very platform specific or border consumer specific. Those have their own APIs like for Samsung PWM driver you can see it has PWM Samsung request PWM Samsung config. So these do a similar same kind of use one only one kind of use and we cannot have multi functionality in those API. But there is another form of dive implementation which is generally PWM framework it gives us the flexibility to use PWM device in multiple use cases. The driver which is implemented for our use we can in those APIs we can use these APIs by we can call these APIs and have our operation done. The few examples are PWM request PWM config then there is PWM chip add then there is PWM chip remove and there are some generic structure also. Similar to this there are APIs and structures in the platform specific APIs also we will perform specific files also sorry because we will see both in the details this generic PWM framework. First we will see then we will see the legacy driver implementation but before that we will see how why this generic PWM framework is used before this platform specific files nowadays. So there are basically two reasons why to use that one is to provide flexibility. So as I said flexibility is when that PWM device is kind of discrete device and it has no fixed purpose it has multi purpose it can be used in different way. So it is directly up to the designer both designer how he wants to use the PWM device. So when we have three to four different types of use cases in our for PWM device we can use the generic PWM APIs that it gives us the flexibility to use it in different phase. But in legacy approach we don't have that flexibility and we can use it on your single way. Then there another reason of it is locking issue. So as I can say that the mutex locking is there for request and free functions in the platform specific files, but for enable disable config this mutex is not enabled in the platform specific driver for the legacy approach. So it doesn't help us to have multiple PWM device to be using it as there can be deadlock or some kind of locking issue because one device may be using it but at the same time another device want to use that same. So in this to avoid this issue, the generic PWM framework comes and which enables us to have multiple PWM device to be used in the same board. So we have seen the two different ways in basics how to do dive and we have seen how why this generic PWM framework is used before legacy driver implementation nowadays. Now we will see the generic PWM framework in details. It's different APIs, how to use those APIs and then the different generic structures of PWM generic framework. Then like so, so the first thing we do for PWM device after probe is we request for the PWM device. So before configuration of PWM device or for use of PWM device we need to request for PWM device. So the first there are few APIs for requesting those are PWM request PWM get off PWM get PWM request was used earlier but nowadays it is deep located so it is not used nowadays. Now the next API is PWM get. So this PWM get does the request of PWM device via lookup so by lookup I meant that first it will go and look up into the data table for the data file for the node. And if it doesn't get it there then it will go to the file which is given us to given to us by the board files the tables which is given to us by the board files. The difference here between PWM request and PWM get is that only that in PWM request we only go and request look up into the data file, but in PWM get we also go and check into the tables which is provided by the board files. That is the difference and that's what PWM get is nowadays used. Another API called off PWM get so off PWM get helps us to do the same thing which PWM get it does the lookup in both the data file as well as the table in the board file but it does it via the PWM framework. So this PWM get uses a very generic kernel framework of lookup but this off PWM uses the PWM framework the by PWM framework I meant the using the PWM as property so we mentioned some PWM as property in the node, which has its own p handle and index value. So based on those values and the configurations we provide, we do this lookup via off PWM get. And then once we have the PWM device, then we can configure it as per our need then we can use it we can get our output. And once the use is done, and the driver detachment is done we can free the PWM device using PWM free API or PWM put API. So this PWM free API similar to PWM request was used earlier but now it is deprecated. Now what is mostly used API is the PWM put APIs. So there are a few other variants of PWM get like based on our use cases are based on our management of the PWM device we have few variants of PWM get one of those variants is DevM PWM get. So it is a resource managed version of PWM get by resource managed I mean that if you get the PWM device if you request for the PWM device and we get that. After use the driver detachment happened. So when we have using DevM PWM get it will automatically release the device after the driver detachment we don't need to explicitly call the free function like PWM put a PWM free. That's the difference between DevM PWM get and PWM that's the basic meaning of resource managed. Then there is DevM off PWM get again this is the resource managed version of off PWM get. This function is same and it gives us the resource managed device. Then there is another API called DevM FW node PWM get it returns the resource managed PWM device from the firmware node. So again this firmware node is the there is a firmware table present in the DT file or in the board file. So those from where they will have some nodes for different devices so if you want to get the node for the PWM device from the firmware table we use this API to get the PWM device from firmware. Moving forward, we will see the different structure now after that we will again see few other APIs on but since there was talk about the PWM device, we will see the structure. So when we request we get the PWM device. So that PWM device is the struct PWM device it represents the PWM channel object. Again there are multiple fields for it there is label which mentions the name of the PWM device then there is flags field which will shows as the flag associated with the PWM device. Then there is SW PWM field which represents the per chip relative index of the PWM device. Then there is PWM field it represents the global index of the PWM device. Then there is chip field, which is the variable for PWM chip structure, we will see the structure PWM chip structure next in the presentation then there is chip data variable which stores the private chip data associated with this channel. So, since in one chip there are multiple channels and if a specific channel has some data related to that chip which is unique to other channels then those data are stored in this chip data. Then there is arcs variable for struct PWM arcs. Again this PWM arcs is the PWM argument we will again look into this in further in the slides. Then there is PWM state structure which have its two field here we will check into what is PWM state. So state is the current applied state or the last applied state and the last is the last implemented state. So it helps us for debugging we will check in details about PWM chip, PWM arcs and PWM state. So yeah first we will check into PWM chip. So this PWM chip represents the PWM controller of the chip. It has its own field like depth which is the device pointer then there is ops field it represents the different callbacks of the PWM controller like either bit add, remove, config, probe whatever be the callbacks which is provided. There is a base field which represents the number of the PWM control then there is NPWM it represents the number of channels supported by this chip and there are many more fields which we directly don't use in the driver but it has its internal using the PWM thread. So yeah now we will see how to configure PWM state and what are the structures used in those configuration. There is a API called PWM applied state it helps in the configuration of PWM it helps us to configure the period and date cycle and then control it. It also helps us to control the enable and disable state of the PWM device. Also it controls the usage of power setting. Again this PWM applied state is a combination of three different individual APIs called PWM config, PWM enable and PWM disable. This PWM config is related to the configuration of period and duty cycle or the user control of usage power setting. This PWM enable is for control of enable state and this PWM disable is to control the disable state. Again we can use this as individual APIs but if we are using it in the same flow as PWM config, PWM enable and PWM disable it's better to use PWM apply state because it gives us an atomic context while using the PWM device. Also when we want to get the current applied state we can get it via PWM get state. So here again as I said the structure used here is PWM state. It represents the state of a particular PWM channel it has four fields there is period which represents the PWM period in nanoseconds then there is duty cycle which represents the PWM duty cycle in nanoseconds. Then there is a polarity field it represents a PWM polarity by polarity I meant it's either normal polarity or inverse polarity by normal polarity it means the signal is normal in the inverse polarity is mean the signals are inverted on becomes off or becomes on some that kind of thing. Then there is enabled state which variable which shows us the status of enabled state whether the PWM channel is enabled or disabled state. Again, there is another API which exposes the PWM arguments, this PWM arguments is the stuck PWM arcs. It's a reference PWM config to be used by reference PWM config. I can say that the configuration which we do during the initial probe that is stored in the PWM arcs, it also helps us in reconfiguration during resume part. And when we want to retrieve this PWM arguments we can use this PWM get arcs API to get the PWM argument. Now there is one difference between PWM arcs and PWM state, not one different the basic difference is that PWM state represents the current configuration of PWM whatever state we have applied last whatever configuration we have done that is stored in the PWM state structure but this PWM arcs stores the initial configuration of the reference configuration of the PWM device which is initially set. It cannot be changed once it is set during the probe part. Also, when there is one more thing which is forward to PWM state it was that this PWM state gives us the last applied software implemented state maybe the hardware implemented state may differ from the software implemented state if some error happens during the PWM applied state call, and there is no such APIs in the current framework to get the actual hardware implemented state. I missed that earlier, sorry for that. So that was the generic PWM framework we saw the different APIs and different structures. Now the same thing we will see in the legacy PWM driver implementation also this legacy PWM driver implementation will be based on Samsung PWM driver. Yeah, so the Samsung PWM driver file is PWM Samsung dot C it is present in the drivers PWM directory. So now we will see the PWM arguments in Samsung driver file. The first is the Samsung PWM channel. It represents the PWM channels details. Again, there are three fields one is period NS it stores the period of PWM signal in nanoseconds and there is duty NS stores the duty time of the PWM. And then there is TNS which stores the rate of timer of PWM signals based on the current configuration it again stores it in nanoseconds. Then there is another structure called Samsung PWM chip. It represents the data of the PWM chip. There are variables fields in them like there is a field for Samsung PWM chip the generic API also the generic structure of PWM chip also has a chair. So there may be some details which is stored in the chip variable and we don't need to again explicitly define it in this structure also then there is Samsung PWM variant field it represents the local hardware variant of PWM it stores a detail about different hardware configuration of PWM. Then there is a inverter mask and disabled mask field inverter mask stores the current inverter status of each channel disabled mask stores the current enable or disabled status of each PWM channel. Then there is a base field to store the base address of the PWM device. Then there is a base clock pointer it stores the pointer for the clock which is running the PWM timer or the PWM device. Then there are two other clock pointers called TCLK0 and TCLK1 these are for the external clocks if the PWM device supports such clock there will be some details related to them otherwise it is error pointer. Now we will see different APIs just as like in the generic PWM framework there are APIs here in legacy framework which does the operation which we do either generic PWM framework also. So for probe there is PWM Samsung probe then to remove the PWM device there is a API called PWM Samsung remove and during the power management for resume there is a PWM Samsung resume API. Now there was request and free function for in the generic framework similar to that the request and free function in the legacy implementation also there is PWM Samsung request and PWM Samsung free respectively for doing request and free of device. Then the more one of the most important APIs is PWM Samsung config this helps us to configure the PWM sets the PWM duty cycle and the period and is also updates the PWM SFR as per our need and the configuration. So now there is another few other APIs like PWM Samsung enable it enables or starts the PWM signal there is PWM Samsung disable which disable or stops the PWM signal to help or to support these APIs there are a few wrapper functions in the legacy dive implementation. These wrapper functions may be there in the generic framework also. So one of those APIs is PWM Samsung set polarity it will set the polarity either be it in the normal state or be it in the inverse state. And also there is another API called PWM Samsung manual update it helps us to manually update the configuration or SFR of PWM device as per our need or at the end of one of the cycle. There is the current implementation if you want to support the manual update. Yeah, so we have till now looked upon the PWM driver implementation both phase in the generic PWM framework and both in the legacy. So now this diagram represents how the Samsung specific PWM structure are represented associated with the generic PWM structure. So this Samsung PWM chip is the main structure for Samsung PWM chip. It is in its field data from the Samsung PWM variant structure, which represents the local hardware variant. And again this Samsung PWM chip is associated with the PWM chip is the generic PWM chip structure. So it has many of the fields so it can directly use these fields for its use. And this PWM chip has its one to many relationship the PWM device structure as one chip may have multiple channels so it has a one to many relationship and this PWM device which represents the channel of PWM It generates the state data from the PWM state data from the PWM state structure. So this is the overview of the relation between the platform specific PWM structure and the generic PWM structure between them. Yeah, and also we have seen the working of PWM then we have seen an overview of the PWM system there was two kind of APIs Incarnal API as user space APIs. Then we check the identification of PWM how do we do the device binding in the PWM subsystem we got into the details of Incarnal API is in the PWM driver implementation section in the PWM driver implementation we saw. Two types of driver implementation one was generic PWM framework. We saw that in details in the legacy PWM driver implementation also we saw that in details. You also saw the relation between the different structures of platform specific if files and the generic PWM file. So what we saw by the generic framework is has an advantage over the legacy approach. Now, the other type of API is that user space API is we will see how those are used from the user space. So we have the CFS interface, so very simple PWM CFS interface to be using that we need to enable the config CFS in the configuration file. Then, once it is enabled and the Linux is booted that CFS is exposed at CIS class PWM directory. And the PWM chips which are pro are exported as PWM chip and in this directory CIS class PWM and is the base value as mentioned in the PWM chip structure. So this can be 012 based on the number of PWM chip. So this is how it is represented CIS class PWM PWM chip zero CIS class PWM PWM chip one. Then inside this directory we have few properties called NPWM export and export. This will help us to use the PWM device from user space. This NPWM gives us the number of PWM channel supported by this chip. When we try to do cat NPWM show the number of channel supported. This is a read only property. Then there is an export property which helps us to export the PWM channel the default PWM channel which you want to use for CFS use by then there is an export property. It helps us to unexport the PWM channel from CFS after its use. Now, when we export a PWM channel, a PWM X directly will be created in the PWM chip directory. This X will be from zero to NPWM minus one. NPWM is the number of channel supported. So again this inside PWM X there will be a number of properties called period. There will be duty cycle, polarity, enable and capture. This polarity helps us to set the total period of the PWM signal. The value should be nanoseconds and it is a read write property. Then there is duty time cycle. It helps us to set the active time of PWM signals. Again the value should be nanoseconds and it is a read write property. Then there is a polarity property. It helps us to set the polarity of PWM signal. Either it can be normal or it can be inverse. Again, it's a read write property. Then there is an enable property which helps us to enable or disable the PWM signal. If we write one to the enable, it will enable the PWM signal. If you write zero to the property, it will disable the PWM signal. Then there is a capture field which helps us to give the details about PWM configuration. Whatever the current configuration of PWM is there, it helps us to get that detail. This capture is again read only property. The value cannot be written by this. So now we will see how these commands are used from the users. So to get the number of channels supported, we write cat, sys class, PWM, PWM chip, zero and PWM. This PWM chip zero can be variable. It can be one, two, three. Again, to export the PWM channel, we write equal zero to the sys class, PWM, PWM chip zero and the export property. Then once the PWM channel is exported, we will get a directly something like that. If the channel is zero, we will get a directory named PWM zero inside PWM chip. So to set the period and duty cycle, we write the values in the nanoseconds to the period and duty cycle. Also, the duty cycle value has to remain less than period, otherwise it will generate an error. Now to set the polarity, we either write normal or write inverse to the polarity property by this command. And by default, the polarity is normal, but if you want to change it to inverse, we can do that. And once we change to inverse, after that, if you want to have the normal polarity, we can change that also. One thing to take a note here is like to set the polarity or to set the period and duty cycle. The PWM channel should be in the disabled state. We cannot do this in the enable state. If we try to do that in the enable state, we will get an error from the linear scandal. To enable the PWM timer, we need to write equal one to the enable property inside PWM zero. It will enable the PWM timer and we can get the output in our output device. And to disable the PWM timer, we write zero to the enable property. And again, after use via the CFS interface, if you want to unexport the PWM channel, we can do it via equo zero. This class PWM, PWM chip zero, unexport command. Yeah, so we saw the whole PWM subsystem overview. We saw the details, the driver implementation, how the driver implementation is done, how there is an interrelation between the structures of the different types of driver implementation. Then we saw the use of PWM device from the user space by the CFS interface. Now we will see the few of the use cases of PWM devices, how those are used in different embedded devices in our industry. So one of its use is in CPUs and GPUs. The PWM fans are used in the CPU coolers and the GPU coolers. It uses an integrated circuit to control the speed of effect, as there may be a lot of heavy load CPUs and GPUs working so it may get hot some time. So you need some kind of fans or coolers to do that and PWM fans are used in this thing. This PWM fans control when and how much of cooling is needed by the CPU and GPU. Moving forward, it's also fine, it's used in the brightness of bulb and LED. PWM is a very common method of dimming LED and bulb lights. It works on the principle that we rapidly switch on and switch off the PWM signal so it kind of creates a pulsing effect which visually make the LED to appear as very steady dim light. This steady dim light brightness variation can be adjusted by, can be like the brightness can be changed by adjusting the percentage of time the light comes, which is done by the adjusting of duty cycle. If we set a very low duty cycle, the brightness of the light will be very low and if we set our duty cycle in a higher range around 70-80, the brightness will be much. And this same principle is being used by different kinds of LCD backlights or backlights also in our laptops or in our mobile keypads and all. Also PWM devices find its use in the switches. In the control circuits to control the on and off switches, the PWM device can be used. It's used in controlling the MOSFET in many of the circuits. PWM device is also used in the telecommunication. So in telecommunication, the usage is based on the pulse width of the PWM device. So we encode some values in the source and then we decode the values in the destination. And this, how does it work is like we continuously send a clock signal with a fixed pulse width and based on the pulse width received for the PWM signal, we decode what is the information there. So if the PWM signal pulse width corresponding to the clock pulse width is nil, then the value received is zero. And the pulse width is same, the value received is one. And the pulse width is twice the value received is two, but it is four times the value received is four and so on. If it's three times, it will be three. And one more important thing is the, here the PWM signal is the information as well as the carrier width, both. So that is one of the things of the advantage, but yeah, it helps the use of clock, PWM clock signal also as a carrier. Also PWM device is used in the robotics industry so in robots to control its speed and its movement, motors are used and these motors are somehow controlled by the PWM device. It's not like PWM device are used in large scale in the robots, it's a very small scale but it's a study like it's a research, there can be research on this, how to use PWM device very much because PWM device is very inexpensive. Another use of PWM device is audio effects and amplification. So there are many soundtracks in the video games which needs amplification or which needs to give the audio effects. So PWM device is for its use here. It's also fine, it's used in the music synthesis. When we see a PWM signal output of the PWM signal, we will see that it's a difference between two saw through the threads. One of the toss with it waves is inverted. So there will be some high level values and some low level values. So when we do a ratio of high levels wave to the low level wave and modulate it with a low frequency oscillator, we will get a sound amplification. And this sound amplification, timbral variation can be produced by varying our duty cycle. So if you vary the duty cycle, the amplification, timbral variation can be varied. As I said earlier, the soundtracks of video games uses the PWM device. So the duty cycle range for those PWM devices normally between 12.5% to 50%. Also PWM devices find its use in the inverters, which is used to control the inverter voltages, which is used in many applications like AC motor and other special motors also. Also the device efficiency or the inverter efficiency depends on the harmonic content of the PWM signal. The way the PWM signal is doing the harmonic motion and what's the harmonic property that affects the inverter efficiency. This is a very simple circuit of inverter and how the PWM device is or controller is connected to that device. So we have come to the end of the presentation. We discussed what is PWM, how the PWM is used. Then we saw the PWM subsystem overview. Then we went into details regarding the PWM driver implementation to understand the incandell APIs. We saw both types of driver implementation, the generic framework and the legacy framework also. Legacy framework we saw based on the Samsung PWM driver. Then that we took a look in the using of PWM system with CISFS interface, that is from user space. Then after that we got into the details of each use cases of PWM device. So what we can conclude from this short session was that PWM is a very discrete device. It's a very individual device which has no fixed purpose and it can be used in many different ways. And whoever is the board designer of a specific inverter device, it depends on him how he want to use the PWM device and PWM device is very flexible in that nature that it can be used in multiple ways. And that's why PWM devices in nowadays is getting used as an important component in very useful devices like either be it in fan coolers in heavy load CPUs and GPUs, either be it in robotics in transformers and switches in inverters. Intelli communication industry also then is used in the LED bulbs in the LCD back lights in the vibrators of cell phones. And in future it may find its use in other areas also one of those areas can be the medical for medical purpose as we see there are a lot of engineering devices being used in the medical program so maybe PWM device are being currently used or can be used for research purpose yeah but we are hopeful that it can be used. Then again, another advantage is of using PWM devices like one of the basic advantages it is very inexpensive device. And the one of the most important advantage is the PWM subsystem present in a linear scanner so if you are using an OS as linear scanner in an embedded device that there is already implemented and well maintained and very flexible PWM system which is there in the linear scanner so to use a PWM device efficiently we can. So this helps us to use the PWM device efficiently. So that was the presentation. So if you have any questions you can ask and thank you for very much for joining this session. So if you have any questions you can ask.