^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) ======================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) Pulse Width Modulation (PWM) interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) ======================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) This provides an overview about the Linux PWM interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) PWMs are commonly used for controlling LEDs, fans or vibrators in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) cell phones. PWMs with a fixed purpose have no need implementing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) the Linux PWM API (although they could). However, PWMs are often
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) found as discrete devices on SoCs which have no fixed purpose. It's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) up to the board designer to connect them to LEDs or fans. To provide
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) this kind of flexibility the generic PWM API exists.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) Identifying PWMs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) ----------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) Users of the legacy PWM API use unique IDs to refer to PWM devices.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) Instead of referring to a PWM device via its unique ID, board setup code
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) should instead register a static mapping that can be used to match PWM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) consumers to providers, as given in the following example::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) static struct pwm_lookup board_pwm_lookup[] = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) PWM_LOOKUP("tegra-pwm", 0, "pwm-backlight", NULL,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) 50000, PWM_POLARITY_NORMAL),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) static void __init board_init(void)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) pwm_add_table(board_pwm_lookup, ARRAY_SIZE(board_pwm_lookup));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) Using PWMs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) ----------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) Legacy users can request a PWM device using pwm_request() and free it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) after usage with pwm_free().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) New users should use the pwm_get() function and pass to it the consumer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) device or a consumer name. pwm_put() is used to free the PWM device. Managed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) variants of these functions, devm_pwm_get() and devm_pwm_put(), also exist.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) After being requested, a PWM has to be configured using::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) int pwm_apply_state(struct pwm_device *pwm, struct pwm_state *state);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) This API controls both the PWM period/duty_cycle config and the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) enable/disable state.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) The pwm_config(), pwm_enable() and pwm_disable() functions are just wrappers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) around pwm_apply_state() and should not be used if the user wants to change
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) several parameter at once. For example, if you see pwm_config() and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) pwm_{enable,disable}() calls in the same function, this probably means you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) should switch to pwm_apply_state().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) The PWM user API also allows one to query the PWM state with pwm_get_state().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) In addition to the PWM state, the PWM API also exposes PWM arguments, which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) are the reference PWM config one should use on this PWM.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) PWM arguments are usually platform-specific and allows the PWM user to only
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) care about dutycycle relatively to the full period (like, duty = 50% of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) period). struct pwm_args contains 2 fields (period and polarity) and should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) be used to set the initial PWM config (usually done in the probe function
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) of the PWM user). PWM arguments are retrieved with pwm_get_args().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) All consumers should really be reconfiguring the PWM upon resume as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) appropriate. This is the only way to ensure that everything is resumed in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) the proper order.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) Using PWMs with the sysfs interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) -----------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) If CONFIG_SYSFS is enabled in your kernel configuration a simple sysfs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) interface is provided to use the PWMs from userspace. It is exposed at
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) /sys/class/pwm/. Each probed PWM controller/chip will be exported as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) pwmchipN, where N is the base of the PWM chip. Inside the directory you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) will find:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) npwm
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) The number of PWM channels this chip supports (read-only).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) export
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) Exports a PWM channel for use with sysfs (write-only).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) unexport
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) Unexports a PWM channel from sysfs (write-only).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) The PWM channels are numbered using a per-chip index from 0 to npwm-1.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) When a PWM channel is exported a pwmX directory will be created in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) pwmchipN directory it is associated with, where X is the number of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) channel that was exported. The following properties will then be available:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) period
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) The total period of the PWM signal (read/write).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) Value is in nanoseconds and is the sum of the active and inactive
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) time of the PWM.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) duty_cycle
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) The active time of the PWM signal (read/write).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) Value is in nanoseconds and must be less than the period.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) polarity
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) Changes the polarity of the PWM signal (read/write).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) Writes to this property only work if the PWM chip supports changing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) the polarity. The polarity can only be changed if the PWM is not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) enabled. Value is the string "normal" or "inversed".
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) enable
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) Enable/disable the PWM signal (read/write).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) - 0 - disabled
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) - 1 - enabled
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) Implementing a PWM driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) -------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) Currently there are two ways to implement pwm drivers. Traditionally
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) there only has been the barebone API meaning that each driver has
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) to implement the pwm_*() functions itself. This means that it's impossible
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) to have multiple PWM drivers in the system. For this reason it's mandatory
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) for new drivers to use the generic PWM framework.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) A new PWM controller/chip can be added using pwmchip_add() and removed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) again with pwmchip_remove(). pwmchip_add() takes a filled in struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) pwm_chip as argument which provides a description of the PWM chip, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) number of PWM devices provided by the chip and the chip-specific
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) implementation of the supported PWM operations to the framework.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) When implementing polarity support in a PWM driver, make sure to respect the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) signal conventions in the PWM framework. By definition, normal polarity
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) characterizes a signal starts high for the duration of the duty cycle and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) goes low for the remainder of the period. Conversely, a signal with inversed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) polarity starts low for the duration of the duty cycle and goes high for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) remainder of the period.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) Drivers are encouraged to implement ->apply() instead of the legacy
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) ->enable(), ->disable() and ->config() methods. Doing that should provide
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) atomicity in the PWM config workflow, which is required when the PWM controls
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) a critical device (like a regulator).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) The implementation of ->get_state() (a method used to retrieve initial PWM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) state) is also encouraged for the same reason: letting the PWM user know
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) about the current PWM state would allow him to avoid glitches.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) Drivers should not implement any power management. In other words,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) consumers should implement it as described in the "Using PWMs" section.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) Locking
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) -------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) The PWM core list manipulations are protected by a mutex, so pwm_request()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) and pwm_free() may not be called from an atomic context. Currently the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) PWM core does not enforce any locking to pwm_enable(), pwm_disable() and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) pwm_config(), so the calling context is currently driver specific. This
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) is an issue derived from the former barebone API and should be fixed soon.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) Helpers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) -------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) Currently a PWM can only be configured with period_ns and duty_ns. For several
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) use cases freq_hz and duty_percent might be better. Instead of calculating
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) this in your driver please consider adding appropriate helpers to the framework.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags