linux: How_to_Guides: Add instructions to enable SSC on DSS PLLs

configs/AM62AX/AM62AX_linux_toc.txt

@@ -123,6 +123,7 @@ linux/How_to_Guides/Target/How_to_test_MCAN_on_AM62x
 linux/How_to_Guides/Target/How_to_enable_DT_overlays_in_linux
 linux/How_to_Guides/Target/How_To_Enable_M2CC3301_in_linux
 linux/How_to_Guides/Target/How_to_playback_audio_over_HDMI
+linux/How_to_Guides/Target/How_to_enable_SSC_for_DSS
 linux/How_to_Guides/Target/How_to_Use_K3Conf_Tool
 linux/How_to_Guides/Target/Runtime_debug_unlock_on_secure_device
 linux/How_to_Guides/Target/How_to_Tune_Real_Time_Linux

configs/AM62DX/AM62DX_linux_toc.txt

@@ -76,6 +76,7 @@ linux/How_to_Guides
 linux/How_to_Guides_Developer_Notes
 linux/How_to_Guides/Host/SYSFW_Trace_Parser
 linux/How_to_Guides/Target/How_to_enable_DT_overlays_in_linux
+linux/How_to_Guides/Target/How_to_enable_SSC_for_DSS
 linux/How_to_Guides/Target/How_to_emmc_boot
 linux/How_to_Guides/Target/How_to_mmcsd_boot_emmc_uda
 linux/How_to_Guides/Target/Runtime_debug_unlock_on_secure_device

configs/AM62PX/AM62PX_linux_toc.txt

@@ -160,6 +160,7 @@ linux/How_to_Guides/Target/How_to_test_MCAN_on_AM62x
 linux/How_to_Guides/Target/How_to_enable_DT_overlays_in_linux
 linux/How_to_Guides/Target/How_to_playback_audio_over_HDMI
 linux/How_to_Guides/Target/How_to_enable_display_sharing_between_remotecore_and_Linux
+linux/How_to_Guides/Target/How_to_enable_SSC_for_DSS
 linux/How_to_Guides/Target/How_to_boot_quickly
 linux/How_to_Guides/Target/How_to_enable_Microtips_LVDS_Panel
 linux/How_to_Guides/Target/How_To_Enable_M2CC3301_in_linux

configs/AM62X/AM62X_linux_toc.txt

@@ -167,6 +167,7 @@ linux/How_to_Guides/Target/How_to_enable_DT_overlays_in_linux
 linux/How_to_Guides/Target/How_to_playback_audio_over_HDMI
 linux/How_to_Guides/Target/How_to_enable_Microtips_LVDS_Panel
 linux/How_to_Guides/Target/How_To_Enable_M2CC3301_in_linux
+linux/How_to_Guides/Target/How_to_enable_SSC_for_DSS
 linux/How_to_Guides/Target/How_to_Use_K3Conf_Tool
 linux/How_to_Guides/Target/Runtime_debug_unlock_on_secure_device
 linux/How_to_Guides/Target/How_to_Tune_Real_Time_Linux

source/linux/Foundational_Components/Kernel/Kernel_Drivers/Display/DSS7.rst

@@ -375,6 +375,8 @@ Device Tree Node
 Documentation for tidss device tree node and its properties can be found in linux kernel device tree bindings in below directory
 ``Documentation/devicetree/bindings/display/ti/``. Seperate binding files are present for different version of the DSS controller.
 
+For information about configuring Spread Spectrum Clocking (SSC) for DSS, see <../../../../How_to_Guides/Target/How_to_enable_SSC_for_DSS.html>`__
+
 
 Driver Usage
 ============

source/linux/How_to_Guides/Target/How_to_enable_SSC_for_DSS.rst

@@ -0,0 +1,201 @@
+.. _how-to-enable-ssc-for-dss:
+
+How to enable spread spectrum clocking for display subsystem
+============================================================
+
+Introduction
+------------
+
+Spread Spectrum Clocking (SSC) reduces electromagnetic interference (EMI). It modulates the clock frequency. SSC varies the frequency over time. This spreads energy across many frequencies. This reduces peak emissions.
+
+Digital clock signals are periodic and square-shaped. Most energy focuses at the center frequency and odd harmonics. SSC spreads this energy across a wider range. This reduces the peak amplitude. SSC adds jitter to the clock signal. The voltage amplitude stays unchanged.
+
+Display Subsystem (DSS) supports SSC configuration for its pixel clocks. You configure this through device tree properties. This helps you meet EMI compliance requirements. For DPI, DSS typically uses Phase-locked loop (PLL) 17. You can also use PLL 16 or PLL 18.
+
+This guide shows how to configure SSC for DSS pixel clocks on supported TI SoCs.
+
+.. important::
+   The pixel clock frequency for DPI from the DSS PLL must not exceed 165MHz. Center spread adds a 20% overshoot to the modulation depth. Account for this when you calculate the maximum frequency.
+
+Spread spectrum clocking configuration parameters
+-------------------------------------------------
+
+The ``assigned-clock-sscs`` device tree property is used to configure SSC and takes three parameters:
+
++-----------------------+----------------------------------------------------------------+
+| Parameter             | Description                                                    |
++=======================+================================================================+
+|| Modulation Frequency || The frequency at which the spread spectrum modulation occurs  |
+|| (Hz)                 || - Minimum: 32,000 Hz (32 kHz)                                 |
+||                      || - Maximum: Reference clock frequency / 200                    |
+||                      || - Typical values: 32 kHz to 120 kHz                           |
++-----------------------+----------------------------------------------------------------+
+|| Modulation Depth     || The amount of frequency spread as a percentage                |
+|| - Minimum: 10 (0.1%) || - Maximum: 310 (3.1%)                                         |
+||                      || - Adjustable in increments of 10 (0.1%)                       |
+||                      || - Example: 50 = 0.5% spread                                   |
+||                      || - Units: 1/10,000 (for example, 50 represents 0.5%)           |
++-----------------------+----------------------------------------------------------------+
+|| Spread Type          || - 1: Center spread (frequency varies on both higher and lower |
+||                      ||      frequencies than nominal)                                |
+||                      || - 3: Down spread (frequency varies only lower than nominal)   |
++-----------------------+----------------------------------------------------------------+
+
+**Modulation Profile**
+
+The modulation uses a triangular waveform. The Device Manager automatically configures the PLL hardware based on the modulation frequency specified in the device tree.
+
+.. note::
+   Down spread mode (value 3) is commonly used for display interfaces. It ensures the clock never exceeds the specified maximum frequency. This is important for meeting display timing specifications and avoiding over-clocking.
+
+.. note::
+   SSC is currently supported only on display PLL for these SoCs: AM62x, AM62Ax, AM62Dx, AM62Px. The display PLL is typically PLL17. You can also use PLL16 or PLL18 for DPI applications.
+
+.. note::
+   The Device Manager automatically converts the modulation depth values from the device tree to the appropriate hardware register values.
+
+Example 1: Basic SSC configuration (center spread)
+--------------------------------------------------
+
+This example shows how to enable SSC for the DSS VP2 clock with the following parameters:
+
+- Modulation frequency: 100 kHz
+- Modulation depth: 10 (0.1%)
+- Spread type: Center spread (1)
+
+Add the following properties to the DSS node in your device tree file (for example, ``k3-am62p-j722s-common-main.dtsi``):
+
+.. code-block:: dts
+
+   &dss0 {
+       assigned-clocks = <&k3_clks 186 2>;
+       assigned-clock-sscs = <100000 10 1>;
+   };
+
+In this example:
+
+- ``assigned-clocks``: Specifies the clock to configure (DSS VP2 clock, k3_clks 186 2)
+- ``assigned-clock-sscs``: Configures SSC with 100 kHz modulation, 0.1% depth, center spread mode (1)
+
+.. warning::
+   This example uses center spread mode (1). Center spread has a 20% overshoot on the modulation depth. For 0.1% nominal depth, the actual peak deviation is about 0.12%.
+
+   When using center spread:
+
+   1. Ensure the display panel can handle the higher peak frequency
+   2. Verify the maximum frequency stays below 165MHz including the overshoot
+   3. Consider down spread mode (Example 2) to avoid exceeding the nominal frequency
+
+Example 2: SSC with down spread mode
+------------------------------------
+
+This example demonstrates down spread mode, which we recommend for display interfaces to ensure the clock never exceeds the nominal frequency:
+
+- Modulation frequency: 33 kHz
+- Modulation depth: 50 (0.5%)
+- Spread type: Down spread (3)
+
+.. code-block:: dts
+
+   &dss0 {
+       assigned-clocks = <&k3_clks 186 2>;
+       assigned-clock-sscs = <33000 50 3>;
+   };
+
+Example 3: Greater modulation depth
+-----------------------------------
+
+This example shows a configuration with greater modulation depth for better EMI reduction:
+
+- Modulation frequency: 50 kHz
+- Modulation depth: 250 (2.5%)
+- Spread type: Down spread (3)
+
+.. code-block:: dts
+
+   &dss0 {
+       assigned-clocks = <&k3_clks 186 2>;
+       assigned-clock-sscs = <50000 250 3>;
+   };
+
+.. note::
+   Greater modulation depth provides better EMI reduction but increases clock jitter. Test with your specific display panel to ensure timing margins meet requirements.
+
+Troubleshooting
+---------------
+
+Display artifacts
+^^^^^^^^^^^^^^^^^
+
+If you observe display artifacts, flickering, or other visual anomalies after enabling SSC:
+
+1. Reduce the spread percentage to a smaller value (for example, try 0.1% or 10 in device tree)
+2. Try a different modulation frequency (typical range: 32-100 kHz)
+3. Switch from center spread to down spread mode if not already using it
+4. Consult your display panel data sheet for spread spectrum tolerance specifications
+
+Clock not found error
+^^^^^^^^^^^^^^^^^^^^^
+
+If you experience errors during boot about clock assignment:
+
+1. Verify the clock ID is correct for your SoC (check the technical reference manual)
+2. Ensure the Device Manager supports SSC for the specified clock
+3. Check that the kernel version includes SSC support for the clock subsystem
+
+Requirements and limitations
+----------------------------
+
+- Configure the display clock by using ``assigned-clocks`` and ``assigned-clock-sscs``
+
+**Firmware capability**
+
+Check if your firmware supports SSC by using the capability flag:
+
+.. code-block:: console
+
+   # Check firmware capabilities (requires ti-sci driver)
+   cat /sys/kernel/debug/ti-sci/fw_caps
+
+Look for ``TISCI_MSG_FLAG_FW_CAP_CLOCK_SSC`` in the capabilities list.
+
+Best practices and recommendations
+----------------------------------
+
+- Start with low modulation depth (0.1% to 0.5%) and increase only if needed to meet EMI requirements
+- Use down spread mode (3) for display interfaces to ensure the clock never exceeds the nominal frequency
+- If using center spread mode (1), account for 20% overshoot on the modulation depth
+- Test with your specific display panel to ensure timing margins meet requirements
+
+Important considerations
+------------------------
+
+.. important::
+
+   - Configure SSC together with ``assigned-clocks`` to specify which clock receives the SSC settings
+   - When you enable SSC, the instantaneous clock frequency deviates from the nominal rate
+   - Always validate SSC parameters with the specific display panel you use. Some panels might have strict jitter requirements
+
+Customer responsibilities
+-------------------------
+
+.. warning::
+
+   **You assume all responsibility for the configuration and usage of spread-spectrum clocking.** You must:
+
+   1. Research the clock limitations associated with your selected display panel
+   2. Configure SSC to be compatible with that specific display panel
+   3. Verify that the SSC configuration does not cause any system-related issues for any operating condition
+   4. Work with the display panel vendor to resolve any issues caused by enabling SSC
+   5. Validate displays to have enough functional margin with the jitter introduced by spread spectrum modulation
+
+   Some display panels have clocking limitations not in their data sheets. Work directly with the display panel manufacturer on any display-related issues from SSC.
+
+References
+----------
+
+- `DSS Driver Documentation <../../Foundational_Components/Kernel/Kernel_Drivers/Display/DSS7.html>`__
+- SoC Technical Reference Manual (TRM)
+- System Firmware Documentation - PM Clock API
+- Linux kernel device tree bindings: ``Documentation/devicetree/bindings/display/ti/``
+- Linux kernel clock framework documentation: ``Documentation/driver-api/clk.rst``

source/linux/How_to_Guides_Developer_Notes.rst

@@ -33,6 +33,7 @@ Developer Notes
    How_to_Guides/Target/How_to_Use_K3Conf_Tool
    How_to_Guides/Target/How_to_Tune_Real_Time_Linux
    How_to_Guides/Target/How_to_enable_display_sharing_between_remotecore_and_Linux
+   How_to_Guides/Target/How_to_enable_SSC_for_DSS
    How_to_Guides/Target/How_to_boot_quickly
    How_to_Guides/Target/Runtime_debug_unlock_on_secure_device
    How_to_Guides/FAQ/How_to_Verify_Ipc_Linux_R5