AN922: Using the Command Line Interface (CLI) for Frequency On-the-Fly with the Si5346/47 Clockbuilder Pro comes with a command line interface (CLI)that can be used for ad- justing the configuration of Si534x/8x devices on the fly. Several CLI tools are available including CBProProjectEdit and CBProMultiProjectExport which are mentioned in this application note. There are 2 documents that install with CBPro that provide reference information for the CLI tools: • CBPro CLI Overview.pdf • CBPro CLI User Guide.pdf These CLI documents are typically located in C:\Program Files (x86)\Silicon Laborato- ries\ClockBuilder Pro\CLI\Docs. This application note gives a workflow example and describes how to use a batch file which in turn calls these CLI tools to change frequencies on the Si5346 and Si5347 multi-PLL devices. It shows how the user can create register difference files to easily alter the output frequencies at runtime. The changes will alter one of the DPLLs (A, B, C, or D depending on the part) while the other PLLs remains unchanged. In the following example, a Si5346 design will be used with two outputs on DSPLLA and two outputs on DSPLLB. The command line tool is restrictive in the allowable set- ting changes from the base file. The clock out, state DSPLL, and frequency are the on- ly allowable changes. Note that bandwidth is not adjustable on the fly. The tool exports a set of register changes that can be written into the device from the host processor. This tool has some limitations, and there are cases where certain frequencies or com- binations of frequencies may not work. Contact Silicon Labs for further support if you encounter this situation. KEY POINTS • Software tool that generates register writes to change frequency • Step-by-step instructions for using the software tool • Example files available silabs.com | Smart. Connected. Energy-friendly. Rev. 0.1
Transcript
AN922: Using the Command Line Interface(CLI) for Frequency On-the-Fly with theSi5346/47
Clockbuilder Pro comes with a command line interface (CLI)that can be used for ad-justing the configuration of Si534x/8x devices on the fly. Several CLI tools are availableincluding CBProProjectEdit and CBProMultiProjectExport which are mentioned in thisapplication note. There are 2 documents that install with CBPro that provide referenceinformation for the CLI tools:• CBPro CLI Overview.pdf• CBPro CLI User Guide.pdf
These CLI documents are typically located in C:\Program Files (x86)\Silicon Laborato-ries\ClockBuilder Pro\CLI\Docs.
This application note gives a workflow example and describes how to use a batch filewhich in turn calls these CLI tools to change frequencies on the Si5346 and Si5347multi-PLL devices. It shows how the user can create register difference files to easilyalter the output frequencies at runtime. The changes will alter one of the DPLLs (A, B,C, or D depending on the part) while the other PLLs remains unchanged.
In the following example, a Si5346 design will be used with two outputs on DSPLLAand two outputs on DSPLLB. The command line tool is restrictive in the allowable set-ting changes from the base file. The clock out, state DSPLL, and frequency are the on-ly allowable changes. Note that bandwidth is not adjustable on the fly. The tool exportsa set of register changes that can be written into the device from the host processor.This tool has some limitations, and there are cases where certain frequencies or com-binations of frequencies may not work. Contact Silicon Labs for further support if youencounter this situation.
KEY POINTS
• Software tool that generates register writesto change frequency
• Step-by-step instructions for using thesoftware tool
The latest ClockBuilder Pro (CBPro) Software must be downloaded configuring the following options shown in the figure below. Wheninstalling CBPro, be sure to select the option to add the application folder to your Windows executable search path.
Figure 1.1. ClockBuilder Pro Setup for Command Line Interface
This will ensure Windows can find the CLI tools on the PC. A batch file is run which will generate various difference files and projectfiles. In the batch files there are commands to various executables. If the path is not set correctly, then the batch file won’t be able tolocate the programs when it is run. If there is any confusion as to whether the tool was installed properly with this option, simply re-install the latest version of CBPro and select the checkbox above.
A ZIP file containing a sample project file, DOS batch script, DSPLL edit files, and output files created by the script is available fordownload from http://www.silabs.com/internal-apps-management/Timing/cbpro/Using-CLI-For-FOTF-Si5346-47-Examples.zip. This ex-ample can be used and modified to your specific needs. Note it is beneficial to have some familiarity with DOS/Windows command line,but not necessary. By double clicking on the batch file it will run the script. The other alternative is to navigate to the folder where thebatch file exists and then type the file name to run it from the command line.
1.1 Troubleshooting Tip
If there continues to be issues running the batch file, the “CBProMultiProjectExport.exe” and “CBProProjectEdit.exe” tools are typicallylocated in C:\Program Files (x86)\Silicon Laboratories\ClockBuilder Pro\Bin when CBPro is installed. Verify that these programs exist onthe PC. If the batch file is run from this directory it should be able to see the executables.
AN922: Using the Command Line Interface (CLI) for Frequency On-the-Fly with the Si5346/47Software Tool Requirements
2. Workflow Example: Generating Frequency Settings On the Fly
This section is intended to explain the process of generating the final output which is a file showing the register setting changes tomodify the frequency output based on the scenario chosen. Some steps below require the user to take action, while others occur whenthe batch file script is run, auto-generating files.
1. The user must create a base project file with the CBPro Wizard. In the example, this will be a Si5346 with OUT0/1 synthesized byDSPLLA and OUT2/3 synthesized by DSPLLB. Name this file “Base.slabtimeproj” as shown in the following figure.
Figure 2.1. Files Used in Workflow to Generate Settings to Change Output Frequencies On the Fly
Base.slabtimeproj is provided to the user in the top-level of the examples folder. In the Base project, OUT0/1 (DSPLLA) are bothset to the same frequency, 644.53125 MHz. OUT2/3 (DSPLLB) are set to different frequencies, 168.041015625 MHz and672.1640625 MHz respectively.
2. The user must create 4 scenario frequency edit (.txt) files that alter the frequencies of the base (ScenarioA1, ScenarioA2, Scenar-ioB1, and ScenarioB2). The letter A or B in the Scenario files corresponds to the DSPLL that is being altered. The text files in theexample can be edited to the specific frequencies. The text files are shown below in Figure 3 . These text files are very basic. Theycontain the output frequency, output enable state, output DSPLL assignment, and output frequency, all comma separated asshown below. Save these text files in the same folder as is shown in the figure above.
The four text files shown in the figure below are also provided to the user in the examples folder. Each text file will define a differentfrequency on the fly example scenario. The CBProProjectEdit tool will use these files and Base.slabtimeproj to generate four Sce-nario_ _.slabtimeproj files.• ScenarioA1 changes OUT0/1 (DSPLLA) to a new, common frequency. OUT2/3 (DSPLLB) remains unchanged.• ScenarioA2 changes OUT0 to a new frequency and sets OUT1 to unused (turns it off). OUT2/3 (DSPLLB) remains unchanged.• ScenarioB1 changes OUT2/3 (DSPLLB) to a new, common frequency. OUT0/1 (DSPLLA) remains unchanged.• ScenarioB2 changes OUT2/3 (DSPLLB) to new, different frequencies. OUT0/1 (DSPLLA) remains unchanged.
AN922: Using the Command Line Interface (CLI) for Frequency On-the-Fly with the Si5346/47Workflow Example: Generating Frequency Settings On the Fly
Figure 2.2. Scenario Text Files that Alter the Frequency On the Fly from the Base Project
The following table lists the output frequencies of Base.slabtimeproj and the four scenario files:
Table 2.1. Output Frequencies for All Scenarios
Scenario DSPLLA DSPLLB
OUT0 (MHz) OUT1 (MHz) OUT2 (MHz) OUT3 (MHz)
Base 644.53125 644.53125 168.041015625 672.1640625
ScenarioA1 161.1328125 161.1328125 N/A N/A
ScenarioA2 161.1328125 Unused N/A N/A
ScenarioB1 N/A N/A 168.041015625 168.041015625
ScenarioB2 N/A N/A 672.1640625 168.041015625
3. Use the example batch file Si5346_Workflow.bat with the correct expected file names to automatically run the CBProProjectEditTool. This executable accepts the project edit text files and the base project file, to generate new scenario (.slabtimeproj) projectfiles for four runtime scenarios, two for each DSPLL:
a. Base + A1 edits � A1 scenario project fileb. Base + A2 edits � A2 scenario project filec. Base + B1 edits � B1 scenario project filed. Base + B2 edits � B2 scenario project file
The CBProjProjectEdit Tool is an executable that is called from the batch file that will automatically create these four different sce-nario project output files.
4. Use the example batch file, Si5346_Workflow.bat, to automatically run the CBProMultiProjectExport Tool, which creates registerand settings export files for a pair of project files:
a. Base + A1 + A2 projects � DSPLL A exportb. Base + B1 + B2 projects � DSPLL B export
In this example, we are only switching between two configurations on each PLL for simplicity. The user can have any number ofalternate configurations and pass any number of projects to this tool.
The CBProMultiProjectExport includes all registers for each configuration in a single file but, more importantly, identifies which reg-isters actually differ between configurations and therefore simplifies the process of the host switching between them.
The following DOS batch file is included in the examples folder. The batch file is used in step 3 and step 4 in this workflow. Thebatch file contains some commands to automatically create some output folders and files. It then runs two different executable pro-grams which were downloaded with CBPro. These executables are located in C:\Program Files (x86)\Silicon Laboratories\Clock-Builder Pro\Bin, but the PC should be configured to automatically find the EXEs from the script from configuration settings chosenin Figure 1.1 ClockBuilder Pro Setup for Command Line Interface on page 1.
AN922: Using the Command Line Interface (CLI) for Frequency On-the-Fly with the Si5346/47Workflow Example: Generating Frequency Settings On the Fly
By reviewing the figure of the batch file below, it can be seen that the script creates some output folders. Then it calls the CBPro-jectEdit Tool to create the four different Scenario CBPro Project Files. Then the CBProMultiProjectExport Tool is called. It uses thefour Scenario projects just created and exports all the register settings of the different scenarios.
Figure 2.3. Example Batch File for Frequency On the Fly Settings Generation
The CBProMultiProjectExport Tool generates register and settings export files along with the design report of each project that isexported. The batch file runs two CBProMultiProjectExports; once for Base and DSPLLA edits (A1 and A2) and once for Base andDSPLLB edits (B1 and B2).
5. After the batch file is configured, run it from the DOS prompt: navigate to the folder containing the batch file and type the batch filename and <ENTER>. Alternatively, you can double click the batch file from Explorer to run it. The batch file should automaticallygenerate the output files in a folder called “OutputFiles”. After this step, the settings for the different scenarios have been gener-ated. The table below shows an example of the registers.csv file that is generated. P1, P2, P3 correspond to Base, ScenarioA1,and ScenarioA2 respectively. These will always match up with the order in which the user runs the command for CBProMultiPro-jectExport.
Each register difference file has a “Varies” column that indicated if the register value needs to be changed or not to switch betweenthe three project files. In this example, there are 18 addresses which vary. The user now has all of the information needed to pre-form frequency changes at runtime.
AN922: Using the Command Line Interface (CLI) for Frequency On-the-Fly with the Si5346/47Workflow Example: Generating Frequency Settings On the Fly
6. The host microcontroller needs to ensure that the base configuration or one of the scenario configurations is present and loaded inthe part before attempting to switch between one of the scenarios. There are two ways to achieve this:
a. Ensure the base DUT register configuration matches the Orderable Part Number (OPN) DUT register configuration exactly. Ifthe same version of CBPro was used to create the OPN as you are using to create the exports, then this will be the case.Please contact Silicon Labs if you need access to an earlier version of CBPro to facilitate this.
b. If you would like to use a different version of CBPro than what created the OPN, or are writing to an un-programmed “base”part, you can alternatively write the base configuration to the DUT on system startup / DUT reset. For example, you may wantto use the last version of CBPro because the frequency planning algorithm or other register algorithm was improved. The hostpseudo code presented later in this document writes the base configuration.
7. As the host needs to switch to a different scenario, it will use the multi-project export files to write the register settings that varybetween the different scenarios.
AN922: Using the Command Line Interface (CLI) for Frequency On-the-Fly with the Si5346/47Workflow Example: Generating Frequency Settings On the Fly
3. Commands to Change the Frequencies from the Host
The previous section explained how to quickly get the registers and the settings that must be updated to make the expected frequencychanges. This section will explain how to use the exported project/register files to first configure the DUT in base mode and then makethe “on the fly” modifications.
3.1 Setting up the Base Configuration in the DUT
The Si5346 should be configured initially with the full base configuration in the DUT, which should match what was in the “BASE”project file. This can be written from CBPro Software tool or this can also be re-done from the host MCU/processor by writing the “P1”column from either multi-project export file. They will both contain the same data. Every single row will be written, and the Varies col-umn will be ignored. Note if doing this from your own host MCU/processor it is necessary to also include some special control registerwrites before and after writing the P1 column in full to put the DUT in mass programming mode and restore it to normal operation whencomplete. This is usually referred to as full configuration write preamble and postamble. This sequence is explained in the referencemanual, but the sequence is provided below. For Si5346 and Si5347, the following sequence is expected to initially program the part.(Do not include the comments if generating a csv .txt register file to be written in to an Si5346-EVB.)
1. Write the Preamble.
Address,Data
0x0B24, 0xD8
0x0B25, 0x00
2. Write in column P1.
3. Write the Postamble.
Address,Data
0x0414, 0x01
0x0514, 0x01
0x0614, 0x01 // only required on ’47; ignored on ‘46
0x0715, 0x01 // only required on ’47; ignored on ‘46
0x001C, 0x01
0x0B24, 0xDB
0x0B25, 0x02
Now the part should be configured in the base configuration.
AN922: Using the Command Line Interface (CLI) for Frequency On-the-Fly with the Si5346/47Commands to Change the Frequencies from the Host
It is expected that the part is outputting the correct initial frequencies on the outputs, but it is time to quickly change the output frequen-cies on the fly.
To switch to one of the frequency edit scenarios, parse through the register difference file and write new values from column P2 or P3that have Varies=Yes. The values in the P2- 5346EVB2 correspond to Scenario_1 and the values in the P3- 5346EVB2 correspond toScenario_2.
No special preamble or postamble sequence is required in when switching between scenarios. However, a soft reset for the DSPLLbeing adjusted must be performed. Write one of the following values to address 0x001C to perform a DSPLL soft reset.
Register Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0
All the above can be demonstrated using csv .txt files written in to an Si5346-EVB via CBPro’s EVB GUI. The section below lists exam-ple host pseudo code.
AN922: Using the Command Line Interface (CLI) for Frequency On-the-Fly with the Si5346/47Commands to Change the Frequencies from the Host
The user is given a .zip containing the Base.slabtimeproj, all four of the Scenario_ _ .txt edit files, and the batch file. This exampleexplains how to use the command line tool to generate the register settings to change the frequency. The device must start with a baseconfiguration loaded into it. Then the register settings for the frequency change can be written to the device followed by a software reseton the corresponding DSPLL. This allows the user to switch back and forth at runtime between the different output frequencies.
AN922: Using the Command Line Interface (CLI) for Frequency On-the-Fly with the Si5346/47Conclusions
DisclaimerSilicon Laboratories intends to provide customers with the latest, accurate, and in-depth documentation of all peripherals and modules available for system and software implementers using or intending to use the Silicon Laboratories products. Characterization data, available modules and peripherals, memory sizes and memory addresses refer to each specific device, and "Typical" parameters provided can and do vary in different applications. Application examples described herein are for illustrative purposes only. Silicon Laboratories reserves the right to make changes without further notice and limitation to product information, specifications, and descriptions herein, and does not give warranties as to the accuracy or completeness of the included information. Silicon Laboratories shall have no liability for the consequences of use of the information supplied herein. This document does not imply or express copyright licenses granted hereunder to design or fabricate any integrated circuits. The products must not be used within any Life Support System without the specific written consent of Silicon Laboratories. A "Life Support System" is any product or system intended to support or sustain life and/or health, which, if it fails, can be reasonably expected to result in significant personal injury or death. Silicon Laboratories products are generally not intended for military applications. Silicon Laboratories products shall under no circumstances be used in weapons of mass destruction including (but not limited to) nuclear, biological or chemical weapons, or missiles capable of delivering such weapons.
Trademark InformationSilicon Laboratories Inc., Silicon Laboratories, Silicon Labs, SiLabs and the Silicon Labs logo, CMEMS®, EFM, EFM32, EFR, Energy Micro, Energy Micro logo and combinations thereof, "the world’s most energy friendly microcontrollers", Ember®, EZLink®, EZMac®, EZRadio®, EZRadioPRO®, DSPLL®, ISOmodem ®, Precision32®, ProSLIC®, SiPHY®, USBXpress® and others are trademarks or registered trademarks of Silicon Laboratories Inc. ARM, CORTEX, Cortex-M3 and THUMB are trademarks or registered trademarks of ARM Holdings. Keil is a registered trademark of ARM Limited. All other products or brand names mentioned herein are trademarks of their respective holders.
http://www.silabs.com
Silicon Laboratories Inc.400 West Cesar ChavezAustin, TX 78701USA
ClockBuilder ProOne-click access to Timing tools, documentation, software, source code libraries & more. Available for Windows and iOS (CBGo only).
