AN922: Using the Command Line Interface (CLI) for Frequency On-the-Fly with the Si5346/47

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 adjusting 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 Laboratories\ClockBuilder Pro\CLI\Docs. KEY POINTS Software tool that generates register writes to change frequency Step-by-step instructions for using the software tool Example files available 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 setting changes from the base file. The clock out, state DSPLL, and frequency are the only 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 combinations of frequencies may not work. Contact Silicon Labs for further support if you encounter this situation. silabs.com Smart. Connected. Energy-friendly. Rev. 0.1

Software Tool Requirements 1. Software Tool Requirements The latest ClockBuilder Pro (CBPro) Software must be downloaded configuring the following options shown in the figure below. When installing 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 project files. 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 to locate the programs when it is run. If there is any confusion as to whether the tool was installed properly with this option, simply reinstall 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 for download from http://www.silabs.com/internal-apps-management/timing/cbpro/using-cli-for-fotf-si5346-47-examples.zip. This example 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 the batch 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 typically located in C:\Program Files (x86)\silicon Laboratories\ClockBuilder Pro\Bin when CBPro is installed. Verify that these programs exist on the PC. If the batch file is run from this directory it should be able to see the executables. silabs.com Smart. Connected. Energy-friendly. Rev. 0.1 1

Workflow Example: Generating Frequency Settings On the Fly 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 to modify the frequency output based on the scenario chosen. Some steps below require the user to take action, while others occur when the 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 by DSPLLA 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 both set to the same frequency, 644.53125 MHz. OUT2/3 (DSPLLB) are set to different frequencies, 168.041015625 MHz and 672.1640625 MHz respectively. 2. The user must create 4 scenario frequency edit (.txt) files that alter the frequencies of the base (ScenarioA1, ScenarioA2, ScenarioB1, and ScenarioB2). The letter A or B in the Scenario files corresponds to the DSPLL that is being altered. The text files in the example can be edited to the specific frequencies. The text files are shown below in Figure 3. These text files are very basic. They contain the output frequency, output enable state, output DSPLL assignment, and output frequency, all comma separated as shown 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 different frequency on the fly example scenario. The CBProProjectEdit tool will use these files and Base.slabtimeproj to generate four Scenario.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. silabs.com Smart. Connected. Energy-friendly. Rev. 0.1 2

Workflow 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 CBProProjectEdit Tool. This executable accepts the project edit text files and the base project file, to generate new scenario (.slabtimeproj) project files for four runtime scenarios, two for each DSPLL: a. Base + A1 edits A1 scenario project file b. Base + A2 edits A2 scenario project file c. Base + B1 edits B1 scenario project file d. 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 scenario project output files. 4. Use the example batch file, Si5346_Workflow.bat, to automatically run the CBProMultiProjectExport Tool, which creates register and settings export files for a pair of project files: a. Base + A1 + A2 projects DSPLL A export b. 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 of alternate 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 registers 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. The batch file contains some commands to automatically create some output folders and files. It then runs two different executable programs 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 chosen in Figure 1.1 ClockBuilder Pro Setup for Command Line Interface on page 1. silabs.com Smart. Connected. Energy-friendly. Rev. 0.1 3

Workflow 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 CBProjectEdit Tool to create the four different Scenario CBPro Project Files. Then the CBProMultiProjectExport Tool is called. It uses the four 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 is exported. The batch file runs two CBProMultiProjectExports; once for Base and DSPLLA edits (A1 and A2) and once for Base and DSPLLB 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 file name and <ENTER>. Alternatively, you can double click the batch file from Explorer to run it. The batch file should automatically generate the output files in a folder called OutputFiles. After this step, the settings for the different scenarios have been generated. 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 CBProMultiProjectExport. Each register difference file has a Varies column that indicated if the register value needs to be changed or not to switch between the three project files. In this example, there are 18 addresses which vary. The user now has all of the information needed to preform frequency changes at runtime. silabs.com Smart. Connected. Energy-friendly. Rev. 0.1 4

Workflow Example: Generating Frequency Settings On the Fly Table 2.2. Register Output File Format Example Address Varies P1-5346EVB2 P2-5346EVB2 P3-5346EVB2 0x000B No 0x6C 0x6C 0x6C 0x0016 No 0x03 0x03 0x03 0x0017 No 0x1C 0x1C 0x1C 0x0018 No 0x00 0x00 0x00 0x0019 No 0xCC 0xCC 0xCC 0x001A No 0xCF 0xCF 0xCF 6. The host microcontroller needs to ensure that the base configuration or one of the scenario configurations is present and loaded in the 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. If the 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 want to use the last version of CBPro because the frequency planning algorithm or other register algorithm was improved. The host pseudo 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 vary between the different scenarios. silabs.com Smart. Connected. Energy-friendly. Rev. 0.1 5

Commands to Change the Frequencies from the Host 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 frequency changes. This section will explain how to use the exported project/register files to first configure the DUT in base mode and then make the 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 column will be ignored. Note if doing this from your own host MCU/processor it is necessary to also include some special control register writes before and after writing the P1 column in full to put the DUT in mass programming mode and restore it to normal operation when complete. This is usually referred to as full configuration write preamble and postamble. This sequence is explained in the reference manual, 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. silabs.com Smart. Connected. Energy-friendly. Rev. 0.1 6

Commands to Change the Frequencies from the Host 3.2 Changing Frequency On-the-Fly It is expected that the part is outputting the correct initial frequencies on the outputs, but it is time to quickly change the output frequencies 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 P3 that have Varies=Yes. The values in the P2-5346EVB2 correspond to Scenario_1 and the values in the P3-5346EVB2 correspond to Scenario_2. No special preamble or postamble sequence is required in when switching between scenarios. However, a soft reset for the DSPLL being 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 0x001C SOFTCAL DSPLLD DSPLLC DSPLLB DSPLLA SOFTRESET_G DSPLL A B C D Value to Write for Reset 0x2 0x4 0x8 0x10 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 example host pseudo code. silabs.com Smart. Connected. Energy-friendly. Rev. 0.1 7

Commands to Change the Frequencies from the Host 3.3 Host Pseudo Code silabs.com Smart. Connected. Energy-friendly. Rev. 0.1 8

Commands to Change the Frequencies from the Host silabs.com Smart. Connected. Energy-friendly. Rev. 0.1 9

Commands to Change the Frequencies from the Host silabs.com Smart. Connected. Energy-friendly. Rev. 0.1 10

Conclusions 4. Conclusions The user is given a.zip containing the Base.slabtimeproj, all four of the Scenario.txt edit files, and the batch file. This example explains how to use the command line tool to generate the register settings to change the frequency. The device must start with a base configuration loaded into it. Then the register settings for the frequency change can be written to the device followed by a software reset on the corresponding DSPLL. This allows the user to switch back and forth at runtime between the different output frequencies. silabs.com Smart. Connected. Energy-friendly. Rev. 0.1 11

ClockBuilder Pro One-click access to Timing tools, documentation, software, source code libraries & more. Available for Windows and ios (CBGo only). www.silabs.com/cbpro Timing Portfolio www.silabs.com/timing SW/HW www.silabs.com/cbpro Quality www.silabs.com/quality Support and Community community.silabs.com Disclaimer Silicon 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 Information Silicon 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. Silicon Laboratories Inc. 400 West Cesar Chavez Austin, TX 78701 USA http://www.silabs.com