docs: zephyr: add an initial Zephyr PWM doc page

Add documentation for configuring PWM on Zephyr.

BRANCH=none
BUG=b:215168520
TEST=browse on gerrit

Signed-off-by: Fabio Baltieri <fabiobaltieri@google.com>
Change-Id: I11e5ea336e1fe1535a35c4a890cb9eb224e213a9
Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/platform/ec/+/3416229
Reviewed-by: Keith Short <keithshort@chromium.org>
Commit-Queue: Keith Short <keithshort@chromium.org>

2 files changed, 134 insertions, 0 deletions

diff --git a/docs/zephyr/pwm_schematic.png b/docs/zephyr/pwm_schematic.png
new file mode 100644
index 0000000000..1864e514f3
--- /dev/null
+++ b/docs/zephyr/pwm_schematic.png
diff --git a/docs/zephyr/zephyr_pwm.md b/docs/zephyr/zephyr_pwm.md
new file mode 100644
index 0000000000..a1c2ba1129
--- /dev/null
+++ b/docs/zephyr/zephyr_pwm.md
@@ -0,0 +1,134 @@
+# Zephyr EC PWM Configuration
+
+[TOC]
+
+## Overview
+
+[PWM] provides support for PWM setup and control on the platform.
+
+## Kconfig Options
+
+Kconfig Option | Default | Documentation
+:------------- | :------ | :------------
+`CONFIG_PWM` | n | [PWM (Pulse Width Modulation) Drivers]
+`CONFIG_PWM_<platform>` | n | Platform specific PWM driver
+`CONFIG_PLATFORM_EC_PWM` | y if `CONFIG_PWM=y` | [PWM (Pulse Width Modulation) module]
+
+Kconfig sub-option | Default | Documentation
+:----------------- | :------ | :------------
+`CONFIG_PLATFORM_EC_PWM_INIT_PRIORITY` | 51 | [Init priority of the PWM module]
+
+## Devicetree Nodes
+
+PWM channels are configured by enabling the PWM subsystem in the project
+`prj.conf`, setting a phandle reference to higher level driver `pwms` property,
+and enabling and configuring the corresponding PWM controller device node.
+
+For example for a keyboard backlight device:
+
+```
+kblight {
+        compatible = "cros-ec,kblight-pwm";
+        pwms = <&pwm3 0 PWM_POLARITY_NORMAL>;
+        frequency = <2400>;
+};
+```
+
+Property | Description | Settings
+:------- | :---------- | :-------
+`pwms` | PWM phandle, identifies the controller (X), channel (Y) and flags. | `<&pwmX Y flags>`
+`frequency` | PWM frequency, in Hz | `integer (32 bit unsigned)`
+
+The `flags` cell of `pwms` defines the PWM signal properties, valid options are
+listed in the [dt-bindings/pwm/pwm.h], commonly used ones are
+`PWM_POLARITY_NORMAL` and `PWM_POLARITY_INVERTED`.
+
+Any used platform PWM device has to be explicitly enabled and configured, for example:
+
+```
+&pwm3 {
+	status = "okay";
+	clock-bus = "NPCX_CLOCK_BUS_LFCLK"; /* Keep active during low power mode. */
+};
+```
+
+The device node may include any platform specific property, see the
+corresponding bindings files for more details ([nuvoton,npcx-pwm],
+[ite,it8xxx2-pwm]).
+
+## Board Specific Code
+
+None required.
+
+## Threads
+
+PWM support does not enable any thread.
+
+## Testing and Debugging
+
+### Shell Command
+
+Zephyr defines a `pwm` shell command that can be used to change the current PWM
+duty cycle and period.
+
+The command is enabled by setting `CONFIG_PWM_SHELL=y` ([CONFIG_PWM_SHELL]) in the project `prj.conf` file.
+
+Command | Description | Usage
+:------ | :---------- | :----
+`pwm` | PWM shell commands | `pwm <cycles or usec or nsec> <device> <pwm> <period> <pulse> [flags]`
+
+Parameter | Description
+:-------- | :----------
+`cycles/usec/nsec` | The unit of period and pulse (cycles, microseconds or nanoseconds).
+`device` | The PWM device label (for example `PWM_1`).
+`pwm` | The PWM channel number.
+`period` | Requested period of the PWM signal.
+`pulse` | Requested active cycle duration of the PWM signal.
+`flags` | PWM flags (for example `1` for inverted polarity).
+
+For example to set the keyboard backlight (connected to PWM3) to 90%  at 250Hz on Volteer:
+
+`$ pwm usec PWM_3 0 250 225`
+
+## Features using PWM directly
+
+### Keyboard backlight
+
+Kconfig Option | Default | Documentation
+:------------- | :------ | :------------
+`PLATFORM_EC_PWM_KBLIGHT` | n | [PWM keyboard backlight]
+
+This requires defining a node with `compatible = "cros-ec,kblight-pwm"`,
+normally in a separate overlay `keyboard.dts` file, for example on the Volteer
+reference board:
+
+![PWM Example]
+
+The keyboard backlight line is connected to `PWM3` channel 0 (there's only one
+channel per PWM on NPCX), normal polarity:
+
+```
+/ {
+        kblight {
+                compatible = "cros-ec,kblight-pwm";
+                pwms = <&pwm3 0 PWM_POLARITY_NORMAL>;
+                frequency = <2400>;
+        };
+};
+
+&pwm3 {
+        status = "okay";
+};
+```
+
+[PWM]: ../ec_terms.md#pwm
+[PWM (Pulse Width Modulation) Drivers]: https://docs.zephyrproject.org/latest/reference/kconfig/CONFIG_PWM.html
+[PWM (Pulse Width Modulation) module]: https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig?q=%22config%20PLATFORM_EC_PWM%22
+[Init priority of the PWM module]: https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig.init_priority?q=%22config%20PLATFORM_EC_PWM_INIT_PRIORITY%22
+[CONFIG_PWM_SHELL]: https://docs.zephyrproject.org/latest/reference/kconfig/CONFIG_PWM_SHELL.html
+[PWM display backlight]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig?q=%22config%20PLATFORM_EC_PWM_DISPLIGHT%22
+[PWM keyboard backlight]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig?q=%22config%20PLATFORM_EC_PWM_KBLIGHT%22
+[dt-bindings/pwm/pwm.h]: https://github.com/zephyrproject-rtos/zephyr/blob/main/include/dt-bindings/pwm/pwm.h
+[PWM Example]: pwm_schematic.png
+[nuvoton,npcx-pwm]: https://github.com/zephyrproject-rtos/zephyr/blob/main/dts/bindings/pwm/nuvoton%2Cnpcx-pwm.yaml
+[ite,it8xxx2-pwm]: https://github.com/zephyrproject-rtos/zephyr/blob/main/dts/bindings/pwm/ite%2Cit8xxx2-pwm.yaml