AM437x Clock Tree Tool

Overview
The Clock Tree Tool (CTT) is a Java™-based stand-alone application. It is an interactive clock tree configuration software for the AM437x device. It allows the user to:


 * visualize the device clock tree
 * interact with clock tree elements and view the effect on PRCM registers
 * interact with the PRCM registers and view the effect on the device clock tree
 * view a trace of all the device registers affected by the user interaction with clock tree

The advantage of the tool is that the user can visualize the device clock tree state on power-on reset and then customize the configuration of the clock tree for the specific use-case and identify the device register settings associated to that configuration. Being an interactive visual tool, the CTT gives the user a global view of the device clock tree architecture and allows determining the exact register settings to obtain the specific configuration.

The latest AM437x CTT can be downloaded here: http://www.ti.com/ctt

System Requirements

 * Requires Java™ JRE 1.6.0 or higher (Can be downloaded from http://www.java.com/en/download/manual.jsp).
 * Has been tested in Microsoft WindowsXP™ environment.
 * The ideal screen resolution is 1280x1024.

Installation

 * 1) To install the Clock Tree Tool double click on the "Installer.jar" file. The installer will execute and display the License Agreement window.
 * 2) Read the License Agreement and accept the conditions of the license agreement. Once accepted, the "Install" button is enabled.
 * 3) Click on the "Install" button to proceed to the "Destination Directory Selection" window. It allows the user to identify the directory for installation of the Clock Tree Tool. Once the directory is selected, click the "Select" button to start the installation.
 * 4) When the installation is complete the "Installation completed" message is displayed. Click on "OK" button to proceed to the "Libraries" window.
 * 5) The "Libraries" window identifies the libraries needed to run the Clock Tree Tool application.
 * 6) Click on "Exit" button to terminate the clock tree tool installer.

Running Requirements

 * Click on the TI_Clock_Tree_Tool\CTT-AM437x_v1.0.0.0\CTT-AM437x_v1.0.0.0.jar

Start-up and View Refresh Delays

 * The start-up sequence of the CTT consists of reading an entire clock tree description database files. This would normally take 7 to 10 seconds.
 * Similarly the View Refresh function that updates the main view, covers the entire clock tree of the device and takes about 5 seconds.

GUI (Graphical User Interface) Description


CTT composed of 5 sub-views
 * 1) Main View
 * 2) Thumbnail  View
 * 3) Controller View
 * 4) Register View
 * 5) Trace View

CTT Main View
The Main View presents a focused view of a section of the device clock tree.



The device clock tree is represented as a tree structure composed of "nodes" or "blocks" (i.e., the rectangular elements) and the "links" or "signals" (i.e., the arrows). The direction of the signal identifies the source and the destination blocks of the signal.

A block may be a source block to multiple blocks and may in turn have multiple source blocks connected to it. The clock tree has following types of blocks:
 * Crystal
 * Clock Source
 * Oscillator*
 * Clock Switch (Hardware/ Manual /Automatic)
 * Multiplexer
 * Divider
 * DPLL
 * Module

The user can use the slide bars on the right side and the bottom of the view to move up/down and left/right in the Main View, respectively. The view highlights the state of the blocks and the signals visually. For example, the state of a clock switch (Open/Close) is presented by a red open switch or a green close switch symbol. Similarly, the state of a clock signal (Active/Gated) is highlighted by the signal being green or red.

CTT Thumbnail View
The Thumbnail View highlights a global view of the device clock tree. It also highlights the region of the clock tree visible in the Main View by a bounding rectangle. As the slide bars of the Main View are displaced the bounding rectangle in the Thumbnail View also moves accordingly.



CTT Controller View
The Controller View highlights a signal or a block of the clock tree. The user selects (i.e., clicks on) the signal/ block in the Main View and it is highlighted in the Controller View. If a signal is selected, its current frequency is presented, whereas, if a block is selected, then depending on the block type its parameters are presented.



CTT Register View
The Registers View is composed of a Register Selector list box, on the left hand side. The name of the currently selected register is highlighted in this box. On the upper right hand side of the Register View is the Register Address/Value indicator. It presents the address and the current hexadecimal value of the register.



When the user changes a parameter of a block in the Controller View, the associated bitfield is updated in the register and the Register View highlights the affected register.When the value of a bit/ bitfield of a register changes in the register view, the Trace view captures this change also.

CTT Trace View
The Trace View is composed of a multi-column table. The successive changes of the register bitfields as a result of the user interaction with the clock tree (via the Controller View or the Register View) are recorded in the rows of the Trace View table. This view allows the user to find a trace of all the register bitfields affected and the values associated to these bitfields, as a result of the current interactions.



CTT Search Bars
The CTT search bars allows the user to navigate directly to the desired block or signal within the main view. There are 3 bars. The first two are for searching and navigating to a particular block. The third one is for searching signals. After selecting the desired block or signal, the main view will automatically scroll and highlight the selected (from the bars) block or signal.



CTT Menu Commands Description
The CTT menu has following commands:

1. CTT Settings |- Power-on Reset 2. Trace |- Reset 3. View |- Hand Tool |- Select Tool |- Hide Others |- Display All |- Hide Frequency |- Display Frequency |- Refresh View |- Print View 4. Save/Load |- Save Registers |- Load Registers |- Save Source Clocks |- Load Source Clocks 6. Help |- About Clock Tree Tool |- User Manual |- License Agreement |- Export Control Notice

CTT Settings
Triggers a power-on reset for all the registers of the PRCM. All the registers are set to their reset values.As a result, the state of the clock tree is updated and reflects the state after power-on reset. (Note: When the CTT starts, the power-on reset is automatically triggered. Hence, the initial clock tree state is that of the device after power-on reset).

Trace
Reset Clears the trace log.

View
Hand Tool Allows the user to click-and-drag to pan the clock tree Main View.

Select Tool Allows the user to select elements in the clock tree Main View.

Hide Others When a clock signal is selected in the Main View and this command is selected from the menu, the CTT hides all the clocks not associated to the selected clock. A clock is considered associated to another clock if it is directly/indirectly a parent/child of the clock.

Display All This command is used to redisplay the entire clock tree from a partial view (as a result of the Hide Others command).

Hide Frequency This command hides the frequency value of the clock signals in the Main View.

Display Frequency This command displays the frequency values of the clock signals in the Main View.

Refresh View This command refreshes the Main View representation of the clock tree. It is used if the clock tree representation is not correct and the view needs to be refreshed.

Print View For a particular reason a user may want to print the tree onto an image. This image could be helpful if one needs to have it on paper, or just look at it without the need to load the CTT. This may also help when a user want to create a CTT configuration and print it. Then create another one and print it. This way the 2 or more print stamps can be compared and analyzed. When selected, the print option generated an image and saves it in the CTT install directory.

Save/Load
The register dump menu allows the user to either configure the registers of the PRCM (used in the CTT) to specific settings given in a file or to write the current values of the registers of the CTT to a file.

Save Registers The Save Registers function is used to save the current clock configuration displayed in the CTT. It generates a register dump file, which can be later imported using the Load Registers function.

Load Registers The Load Registers may be used to read-in the registers dump file generated by the Register Dump GEL script in Code Composer Studio or by any function respecting the format described below. This allows to read the current state of clock tree at any break-point in the code and obtain a visual representation of its state in the CTT.

Some example register dump files, which can be loaded by the AM437x CTT:
 * [[Media:AM437x_CTT_ROM_boot.zip|AM437x ROM Boot]] - represents the clock configuration while executing ROM boot code
 * [[Media:AM437x_CTT_OSidle.zip|AM437x OS Idle]] - represents the clock configuration in the OS Idle use case in Linux SDK 7.0
 * [[Media:AM437x_CTT_DeepSleep.zip|AM437x DeepSleep]] - represents the clock configuration in the DeepSleep use case (low power mode with most clocks gated)

Save Source Clocks The Save Source Clocks allows users to save the source clock settings used in the CTT, such as the TCLKIN frequency, into a .txt file. This file can be later imported using the Load Source Clocks function.

Load Source Clocks The Load Source Clocks allows users to import source clock settings used in the CTT. It accepts .txt files with the same contents format outputted from the Save Source Clocks function. DeviceName AM437x_PG1.0 TCLKINSource 1 10000

Help
About Clock Tree Tool Displays the CTT splash screen, which includes the device type, model version, view version, and tool version numbers.

User Manual Opens the CTT User Manual (PDF document), which contains more detailed information on CTT usage and features.

License Agreement Displays the license agreement.

Export Control Notice Displays the export notice.

Limitations And Bugs
This section identifies the known limitations and bugs of the clock tree tool

CTT View Refresh On First Start
Sometimes the clock tree representation in the main view may not be correct. The signal lines may not be straight and the blocks may not be of the correct dimensions.



Solution: Refresh the view after the clock tree tool is started and the tree is visible in the main view. for refreshing view you can refer the CTT Menu commands.

CTT Status Bits
Currently, the clock tree tool does not present the status bits associated to the clocks and module states

CTT Power Domains Behavior
Clock Tree Tool does not model the behavior of the clocks when the power domains are in RETENTION or OFF power states.It also does not model the SLEEP and WAKE-UP related clock behavior.Currently, the clock tree tool does not present the status bits associated to the clocks and module states

Debug Access Port
Using a DSS script for CCS you can easily generate a properly formatted *.rd1 file from your actual hardware which can be imported into CTT for visualization.


 * 1) Download and unzip [[Media:AM437x_CTT_DSS_scripts.zip|AM437x_CTT_DSS_scripts.zip]].
 * 2) Launch CCS.
 * 3) Create an appropriate target configuration file for connecting to your board.
 * 4) * File -> New -> Target Configuration File
 * 5) * Supply a name/location for the file.
 * 6) * View -> Target Configurations to see the available target configurations (yours should now be among them!).
 * 7) * Double-click your file in the Target Configurations panel to open it for editing.
 * 8) * Select your emulator and processor. Save.
 * 9) Launch the debugger, but do not connect to any CPUs.
 * 10) * In the Target Configurations window, right-click on your ccxml file and select "Launch Selected Configuration"
 * 11) Launch the scripting console by going to View -> Scripting Console.
 * 12) Load am437x-ctt.dss in the scripting console by executing "loadJSFile /am437x-ctt.dss".
 * 13) It will use the Debug Access Port (DAP) unobtrusively behind the scenes such that the Cortex A9 is never halted.  It will generate a am437x-ctt_yyyy-mm-dd_hhmmss.rd1 file on your desktop.
 * 14) Import the file into CTT by going to Register Dump -> Read-in.

Linux Userspace
A CTT register dump can also be taken from Linux userspace while the system is operating. This script utilizes devmem2 to read PRCM register values, then parses and formats the data into a .rd1 file for importing into the AM437x CTT.
 * 1) Download and unzip [[Media:AM437x_CTT_regdump_Linux_userspace.zip|AM437x_CTT_regdump_Linux_userspace.zip]].
 * 2) Copy the script into your rootfs.
 * 3) Boot the kernel and configure your system into the desired active state.
 * 4) Run the script. Make sure it is executable. root@am437x-evm:~# ./CTT-AM437x_REG_DUMP.sh
 * 5) A "CTT-AM437x_REG_DUMP.rd1" file will be generated.
 * 6) Import the file into CTT by going to Register Dump -> Read-in.

Uninstall
Uninstalling CTT is as easy as simply deleting the folder the CTT is installed in. This will automatically uninstall JGraph as well. Moreover, JRE can be uninstalled from Start>Settings>Control Panel>Add or Remove programs.