UniFlash v3 Quick Start Guide

# Quick Start Guide [[y Note: This guide is for UniFlash v3.x only. ]] Once you have downloaded the UniFlash installer from the Download site, you can install the UniFlash application using the provided executable. During installation, on top of choosing where you would like to install the application, you will also be able to choose to install the "Complete Feature Set", or choose specific product family of devices and communication interface support to meet your needs. The final disk usage is determined by the number of device and communication interface support you choice. After successfully installing, there are 3 main ways to interact with the application: - Graphical User Interface (GUI) - Provides a graphic interface for users to program their Flash targets, as well as to perform Flash Operations - Scripting - Provides JavaScript based scripting support for Flash Programming/Operations - Command Line - single line interface for quick access to Flash Programming/Operations CCS UniFlash uses Target Configuration (CCXML) files for determining the communication interface to use and the target to communicate with during a session. The CCXML files can either be generated using the available interfaces, or can be imported from existing configurations generated from Code Composer Studio (CCS). # Target Configuration The Target Configuration (CCXML) files are the XML files used for configuring a device in CCS UniFlash and the main CCS application. The files are generated by specifying a Connection type and a board or device (based on the emulation/device support that was installed). Once a Target Configuration file is specified, users will be able to access the available Flash options, execute Flash operations and load programs on the configured device. # Interfaces ## Graphical User Interface (GUI) ### Overview Provides a graphic interface for users to program their Flash targets, as well as to perform Flash Operations. Not only does the GUI provide a graphical way to interact with the UniFlash application, it also provides extra functionality like automatic session saving, providing the most recently used list, ability to view the installed versions of each component, and in the future, provide the ability to update the application using the provided dialog. ### Step by Step guide to use UniFlash RCP to program your device 1. Specify a Target Configuration file: - You will need to provide a target configuration (\*.ccxml) file which defines your target device and connection from the host to the target device. You can use an existing target configuration by **Open Target Configuration(*.ccxml) File** or create a new one using **Open Target Configuration(*.ccxml) File**. Both can be found in the **<File>** menu or the from the links in the welcome page when you launch UniFlash. - You can also find quick access links to recent sessions under the **<File>** menu and welcome page. A link to the unsaved session is also provided in the welcome page 2. Program your device: - At this stage, you can start to program or erase your device. The settings for the flash operations such as erase options etc are show in the main view for further configuration. You can also save the target configuration you have just created using **Save Target Configuration(*.ccxml) File** in the **<File>** menu. - Under **<Program>** menu: - **Load Program...** allows the user to specify a single file to be loaded onto a specific core on the target device. - **Erase Cores...** allows the user to erase the flash on the cores checked in the list using the settings specified in the main view - **Save Memory...** provide a way for the user to export contents on the target flash to a file on the host side. - In the tree menu, click on the **Programs** node will display the multi-load interface. For users whos project contains multiple binaries to be loaded onto a single device, this will help to automate the process. There will be no erase in between the loading of files. However, the user have to make sure that there is no overlap in the flash regions for the files to be loaded. To use this feature, you can use the context menu or the buttons at the bottom of the view to add/remove files into the list for multi-load. Only the checked files will be loaded. The Check/Uncheck buttons will check/uncheck the selected entries for easier file management. ### Session Settings - After a target configuration file is specified, all the changes in setting you have made is saved automatically to a .uniflashsession file next to the .ccxml file in xml format. This saved settings is automatically restored when you open the same target configuration file next time. This file saves all the changes you have made to the settings in the main view and the file entries added in the multi-load view. The **<Session>** menu provide some operations for you to further leverage on this feature. - **Save Settings** as a Copy allows the user to snapshot the current settings and save to a specific file. - **Load Settings** allows the user to restore the settings from any saved .uniflashsession file. - **Purge Settings** provide a way to reset all settings back to default. In **Windows → Preferences → UniFlash Preferences**, there is an option to turn off the autosave of session files. ## Scripting ### Overview Provides JavaScript based scripting support for Flash Programming/Operations in CCS UniFlash. The scripting support is based on the Debug Server Scripting (DSS) architecture also available in Code Composer Studio. This means that scripts written for DSS can be ran in UniFlash without any changes. All of the available APIs in DSS will be available in the UniFlash scripting environment, which will allow users to set up their target configuration, set Flash options, perform Flash operations, load programs, and so on. To understand the full functionality of DSS, read the next section on Documentation. ### Documentation JavaDoc is generated for the DSS APIs, and they provide users with information on each of the available APIs. The documentation is available in the following location: <tt><installDir>/uniflash<version>/ccs_base/scripting/docs/GettingStarted.htm</tt> ### How to Run The main script for running your JavaScript based UniFlash scripts is located at the following location: <tt><installDir>/uniflash<version>/ccs_base/scripting/bin/</tt> The script **dss.bat** (for Windows) and **dss.sh** (for Linux) can be use to run a given JavaScript (*.js) file. - <tt>> dss.bat myScript.js</tt> (Windows) - <tt>> ./dss.sh myScript.js</tt> (Linux) ### Examples There are a few UniFlash Scripting examples shipped with the product, and they can be located at the following location: <tt><installDir>/uniflash<version>/ccs_base/scripting/examples/uniflash/scripting/</tt> <br> Note that you will need to either have the exact target as in the example, or modify the example to match your needs. - **scriptExample_viewOptions.js**: An example of using an existing Configuration file and viewing available Flash options - **scriptExample_createConfig_viewOperation.js**: An example of creating a new Configuration file and listing available Flash operations - **scriptExample_setOptions_performOp.js**: An example of setting Flash Options, and performing a Flash operation - **scriptExample_multiCore_loadSettings_program.js**: An example of accessing the C28 core of the Concerto multicore devices, load settings from a session file (changes default to erase Necessary Sectors Only), and load a program - **scriptExample_export.js**: An example of accessing the M3 core of the Concerto multicore devices, and export the memory to a COFF file - **scriptExample_complex.js**: An example of chaining (issuing multiple) operations in the same command. It will configure an F28035 device, give the necessary password, unlock the device, erase the Flash, load multiple Flash programs, calculate the checksum (which will be logged in the log file), and export the memory to one single program file. ## Command Line ### Overview Single line interface for quick access to Flash Programming/Operations. The purpose of the command line support is to be able to perform all support functionality from the GUI, all with a single line of command. All command line support files are location in the following locations: <tt><installDir>/uniflash<version>/ccs_base/scripting/examples/uniflash/cmdLine/</tt> <br> There are also included shortcut scripts for the command line tool in the installation directory, uniflash.bat (for Windows) and uniflash.sh (for Linux). To use them, just go to the installation folder in command line, and execute command line commands like you would in the <tt><installDir>/uniflash<version>/ccs_base/scripting/examples/uniflash/cmdLine/</tt> directory. ### Documentation To get more information on the available arguments when running the command line support, go to the cmdLine folder, and run the following: - <tt>> uniflash -help</tt> (for Windows) - <tt>> ./uniflash.sh -help</tt> (for Linux) To get further details on each of the available arguments, read the available Read-Me file at: <tt><installDir>/uniflash<version>/ccs_base/scripting/examples/uniflash/cmdLine/uniFlash_ReadMe.txt</tt> ### How to Run To run your specific command, go to the cmdLine folder or the installation folder (for the shortcuts), and run the following: - <tt>> uniflash <yourCommand></tt> (for Windows) - <tt>> ./uniflash.sh <yourCommand></tt> (for Linux) ### Examples We provide the same examples we provide for scripting support, but only in command line form. The examples are provided in Windows format, but should be easily converted to other formats as needed. The text file containing the examples are available in the following location: <tt><installDir>/uniflash<version>/ccs_base/scripting/examples/uniflash/cmdLine/uniFlash_example.bat</tt> # Target Specific Documentation ## Sitara ARM Cortex-A Processors See: [Sitara UniFlash Documentation](https://software-dl.ti.com/processor-sdk-linux/esd/docs/latest/linux/Foundational_Components/Tools/Flash_Tools.html#sitara-uniflash) ## Stellaris and Tiva ARM Cortex-M Microcontrollers ### User Register Programming The User Register Programming utility allows programming the non-volatile User registers (USER_REG0 and USER_REG1). There are two programming modes for the User Register Programming utility. - Register Mode - MAC Address Mode #### Register Mode When you select the **Register Mode**, you can program the User registers by specifying the data to be written to each User register. If the **Commit User 0** checkbox is checked, then User 0 will be permanently programmed. If the **Commit User 1** checkbox is checked, then User 1 will be permanently programmed. Otherwise, the User registers will reset to 0xFFFFFFFF upon the next reset. The **Get Current Values** button will display the current User 0 and User 1 values in the appropriate edit boxes. [[y Note: Committing User registers is permanent and cannot be reversed. ]] #### MAC Address Mode When you select the **MAC Address Mode**, you can program the User registers by specifying the MAC address to be written to the User registers. If the **Commit MAC Address** checkbox is checked, then User 0 and User 1 will be permanently programmed. Otherwise, the User registers will reset to 0xFFFFFFFF upon the next reset. Example: A MAC address of 00-1A-B6-00-02-74 will be stored in the User registers as "User 0 = 0x00B61A00" and "User 1 = 0x00740200". The **Get Current MAC Address** button will display the current MAC address value in the edit box. [[y Note: Committing User registers is permanent and cannot be reversed. ]] ### Debug Port Unlock The Debug Port Unlock utility allows the JTAG/SWD debug pins to be unlocked if you configure the pins as GPIOs or there is some other issue that causes the device to lock up, such as configuring to system clock out of specification. This utility has some restrictions for the Sandstorm class of microcontrollers. There are three options for the Debug Port Unlock utility: - Fury, DustDevil and Blizzard Classes - Tempest and Firestorm Classes #### Fury, DustDevil and Blizzard Classes When you select this option, the utility unlocks the JTAG/SWD debug pins for all revisions of the Fury, DustDevil and Blizzard classes of microcontrollers by performing a mass erase of the internal flash using the JTAG/SWD recovery sequence. This utility works regardless of which pins are configured as GPIOs. #### Tempest and Firestorm Classes When you select this option, the utility unlocks the JTAG/SWD debug pins for all revisions of the Tempest and Firestorm classes of microcontrollers by performing a mass erase of the internal flash using the JTAG/SWD recovery sequence. This utility works regardless of which pins are configured as GPIOs. [[y Note: User Registers are committed permanently on Fury and Dustdevil classes, but on Tempest, Firestorm and Blizzard classes, they will be erased when the Debug Unlock sequence is performed. You should note of the values in the User Registers prior to performing a Debug Unlock sequence, so that you will be able to restore these values after the process. Note also that on Stellaris Kits that support the Ethernet interface, the User Registers are used to program the MAC address. If the MAC address is erase, the sample Ethernet applications will not function properly, as there is no valid MAC address to be used. ]] ### ICDI Firmware Update Some evaluation boards have an ICDI interface that uses a Texas Instruments USB device. For these devices, it is possible to update the ICDI firmware, using the ICDI Firmware Update utility. This utility will first check for the presence of a TI-based ICDI device, and if found, will check the firmware revision number against the latest firmware contained in the LM Flash Programmer application. After these checks, the firmware will be updated and the ICDI device will be reset and ready for debugging operation. In some cases, it may be necessary to install the firmware update drivers (if these drivers have not yet been installed). If the operating system prompts you for new drivers, you simply need to point the installer to the same location where the original board drivers were installed. This folder will also contain the necessary update drivers. ### USB DFU Interface The USB Device Firmware Upgrade (DFU) Interface is a high speed serial interface and device class which allows embedded USB devices to offer firmware upgrade abilities when connected to a USB host system. You can use the USB DFU Interface to program the internal flash of the Stellaris or Tiva microcontroller and to read back the current contents. Texas Instruments-specific extensions to the standard USB DFU device protocol are also implemented to allow the host to erase sections of flash and check that regions of flash are blank. [[y Note: A properly configured boot loader needs to be programmed into the internal flash of the Stellaris or Tiva microcontroller prior to programming with the USB DFU Interface ]] For UniFlash, you will need to create a CCXML file containing the **Tiva/LM USB DFU Interface** as the connection, and 'Tiva/LM device' entry as the device. Once created, you can choose to save the CCXML file for future use in UniFlash. Once configured, use the **Display DFU devices** button to display to the console the list of connected DFU devices to your machine, along with the index of each entry. You can enter the index of the DFU device you want to interact with in the **Select Device (index)** field. The following options are available via the DFU interface: - **Load Program** - **Erase Flash** - **Blank Check** ## Wireless Connectivity CCxxxx Cortex-M devices - Code examples for CC2538 devices can be found at the following location: <tt><installDir>/eclipse/plugins/com.ti.cc2538_<version#>/resources/</tt> (need CCS or equivalent to compile) - Already created CCXML files for CC2538 devices, which should work with UniFlash, can be found at the following location: <tt><installDir>/eclipse/plugins/com.ti.cc2538_<version#>/resources/blinky/ccs/</tt> # Diagnostic Information There are a few ways users can gather diagnostic information that can be sent to TI to help with debugging a particular problem within UniFlash. ## Generating DS logs (Starting in UniFlash 3.1) To generate a DS log, start up UniFlash and go to the **Help** menu item. In the dropdown, you will see an entry for **Start DS Logging**. Choose this, and choose a file on your file system where the logs will go. This will enable the DS logging system. Now, just run through your scenario that shows the error, and after you are done, go into the **Help menu**, and choose **Stop DS Logging**. Now, you get include this log when posting on the E2E forum; this will help me in the analysis of the issue. ## Generate RCP Log Add these 2 lines to the bottom of the file at <tt>uniflash_3.4\eclipse\uniflash.ini</tt> - <tt>DDebugPrintlnFlag=16</tt> - <tt>DDebugLogPath=c:\temp</tt> A log file named **UniFlashRCPLog.log** will be generated in <tt>c:\temp</tt> ## Enable verbose mode during Flash operations Users can also enable verbose mode for Flash operations, which will add additional output during Flash operations. To find the option, configure for your device and scroll down to the bottom of the Flash Programming settings. The verbose mode is on by default in the command line tool.   <div id="resources" align="center" style="margin-top: 4em; font-size: smaller;"> </div> <div align="center" style="margin-top: 4em; font-size: smaller;"> <a rel="license" href="https://creativecommons.org/licenses/by-nc-nd/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://software-dl.ti.com/ccs/esd/documents/web_support_v2/cc_license_icon.png" /></a><br />This work is licensed under a <a rel="license" href="https://creativecommons.org/licenses/by-nc-nd/4.0/">Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International License</a>.</div> <div id="timestamp" align="center" style="margin-top: 4em; font-size: smaller;"> </div>