PWM overview

Revision as of 08:41, 10 January 2019 by Frq09470 (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)


Template:ArticleMainWriter Template:ArticleApprovedVersion



1 Article purpose[edit]

The purpose of this article is the following:

  • introduce PWM (pulse width modulation) Linux® Framework
  • provide general information of PWM
  • describe the main components and stakeholders
  • give examples of PWM usage:
    • user space (sysfs) usage
    • kernel space (API) usage

2 PWM overview[edit]

PWM sysfs interfacePWM kernel interfaceSTM32 TIM Linux driverSTM32 LPTIM Linux driverSTM32 TIM internal peripheralSTM32 LPTIM internal peripheral
PWM Implementation architecture

Template:WarningImageMapOverlay

2.1 Component description[edit]

  • PWM user (User space)

The user can use PWM sysfs interface, from a user terminal or a custom application, to control PWM device(s) from user space.

  • PWM user (Kernel space)

User drivers can use PWM API to control PWM external device(s) from kernel space (such as back-light, vibrator, LED or fan drivers).

  • PWM framework (Kernel space)

The PWM core provides sysfs interface and PWM API. They can be used to implement PWM user and PWM controller drivers.

  • PWM drivers (Kernel space)

Provider drivers such as STM32 TIM Linux driver and STM32 LPTIM Linux driver that expose PWM controller(s) to the core.

  • PWM hardware

PWM controller(s) such as TIM internal peripheral[1] and LPTIM internal peripheral[2] used to drive external PWM controlled devices.

2.2 API description[edit]

Documentation on PWM interface can be found under kernel Documentation/pwm.txt

2.2.1 Kernel PWM API[edit]

The main useful user API are the following:

  • devm_pwm_get() or pwm_get() / pwm_put(): this API is used to look up, request, then free a PWM device.
  • pwm_init_state(), pwm_get_state(), pwm_apply_state(): this API is used to initialize, retrieve and apply the current PWM device state.
  • pwm_config(): this API updates the PWM device configuration (period and duty cycle).
  • ...

2.2.2 Sysfs interface[edit]

In addition to Documentation/pwm.txt[3] details on ABI are available in Documentation/ABI/testing/sysfs-class-pwm[4].

3 PWM configuration[edit]

3.1 Kernel configuration[edit]

Activate PWM framework in the kernel configuration through the Linux menuconfig tool, Menuconfig or how to configure kernel (CONFIG_PWM=y):

Device Drivers  --->
   [*] Pulse-Width Modulation (PWM) Support  --->

Activate PWM drivers for STM32 PWM drivers: STM32 TIM Linux driver and/or STM32 LPTIM Linux driver

3.2 Device tree configuration[edit]

  • PWM generic DT bindings:

PWM DT bindings documentation[5] describes device tree properties related to standard PWM user nodes and PWM controller nodes.

  • Detailed DT configuration for STM32 internal peripherals:

TIM device tree configuration and/or LPTIM device tree configuration

4 How to use PWM[edit]

PWM can be used either from the user or the kernel space.

4.1 How to use PWM with sysfs interface[edit]

The available PWM controllers are listed in sysfs:

$ ls /sys/class/pwm
pwmchip0

The number of channels per controller can be read in npwm (read-only)

$ cd /sys/class/pwm/pwmchip0
$ cat npwm
4

Each channel is exported (requested for sysfs activation) by writing the corresponding number in 'export'.

As an example, proceed as follows to export the first channel (e.g. channel 0):

$ echo 0 > export
$ ls
device  export  npwm  power  pwm0  subsystem  uevent  unexport

The period and duty cycle must be configured before enabling any channel.

As an example, proceed as follows to set a period of 100 ms with a duty cycle of 60% on channel 0:

$ echo 100000000 > pwm0/period
$ echo 60000000 > pwm0/duty_cycle
$ echo 1 > pwm0/enable

The polarity can be inverted or set to normal by using the polarity entry:

$ echo "inversed" > pwm0/polarity
$ cat pwm0/polarity
inversed

$ echo "normal" > pwm0/polarity
$ cat pwm0/polarity
normal

4.2 How to use PWM capture with sysfs interface[edit]

PWM capture is available on some PWM controllers such as TIM internal peripheral[1] (see TIM configured in PWM input capture mode ).

# First export a channel (e.g. 0), then capture PWM input on it:
$ cd /sys/class/pwm/pwmchip0
$ echo 0 > export

$ cd pwm0
$ ls
capture  duty_cycle  enable  period  polarity  power  uevent

$ cat capture
10000 1002               # capture result is in nano-seconds, e.g.: 100KHz, 10% duty cycle

4.3 Example of PWM usage with kernel PWM API[edit]

Several in-kernel drivers use kernel PWM API. Below a few examples:

5 How to trace and debug the framework[edit]

5.1 How to monitor with debugfs[edit]

PWM usage can be monitored from debugfs 'pwm' entry. For example:

$ cd /sys/kernel/debug/
$ cat pwm
platform/44000000.timer:pwm, 4 PWM devices                                                               <-- One timer instance exposes 4 PWM channels.
 pwm-0   (sysfs               ): requested enabled period: 1000000 ns duty: 500000 ns polarity: normal   <-- Channel 0 has been exported, enabled and configured via sysfs
 pwm-1   ((null)              ): period: 0 ns duty: 0 ns polarity: normal
 pwm-2   ((null)              ): period: 0 ns duty: 0 ns polarity: normal                                <-- Other channels aren't used currently
 pwm-3   ((null)              ): period: 0 ns duty: 0 ns polarity: normal

6 References[edit]

  1. 1.01.1 TIM internal peripheral
  2. LPTIM internal peripheral
  3. Documentation/pwm.txt, Linux PWM interface overview
  4. Documentation/ABI/testing/sysfs-class-pwm, Linux PWM Application binary interface
  5. Documentation/devicetree/bindings/pwm/pwm.txt, PWM DT bindings documentation
  6. drivers/input/misc/pwm-beeper.c , Example to use kernel PWM API
  7. drivers/input/misc/pwm-vibra.c , Example to use kernel PWM API