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


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

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

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

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

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

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