From ac3fb90588a4df0126469a1d3621c2e3f734e165 Mon Sep 17 00:00:00 2001 From: root Date: Fri, 10 Jan 2025 13:34:42 -0600 Subject: [PATCH] feat: Linux: drivers: Add initial DM-Timer documentation This patch adds initial documentation for DM-Timer found on K3 SoCs. Signed-off-by: Judith Mendez --- configs/AM62AX/AM62AX_linux_toc.txt | 1 + configs/AM62PX/AM62PX_linux_toc.txt | 1 + configs/AM62X/AM62X_linux_toc.txt | 1 + configs/AM64X/AM64X_linux_toc.txt | 1 + configs/J7200/J7200_linux_toc.txt | 1 + configs/J721E/J721E_linux_toc.txt | 1 + configs/J721S2/J721S2_linux_toc.txt | 1 + configs/J722S/J722S_linux_toc.txt | 1 + configs/J742S2/J742S2_linux_toc.txt | 1 + configs/J784S4/J784S4_linux_toc.txt | 1 + .../Kernel/Kernel_Drivers/DM-Timer.rst | 137 ++++++++++++++++++ .../Kernel/Kernel_Drivers/PWM.rst | 2 + ...Foundational_Components_Kernel_Drivers.rst | 1 + 13 files changed, 150 insertions(+) create mode 100644 source/linux/Foundational_Components/Kernel/Kernel_Drivers/DM-Timer.rst diff --git a/configs/AM62AX/AM62AX_linux_toc.txt b/configs/AM62AX/AM62AX_linux_toc.txt index d3f989208..d091b8027 100644 --- a/configs/AM62AX/AM62AX_linux_toc.txt +++ b/configs/AM62AX/AM62AX_linux_toc.txt @@ -50,6 +50,7 @@ linux/Foundational_Components/Kernel/Kernel_Drivers/Audio linux/Foundational_Components/Kernel/Kernel_Drivers/Camera/CSI2RX linux/Foundational_Components/Kernel/Kernel_Drivers/Crypto linux/Foundational_Components/Kernel/Kernel_Drivers/Display/DSS7 +linux/Foundational_Components/Kernel/Kernel_Drivers/DM-Timer linux/Foundational_Components/Kernel/Kernel_Drivers/EQEP linux/Foundational_Components/Kernel/Kernel_Drivers/E5010_JPEG_Encoder linux/Foundational_Components/Kernel/Kernel_Drivers/GPIO diff --git a/configs/AM62PX/AM62PX_linux_toc.txt b/configs/AM62PX/AM62PX_linux_toc.txt index bf0405f47..fe6bc0560 100644 --- a/configs/AM62PX/AM62PX_linux_toc.txt +++ b/configs/AM62PX/AM62PX_linux_toc.txt @@ -51,6 +51,7 @@ linux/Foundational_Components/Kernel/Kernel_Drivers/Audio linux/Foundational_Components/Kernel/Kernel_Drivers/Camera/CSI2RX linux/Foundational_Components/Kernel/Kernel_Drivers/Crypto linux/Foundational_Components/Kernel/Kernel_Drivers/Display/DSS7 +linux/Foundational_Components/Kernel/Kernel_Drivers/DM-Timer linux/Foundational_Components/Kernel/Kernel_Drivers/EQEP linux/Foundational_Components/Kernel/Kernel_Drivers/GPIO linux/Foundational_Components/Kernel/Kernel_Drivers/I2C diff --git a/configs/AM62X/AM62X_linux_toc.txt b/configs/AM62X/AM62X_linux_toc.txt index 3519c9430..401feb86d 100644 --- a/configs/AM62X/AM62X_linux_toc.txt +++ b/configs/AM62X/AM62X_linux_toc.txt @@ -50,6 +50,7 @@ linux/Foundational_Components/Kernel/Kernel_Drivers/Audio linux/Foundational_Components/Kernel/Kernel_Drivers/Camera/CSI2RX linux/Foundational_Components/Kernel/Kernel_Drivers/Crypto linux/Foundational_Components/Kernel/Kernel_Drivers/Display/DSS7 +linux/Foundational_Components/Kernel/Kernel_Drivers/DM-Timer linux/Foundational_Components/Kernel/Kernel_Drivers/EQEP linux/Foundational_Components/Kernel/Kernel_Drivers/GPIO linux/Foundational_Components/Kernel/Kernel_Drivers/I2C diff --git a/configs/AM64X/AM64X_linux_toc.txt b/configs/AM64X/AM64X_linux_toc.txt index 201cce9ca..3ea63fb96 100644 --- a/configs/AM64X/AM64X_linux_toc.txt +++ b/configs/AM64X/AM64X_linux_toc.txt @@ -41,6 +41,7 @@ linux/Foundational_Components_Kernel linux/Foundational_Components_Kernel_Drivers linux/Foundational_Components/Kernel/Kernel_Drivers/ADC linux/Foundational_Components/Kernel/Kernel_Drivers/Crypto +linux/Foundational_Components/Kernel/Kernel_Drivers/DM-Timer linux/Foundational_Components/Kernel/Kernel_Drivers/EQEP linux/Foundational_Components/Kernel/Kernel_Drivers/GPIO linux/Foundational_Components/Kernel/Kernel_Drivers/I2C diff --git a/configs/J7200/J7200_linux_toc.txt b/configs/J7200/J7200_linux_toc.txt index cb9cd67bd..d02bbe861 100644 --- a/configs/J7200/J7200_linux_toc.txt +++ b/configs/J7200/J7200_linux_toc.txt @@ -46,6 +46,7 @@ linux/Foundational_Components_Kernel linux/Foundational_Components_Kernel_Drivers linux/Foundational_Components/Kernel/Kernel_Drivers/ADC linux/Foundational_Components/Kernel/Kernel_Drivers/Crypto +linux/Foundational_Components/Kernel/Kernel_Drivers/DM-Timer linux/Foundational_Components/Kernel/Kernel_Drivers/MCAN linux/Foundational_Components/Kernel/Kernel_Drivers/GPIO linux/Foundational_Components/Kernel/Kernel_Drivers/I2C diff --git a/configs/J721E/J721E_linux_toc.txt b/configs/J721E/J721E_linux_toc.txt index b9d1aad06..6548a0c6b 100644 --- a/configs/J721E/J721E_linux_toc.txt +++ b/configs/J721E/J721E_linux_toc.txt @@ -49,6 +49,7 @@ linux/Foundational_Components/Kernel/Kernel_Drivers/Audio linux/Foundational_Components/Kernel/Kernel_Drivers/Camera/CSI2RX linux/Foundational_Components/Kernel/Kernel_Drivers/Crypto linux/Foundational_Components/Kernel/Kernel_Drivers/Display/DSS7 +linux/Foundational_Components/Kernel/Kernel_Drivers/DM-Timer linux/Foundational_Components/Kernel/Kernel_Drivers/GPIO linux/Foundational_Components/Kernel/Kernel_Drivers/HYPERFLASH linux/Foundational_Components/Kernel/Kernel_Drivers/I2C diff --git a/configs/J721S2/J721S2_linux_toc.txt b/configs/J721S2/J721S2_linux_toc.txt index 02381492d..51d1f8931 100644 --- a/configs/J721S2/J721S2_linux_toc.txt +++ b/configs/J721S2/J721S2_linux_toc.txt @@ -49,6 +49,7 @@ linux/Foundational_Components/Kernel/Kernel_Drivers/Audio linux/Foundational_Components/Kernel/Kernel_Drivers/Camera/CSI2RX linux/Foundational_Components/Kernel/Kernel_Drivers/Crypto linux/Foundational_Components/Kernel/Kernel_Drivers/Display/DSS7 +linux/Foundational_Components/Kernel/Kernel_Drivers/DM-Timer linux/Foundational_Components/Kernel/Kernel_Drivers/GPIO linux/Foundational_Components/Kernel/Kernel_Drivers/HYPERFLASH linux/Foundational_Components/Kernel/Kernel_Drivers/I2C diff --git a/configs/J722S/J722S_linux_toc.txt b/configs/J722S/J722S_linux_toc.txt index c6d60750e..716468db5 100644 --- a/configs/J722S/J722S_linux_toc.txt +++ b/configs/J722S/J722S_linux_toc.txt @@ -46,6 +46,7 @@ linux/Foundational_Components/Kernel/Kernel_Drivers/Audio linux/Foundational_Components/Kernel/Kernel_Drivers/Camera/CSI2RX linux/Foundational_Components/Kernel/Kernel_Drivers/Crypto linux/Foundational_Components/Kernel/Kernel_Drivers/Display/DSS7 +linux/Foundational_Components/Kernel/Kernel_Drivers/DM-Timer linux/Foundational_Components/Kernel/Kernel_Drivers/E5010_JPEG_Encoder linux/Foundational_Components/Kernel/Kernel_Drivers/GPIO linux/Foundational_Components/Kernel/Kernel_Drivers/I2C diff --git a/configs/J742S2/J742S2_linux_toc.txt b/configs/J742S2/J742S2_linux_toc.txt index aaec9f8bf..7d345489f 100644 --- a/configs/J742S2/J742S2_linux_toc.txt +++ b/configs/J742S2/J742S2_linux_toc.txt @@ -47,6 +47,7 @@ linux/Foundational_Components/Kernel/Kernel_Drivers/Audio linux/Foundational_Components/Kernel/Kernel_Drivers/Camera/CSI2RX linux/Foundational_Components/Kernel/Kernel_Drivers/Crypto linux/Foundational_Components/Kernel/Kernel_Drivers/Display/DSS7 +linux/Foundational_Components/Kernel/Kernel_Drivers/DM-Timer linux/Foundational_Components/Kernel/Kernel_Drivers/GPIO linux/Foundational_Components/Kernel/Kernel_Drivers/HYPERFLASH linux/Foundational_Components/Kernel/Kernel_Drivers/I2C diff --git a/configs/J784S4/J784S4_linux_toc.txt b/configs/J784S4/J784S4_linux_toc.txt index 88fe17372..f99ab0be8 100644 --- a/configs/J784S4/J784S4_linux_toc.txt +++ b/configs/J784S4/J784S4_linux_toc.txt @@ -47,6 +47,7 @@ linux/Foundational_Components/Kernel/Kernel_Drivers/Audio linux/Foundational_Components/Kernel/Kernel_Drivers/Camera/CSI2RX linux/Foundational_Components/Kernel/Kernel_Drivers/Crypto linux/Foundational_Components/Kernel/Kernel_Drivers/Display/DSS7 +linux/Foundational_Components/Kernel/Kernel_Drivers/DM-Timer linux/Foundational_Components/Kernel/Kernel_Drivers/GPIO linux/Foundational_Components/Kernel/Kernel_Drivers/HYPERFLASH linux/Foundational_Components/Kernel/Kernel_Drivers/I2C diff --git a/source/linux/Foundational_Components/Kernel/Kernel_Drivers/DM-Timer.rst b/source/linux/Foundational_Components/Kernel/Kernel_Drivers/DM-Timer.rst new file mode 100644 index 000000000..ccf42260f --- /dev/null +++ b/source/linux/Foundational_Components/Kernel/Kernel_Drivers/DM-Timer.rst @@ -0,0 +1,137 @@ +######## +DM TIMER +######## + +- This guide covers a general overview on DM Timer, it supports DM Timers found on TI's + |__PART_FAMILY_NAME__| SoC. + +- Each timer comes with dedicated pins that can be used as timer capture inputs or as timer + PWM outputs, please check the device TRM for more information. + +- Each timer contains a free-running upward counter with autoreload capability on overflow. + Each timer includes compare logic to allow an interrupt event on a programmable counter + matching value. A dedicated output signal can be pulsed/toggled on an overflow or a match + event. This offers time-stamp trigger signaling or PWM signal sources. A dedicated input + signal can be used to trigger an automatic timer counter capture or an interrupt event on a + programmable input signal transition. + +- For more detailed information on timers, please refer to the: ``Peripherals/Timer Modules/Timers`` + section of the device specific TRM. + +************** +Driver Sources +************** + +- Driver source location: :file:`drivers/clocksource/ti,timer-dm.c` +- Binding source location: :file:`Documentation/device-tree/bindings/timer/ti,timer-dm.yaml` + +*Enabling PWM output signals:* + +- Driver source location: :file:`drivers/pwm/pwm-omap-dmtimer.c` +- Binding source location: :file:`Documentation/devicetree/bindings/pwm/pwm-omap-dmtimer.txt` + +******************** +Kernel Configuration +******************** + +Configs to be enabled in Linux Kernel: + +.. code-block:: menuconfig + + Device Drivers ---> + -> Clock Source drivers + -> OMAP dual-mode timer driver (OMAP_DM_TIMER [=y]) + +*Enabling PWM output signals:* + +.. code-block:: menuconfig + + Device Drivers ---> + Pulse-Width Modulation (PWM) Support (PWM [=y]) + -> OMAP Dual-Mode Timer PWM support (PWM_OMAP_DMTIMER [=m]) + +.. rubric:: DTS node for DM Timer + +In this example, we take am62x SK DT node as an example. In general all the timer nodes +should be described in its appropriate voltage domain .dtsi file, for example the following +node can be found in k3-am62-main.dtsi: + +.. code-block:: dts + + main_timer3: timer@2430000 { + compatible = "ti,am654-timer"; + reg = <0x00 0x2430000 0x00 0x400>; + interrupts = ; + clocks = <&k3_clks 39 2>; + clock-names = "fck"; + assigned-clocks = <&k3_clks 39 2>; + assigned-clock-parents = <&k3_clks 39 3>; + power-domains = <&k3_pds 39 TI_SCI_PD_EXCLUSIVE>; + ti,timer-pwm; + }; + +*Enabling PWM output signals:* + +- The "ti,timer-pwm" DT attribute is required in the DM Timer node in order to enable PWM output + signals. + +An additional DT node is required in order to enable PWM output signals as shown below. The +``main_timer3_pins_default`` is also required and not listed here, use sysconfig tool to get +pinumux configuration. + +.. code-block:: dts + + main_pwm3: dmtimer-main-pwm-3 { + compatible = "ti,omap-dmtimer-pwm"; + #pwm-cells = <3>; + ti,timers = <&main_timer3>; + pinctrl-names = "default"; + pinctrl-0 = <&main_timer3_pins_default>; + }; + +************ +Driver Usage +************ + +For information on using DM timer as a counter, please refer to the detailed descriptions +in the TRM ``Timers Functional Description`` and ``Low-Level Programming Models`` under +``Peripherals/Timers Modules/Timers``. + + .. note:: + + Currently there is no sysfs interface to interact with the DM Timer as a counter via userspace. + +- Timers in "Timer" mode should be enabled by default in Linux DT. + +.. ifconfig:: CONFIG_part_variant in ('AM62X', 'AM62AX', 'AM62PX') + + In MAIN domain: + - 8 DM timers in MAIN domain + + In MCU domain: + - 4 DM timers in MCU domain + +.. ifconfig:: CONFIG_part_variant in ('AM64X') + + In MAIN domain: + - 12 DM timers in MAIN domain + + In MCU domain: + - 4 DM timers in MCU domain + +*Enabling PWM output signals:* + +If the PWM node exists in DT using a DM TIMER, the PWM device is probed and exposed as a +PWM device by Linux Kernel to be used by userspace in :file:`/sys/class/pwm`. + +For controlling the PWM chip via sysfs interface please refer to the official Linux +documentation: `here `__ +or go to :ref:`Using-PWM-with-sysfs`. + +******** +Examples +******** + +To enable DM timer PWM output signals, there is an example DT overlay found in +:file:`arch/arm64/boot/dts/ti/k3-am62x-sk-dmtimer-pwm.dtso` that applies for am62x +family devices and can be referenced for other K3 devices. diff --git a/source/linux/Foundational_Components/Kernel/Kernel_Drivers/PWM.rst b/source/linux/Foundational_Components/Kernel/Kernel_Drivers/PWM.rst index d804cdb8d..0ba8fa327 100644 --- a/source/linux/Foundational_Components/Kernel/Kernel_Drivers/PWM.rst +++ b/source/linux/Foundational_Components/Kernel/Kernel_Drivers/PWM.rst @@ -46,6 +46,8 @@ of the Pulse-Width Modulation Subsystem (PWMSS). .. rubric:: Driver Usage :name: driver-usage-pwm +.. _Using-PWM-with-sysfs: + .. rubric:: Using PWM with the sysfs interface :name: using-pwm-with-sysfs-interface diff --git a/source/linux/Foundational_Components_Kernel_Drivers.rst b/source/linux/Foundational_Components_Kernel_Drivers.rst index 5325b6281..e8d6fef52 100644 --- a/source/linux/Foundational_Components_Kernel_Drivers.rst +++ b/source/linux/Foundational_Components_Kernel_Drivers.rst @@ -40,6 +40,7 @@ Kernel Drivers Foundational_Components/Kernel/Kernel_Drivers/Storage/SATA Foundational_Components/Kernel/Kernel_Drivers/Storage/NAND Foundational_Components/Kernel/Kernel_Drivers/Storage/MMC-SD + Foundational_Components/Kernel/Kernel_Drivers/DM-Timer Foundational_Components/Kernel/Kernel_Drivers/UART Foundational_Components/Kernel/Kernel_Drivers/UBIFS Foundational_Components/Kernel/Kernel_Drivers/UFS