AM335x 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 AM335X 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 AM335x CTT can be downloaded here: http://www.ti.com/tool/clocktreetool

CLOCKTREETOOL-AM335X has been replaced by CLOCKTREETOOL-SITARA.

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 tool is recommended for use with a screen resolution of 1280x1024 or higher.

Installation

 * 1) To install the Clock Tree Tool, extract the CTT-Sitara-vX.X.X.X.zip file.
 * 2) Double-click the Installer.jar file. The installer will execute and display the License Agreement window.
 * 3) Read the License Agreement and accept the conditions of the license agreement. Once accepted, the "Install" button is enabled.
 * 4) 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.
 * 5) When the installation is complete the "Installation completed" message is displayed. Click on "OK" button to proceed.
 * 6) If the installation succeeded you should get "Clock Tree Tool is successfully installed."
 * 7) Click on "Exit" button to terminate the clock tree tool installer.

Running Requirements

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

Start-up and View Refresh Delays
Note The performance data given below is for the test machine used with AMD ™ Athlon™ 64 X2 Dual Core processor at 3.8GHz+ with 2 GB of RAM.

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

GUI (Graphical User Interface) Description


CTT composed of 5 sub-views
 * Main View
 * Thumbnail View
 * Controller View
 * Register View
 * 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 |- Hide Others |- Display All |- Hide Frequency |- Display Frequency |- Refresh View |- Print View 4. Register Dump |- Load-in |- Dump-out 6. Help |- About Clock Tree Tool |- Licence 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

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.

CTT Register Dump

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.

The Register Dump 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.

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

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.

Importing Data from Actual Hardware
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 am335x-ctt.dss.
 * 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 am335x-ctt.dss in the scripting console by executing "loadJSFile /am335x-ctt.dss".
 * 13) It will use the Debug Access Port (DAP) unobtrusively behind the scenes such that the Cortex A8 is never halted.  It will generate a am335x-ctt_yyyy-mm-dd_hhmmss.rd1 file on your desktop.
 * 14) Import the file into CTT by going to Save / Load -> Load Registers.