6.23.2. JTAG Power Analysis Tool

6.23.2.1. Introduction

The JTAG power analysis tool generates a snapshot of clock management IPs for Jacinto SoCs. The generated output includes:

  1. PLL status and settings

  2. PSC status and settings

  3. Clock tree

  4. Junction Temperature (from CCS20 Debugger only)

The tool is designed to work with the Supported Debuggers.

6.23.2.2. Features

  1. Generates and Prints PLLs status/settings, PSC status/settings, clock tree and SoC junction temperature for supported Supported SoCs

  2. Saves the output of the tool in JSON format

  3. Provides a user configuration file to selectively print the PLL and LPSC status for a subset of IPs present on the SOC, including the Power Estimation Tool IPs/modules.

6.23.2.3. Requirements

To generate the PLLs status/settings, PSC status/settings, and clock tree for a SoC, you need:

  1. J721S2 EVM

  2. Debugging Software (See Usage of desired debugger for specific requirements).

6.23.2.4. Installation

  1. Install node dependencies

  • In jtag_power_analysis_tool/ run npm ci or npm install

6.23.2.5. Usage

The JTAG Power Analysis Tool operates in a two-step process:

  1. Initially, a debugger script is executed to read the MMRs (Memory-Mapped Registers) and generate a list of key-value pairs, representing the MMR addresses and their corresponding values.

  2. The tool then utilizes this list of key-value pairs to generate comprehensive outputs, including PLL status and settings, PSC status and settings and clock tree.

The modular structure of the JTAG Power Analysis Tool allows for easy integration with any debugger. This independence from the debugger enables the tool to be used with any debugger, making it adaptable to the needs of the user.

6.23.2.5.1. Running with Code Composer Studio (CCS)

Please refer to JTAG Power Analysis Tool with CCS for instructions to run this tool with CCS.

6.23.2.5.2. Running with Trace32 PowerView

Please refer to JTAG Power Analysis Tool with Trace32 for instructions to run this tool with Trace32.

6.23.2.6. Output Formats

6.23.2.6.1. JSON Files

The output json files are saved in jtag_power_analysis_tool/output/. Sample output file can be found in jtag_power_analysis_tool/docs/sample_output/<soc>.

Following is a snapshot of the JSON output file for the j784s4 SoC running Sciclient test in no boot mode.

6.23.2.6.1.1. PLL

6.23.2.6.1.1.1. Description

The plls_status_<soc>.json is a JSON file that represents the PLL clock configuration. It contains the status of each PLL in the SoC. The file is organized as a JSON object, where each key represents a specific PLL and the corresponding value is another JSON object that contains the PLL status.

6.23.2.6.1.1.2. Clock Configuration Key

  • isEnable: Boolean value indicating whether the PLL is enabled.

  • numHsdiv: Integer value specifying the number of high-speed dividers.

  • freqOut: Object with foutVco and foutPostDiv properties.

  • hsdivOut: Array of objects with idx, isEnable, freqOut, and hsDiv properties.

  • settings: Object with postDiv1, postDiv2, vcoFreqMul, M, fracM, and isPostDivEn properties.

"PLLFRACF2_SSMOD_16FFT_MAIN_12": {
  "isEnable": 1,
  "numHsdiv": 1,
  "freqOut": {
    "foutVco": 2133,
    "foutPostDiv": 2133
  },
  "hsdivOut": [
    {
      "idx": 0,
      "isEnable": 1,
      "freqOut": 1066.5,
      "hsDiv": 2
    }
  ],
  "settings": {
    "postDiv1": 1,
    "postDiv2": 1,
    "vcoFreqMul": 111.09375,
    "M": 111,
    "fracM": 1572864,
    "isPostDivEn": 1
  }
},

6.23.2.6.1.2. PSC

6.23.2.6.1.2.1. Description

The psc_status_<soc>.json is a hierarchical JSON object that represents the status of PSC.

6.23.2.6.1.2.2. Hierarchy

The hierarchy is as follows:

  • PSC: Top-level keys representing individual PSCs (e.g. WKUP_PSC0).

  • PD: Each PSC contains multiple Power Domains (PDs).

  • LPSC: Each PD contains multiple LPSCs.

  • IP: Each LPSC is connected to a list of IPs.

6.23.2.6.1.2.3. Properties

  • PSC: Top-level key representing a PSC, containing multiple:

    • PD: An object with multiple PD properties.

  • PD: An object representing a Power Domain, containing multiple:

    • LPSC: An object with multiple LPSC properties.

  • LPSC: An object representing a Local Power & State Controller, containing:

    • status: A string indicating the status of the LPSC (ENABLED or DISABLED).

    • controlled_ip_instances: An array of strings representing the IPs connected to the LPSC

"WKUP_PSC0": {
  "PD_wkup": {
    "status": "ENABLED",
    "lpsc_list": {
      "LPSC_wkup_alwayson": {
        "status": "ENABLED",
        "controlled_ip_instances": [...]
      },
      ...
    }
  },
  "PD_mcu_pulsar": {
    "status": "ENABLED",
    "lpsc_list": {
      "LPSC_mcu_r5_0": {
        "status": "ENABLED",
        "controlled_ip_instances": [...]
      },
      ...
    }
  }
}

6.23.2.6.1.3. Clock Tree

The clock_tree_<soc>.json is a hierarchical JSON object. Each key in the clock tree represents a clock IP instance. Each clock IP instance has multiple input clocks. For each input clock, the JSON array lists the clock and its frequency starting from the root clock.

{
"IP1":[
[{clk: "clk0", freq_mhz: 1000}, {clk: "clk1", freq_mhz: 200}, {clk: "clk2", freq_mhz: 100}],
[{clk: "clk0", freq_mhz: 1000}, {clk: "clk1", freq_mhz: 200}, {clk: "clk2", freq_mhz: 50}],
],
"IP2":[
[{clk: "clk3", freq_mhz: 2000}, {clk: "clk4", freq_mhz: 400}, {clk: "clk5", freq_mhz: 400}],
[{clk: "clk3", freq_mhz: 2000}, {clk: "clk4", freq_mhz: 500}, {clk: "clk5", freq_mhz: 250}],
]
}

For example, the J784S4_DEV_MCU_ADC12FC_16FFC0 key in J784s4 represents the clock paths for the ADC IP. The array contains three elements(adc_clk, sys_clk, and vbus_clk), each representing a clock path. Each path includes the clock and its frequency.

"J784S4_DEV_MCU_ADC12FC_16FFC0": [
   [
     {
       "clk": "CLK_J784S4_GLUELOGIC_HFOSC0_CLKOUT",
       "freq_mhz": 19.2
     },
     {
       "clk": "CLK_J784S4_MCU_ADC_CLK_SEL_OUT0",
       "freq_mhz": 19.2
     },
     {
       "clk": "DEV_MCU_ADC12FC_16FFC0_ADC_CLK",
       "freq_mhz": 19.2
     }
   ],
   [
     {
       "clk": "CLK_J784S4_GLUELOGIC_HFOSC0_CLKOUT",
       "freq_mhz": 19.2
     },
     {
       "clk": "CLK_J784S4_PLLFRACF2_SSMOD_16FFT_MCU_0_FOUTVCOP_CLK",
       "freq_mhz": 2000
     },
     {
       "clk": "CLK_J784S4_HSDIV1_16FFT_MCU_0_HSDIVOUT0_CLK",
       "freq_mhz": 1000
     },
     {
       "clk": "CLK_J784S4_K3_PLL_CTRL_WRAP_WKUP_0_SYSCLKOUT_CLK",
       "freq_mhz": 1000
     },
     {
       "clk": "CLK_J784S4_K3_PLL_CTRL_WRAP_WKUP_0_CHIP_DIV1_CLK_CLK",
       "freq_mhz": 1000
     },
     {
       "clk": "DEV_MCU_ADC12FC_16FFC0_SYS_CLK",
       "freq_mhz": 500
     }
   ],
   [
     {
       "clk": "CLK_J784S4_GLUELOGIC_HFOSC0_CLKOUT",
       "freq_mhz": 19.2
     },
     {
       "clk": "CLK_J784S4_PLLFRACF2_SSMOD_16FFT_MCU_0_FOUTVCOP_CLK",
       "freq_mhz": 2000
     },
     {
       "clk": "CLK_J784S4_HSDIV1_16FFT_MCU_0_HSDIVOUT0_CLK",
       "freq_mhz": 1000
     },
     {
       "clk": "CLK_J784S4_K3_PLL_CTRL_WRAP_WKUP_0_SYSCLKOUT_CLK",
       "freq_mhz": 1000
     },
     {
       "clk": "CLK_J784S4_K3_PLL_CTRL_WRAP_WKUP_0_CHIP_DIV1_CLK_CLK",
       "freq_mhz": 1000
     },
     {
       "clk": "DEV_MCU_ADC12FC_16FFC0_VBUS_CLK",
       "freq_mhz": 333.3333
     }
   ]
 ],

6.23.2.6.2. Junction Temperature

This JSON file contains junction temperature data for the SoC. Each object in the list represents the temperature measured by a sensor located at the specified core and vddDomain.

  • tempMiliDegC - The temperature in millidegrees Celsius.

  • description - A brief description of the location of the sensor in the SoC.

6.23.2.6.3. Console output

Print levels determine the verbosity of the output.

  • 0 - Minimal output. Only the most essential information is printed (default).

  • 1 - Intermediate output. Some additional information is printed.

  • 2 - Full output. All available information is printed.

Below are the trimmed-down prints available at different print levels for j784s4 SoC.

6.23.2.6.3.1. PLL

6.23.2.6.3.2. PSC

6.23.2.6.3.3. PET

+---------------------------------------------------------------------------------+
|                            Frequency of Selected IPs                            |
+------------------------------+------------+------------------------+------------+
| IP Name                      | Freq(MHz)  | LPSC                   | Status     |
+------------------------------+------------+------------------------+------------+
| WKUP SMS 0                   | 333.3333   | LPSC_dmsc              | ENABLED    |
+------------------------------+------------+------------------------+------------+
| MCU R5FSS 0                  | 1000       | LPSC_wkup_alwayson     | ENABLED    |
+------------------------------+------------+------------------------+------------+
| MAIN A72SS 0                 | 2000       | LPSC_A72_Cluster_0     | ENABLED    |
+------------------------------+------------+------------------------+------------+
| MAIN A72SS 1                 | 2000       | LPSC_A72_Cluster_1     | ENABLED    |
+------------------------------+------------+------------------------+------------+
| MAIN R5FSS 0                 | 1000       | LPSC_Pulsar_0_R5_0     | ENABLED    |
+------------------------------+------------+------------------------+------------+
| MAIN R5FSS 1                 | 1000       | LPSC_Pulsar_1_R5_0     | ENABLED    |
+------------------------------+------------+------------------------+------------+
| MAIN R5FSS 2                 | 1000       | LPSC_Pulsar_2_R5_0     | ENABLED    |
+------------------------------+------------+------------------------+------------+
| MAIN C71SS 0                 | 1000       | LPSC_C71x_0            | ENABLED    |
+------------------------------+------------+------------------------+------------+
| MAIN C71SS 1                 | 1000       | LPSC_C71x_1            | ENABLED    |
+------------------------------+------------+------------------------+------------+
| MAIN C71SS 2                 | 1000       | LPSC_C66x_0            | ENABLED    |
+------------------------------+------------+------------------------+------------+
| MAIN C71SS 3                 | 1000       | LPSC_C66x_1            | ENABLED    |
+------------------------------+------------+------------------------+------------+
| VPAC 0                       | 720        | LPSC_VPAC              | ENABLED    |
+------------------------------+------------+------------------------+------------+
| VPAC 1                       | 720        | LPSC_vpac_1            | ENABLED    |
+------------------------------+------------+------------------------+------------+
| DMPAC 0                      | 480        | LPSC_DMPAC             | ENABLED    |
+------------------------------+------------+------------------------+------------+
| Graphic Processing Unit 0    | 800        | LPSC_GPUCOM            | ENABLED    |
+------------------------------+------------+------------------------+------------+
| Video Encoder/Decoder 0      | 600        | LPSC_encode_1          | ENABLED    |
+------------------------------+------------+------------------------+------------+
| Video Encoder/Decoder 1      | 600        | LPSC_decode_0          | ENABLED    |
+------------------------------+------------+------------------------+------------+
| LPDDR4 EMIF 0                | 1066.5     | LPSC_EMIF_CFG_0        | ENABLED    |
+------------------------------+------------+------------------------+------------+
| LPDDR4 EMIF 1                | 1066.5     | LPSC_EMIF_CFG_1        | ENABLED    |
+------------------------------+------------+------------------------+------------+
| LPDDR4 EMIF 2                | 1066.5     | LPSC_emif_cfg_2        | ENABLED    |
+------------------------------+------------+------------------------+------------+
| LPDDR4 EMIF 3                | 1066.5     | LPSC_emif_cfg_3        | ENABLED    |
+------------------------------+------------+------------------------+------------+

6.23.2.6.3.4. Clock Tree

Device IP: J784S4_DEV_MCU_ADC12FC_16FFC0
Number of clocks: 3

  >>  GLUELOGIC_HFOSC0_CLKOUT (19.2 MHz) --> MCU_ADC_CLK_SEL_OUT0 (19.2 MHz) --> ADC12FC_16FFC0_ADC_CLK (19.2 MHz)
  >>  GLUELOGIC_HFOSC0_CLKOUT (19.2 MHz) --> PLLFRACF2_SSMOD_16FFT_MCU_0_FOUTVCOP_CLK (2000 MHz) --> HSDIV1_16FFT_MCU_0_HSDIVOUT0_CLK (1000 MHz) -->K3_PLL_CTRL_WRAP_WKUP_0_SYSCLKOUT_CLK (1000 MHz) --> K3_PLL_CTRL_WRAP_WKUP_0_CHIP_DIV1_CLK_CLK (1000 MHz) --> ADC12FC_16FFC0_SYS_CLK (500 MHz)
  >>  GLUELOGIC_HFOSC0_CLKOUT (19.2 MHz) --> PLLFRACF2_SSMOD_16FFT_MCU_0_FOUTVCOP_CLK (2000 MHz) --> HSDIV1_16FFT_MCU_0_HSDIVOUT0_CLK (1000 MHz) --> K3_PLL_CTRL_WRAP_WKUP_0_SYSCLKOUT_CLK (1000 MHz) --> K3_PLL_CTRL_WRAP_WKUP_0_CHIP_DIV1_CLK_CLK (1000 MHz) --> ADC12FC_16FFC0_VBUS_CLK (333.3333 MHz)

NOTE: Some clocks of IPs may originate from sources other than the primary HFOSC/RC, in which case the clock tree print will not display the partial path and instead say “Refer to clock architecture.”

6.23.2.7. Junction Temperature

+-------------------------------------------------------------------------+
|                      Soc Junction Temperature (C)                       |
+--------+---------------------------------------------+------------------+
| Sensor | Location                                    | Temperature ( C) |
+--------+---------------------------------------------+------------------+
| 0      | Near MCU_R5FSS in VDD_MCU                   | 39.45            |
+--------+---------------------------------------------+------------------+
| 1      | On VDD_MCU / VDD_CPU boundary near A72 (in  | 39.92            |
|        | VDD_MCU)                                    |                  |
+--------+---------------------------------------------+------------------+
| 2      | Near GPU in VDD_CORE                        | 38.98            |
+--------+---------------------------------------------+------------------+
| 3      | On VDD_CORE / VDD_CPU boundary near C7x /   | 39.68            |
|        | MMA (in VDD_CORE)                           |                  |
+--------+---------------------------------------------+------------------+
| 4      | On VDD_CORE / VDD_CPU boundary near A72 (in | 39.45            |
|        | VDD_CORE)                                   |                  |
+--------+---------------------------------------------+------------------+
| 5      | On VDD_CORE / VDD_CPU boundary near C7x /   | 39.68            |
|        | MMA (in VDD_CORE)                           |                  |
+--------+---------------------------------------------+------------------+
| 6      | Near LPDDR4 in VDD_CORE (DDR)               | 40.61            |
+--------+---------------------------------------------+------------------+

6.23.2.8. User Config

To print power estimation details of specific IPs or modules, add configuration in config/.meta/<soc>/custom_ip_mapping.json. Running the tool with the –selector pet argument will then print power estimation details of the specified IP or module.

The configuration in custom_ip_mapping.json should be in the following format:

{
    "MAIN R5FSS 1": {
        "ip_name": "J784S4_DEV_R5FSS1_CORE0",
        "input_name": "DEV_R5FSS1_CORE0_CPU_CLK",
        "lpsc_name": "LPSC_Pulsar_1_R5_0"
    },
    "VPAC 0": {
        "ip_name": "J784S4_DEV_VPAC0",
        "input_name": "DEV_VPAC0_MAIN_CLK",
        "lpsc_name": "LPSC_VPAC",
    }
}

ip_name is the IP name, input_name is the particular clock of that IP, and lpsc_name is the LPSC of that IP.

Refer to TISCI for IP name & TRM for LPSC name.

Refer to Custom config documentation.

Output

+-----------------------------------------------------------------------------+
|                          Frequency of Selected IPs                          |
+------------------------------+------------+--------------------+------------+
| IP Name                      | Freq(MHz)  | LPSC               | Status     |
+------------------------------+------------+--------------------+------------+
| MAIN R5FSS 1                 | 1000       | LPSC_Pulsar_1_R5_0 | ENABLED    |
+------------------------------+------------+--------------------+------------+
| VPAC 0                       | 720        | LPSC_VPAC          | ENABLED    |
+------------------------------+------------+--------------------+------------+

6.23.2.9. Supported SoCs

The tool supports the following SoCs:

  1. j784s4

  2. j721s2

  3. j721e

  4. j722s

  5. j7200

6.23.2.10. Supported Debuggers

  • CCS20.xx and above or CCS12.xx and above

  • Trace32 PowerView for ARM version N.2025.01.xx or above with openOCD 0.12.0 or above

6.23.2.11. Known Issues

None

6.23.2.12. Troubleshoot

This section details troubleshooting techniques for resolving issues that may arise when using the JTAG Power Analysis Tool.

  1. Missing Memory Data Initialization

    File /home/cgt/ti/jacinto/workarea/pdk/packages/ti/drv/pdm_utils/tools/jtag_power_analysis_tool/memory_values_csv/j722s does not exist

Memory Data is not initialized

    Solution: Ensure you’ve successfully completed Step 1 of the tool’s setup instructions. This involves creating the MMR key-value pair data and providing the correct path to the tool.

  2. MMR Read Failed - Incorrect Selector

    Memory not found 67109376 0x4000200

/home/cgt/ti/jacinto/workarea/pdk/packages/ti/drv/pdm_utils/tools/jtag_power_analysis_tool/src/drv/lpsc.js:21

        throw new Error("Fatal error: MMR read failed. MMR key value data is missing.");

        ^

Error: Fatal error: MMR read failed. MMR key value data is missing.

    Explanation: This error occurs when running the tool with a different selector than the one used during the debugger execution. For example, running the debugger with selector=”pll” and the tool with selector=”pet/psc”. The debugger needs to retrieve the required MMRs to generate outputs accurately.

    Solution: Use selector=”all” in pmDataGenerator(soc=”j722s”,selector = “all”) to ensure all necessary MMR data is collected.

  3. Missing Node Modules

    Error: Cannot find module minimist

    Solution: Navigate to the jtag_power_analysis_tool/ directory and run either npm ci or npm install to install the required Node.js modules.

  4. Script Path Error

    js:> pmDataProcessor(soc="j722s",selector="all")

Error: pm_data_generator_ccs20: file /home/cgt/ti/pdm_utils/tools/jtag_power_analysis_tool/debugger_scripts/ccs20/pm_data_generator_ccs20.js not found, please check the path in script

0.0

    Solution: Update the filePath variable within the script to the absolute path of the pm_data_generator_ccs20.js file. This will ensure the tool can locate and execute the necessary script.