Hardware section

Introduction

This guide describes the software contained in the SMT6001 package.

The main program of the SMT6001 package, the Flash Programming Utility, manages the Flash ROMs on Sundance TIMs. The Flash Programming Utility uses Texas Instruments' Code Composer™ to allow you to analyse the contents of a ROM and program new data. For added security, the Flash Programming Utility will also allow you to erase the ROM completely.

Important: There have been several changes to the way the ROM is organised. Customers who have used previous versions of the SMT6001 (prior v5.00) are advised to read the section "what's new in this release" for more information about the changes.


Before you start

Before you can use the Flash Programming Utility you must configure Code Composer to match your hardware. This is most easily done using the Sundance Wizard.

The Flash Programming Utility will only be able to function if Code Composer can start successfully.


What's new in this release

V5.0 of the 6001 includes significant changes from previous versions. The most important change is that a new format is used for data in the flash. The new format makes better use of the available flash space, and allows significant simplifications in the programming procedure, but it does mean that any data written with older versions of the SMT6001 will have to be reprogrammed.

3L Diamond V3.0 makes use of the new facilities to simplify the process of generating applications that can be loaded from ROM.

Known issues

Using CCS 3.0

When using CCS 3.0, you need to connect to the target DSP before using the SMT6001. This is a shortcoming of CCS, and will be addressed as soon as a new release of CCS is available.

Diamond applications in the flash

If you wish to program 3L Diamond programs into the flash, you have to build your .app file with 3L Diamond V3.0 or above.


Flash contents

Various data blocks are stored in the flash ROMs of Sundance TIMs. The main data blocks are:

  • Bootloader data block

  • FPGA bitstream data block

  • Dynamic values data block

  • Zero or more User data blocks

These blocks are stored sequentially in the flash. The contents of these data blocks are managed by the Flash Programming Utility (SmtFpu.exe).


Bootloader

The Bootloader data block holds a standard Sundance program that is loaded and starts to execute when the TIM is taken out of reset. This program is responsible for:

  • Initialising the appropriate memory interface settings (EMIF);

  • Configuring the TIM's FPGA;

  • Applying dynamic values;

  • Initialising any external peripherals or co-processors;

  • Loading a user program. This can be:

    • from the first comport that presents data (Default); or

    • from a part of the Flash ROM's User Area.

  • Jumping to the entry point of the loaded program.

The SMT6001 includes bootloader files for all the standard Sundance TIM types.


FPGA data

The FPGA data block holds the FPGA bitstream information that the bootloader uses to configure the FPGA on the TIM. The SMT6001 installs FPGA data files for all the standard Sundance TIM types.

The SMT6001 uses a compressed bitstream: a Sundance Bitstream Fomat (.sbf) file. The SMT6001 provides a BIT to SBF converter.


Dynamic values

Dynamic values are applied by the bootloader immediately after the FPGA has been configured. This is useful in cases where features of the firmware might be enabled by writing values to predefined addresses. In a sense this is a similar concept to GEL files.

Any number of Dynamic values may be stored in the flash.


User data blocks

Users can store their own data in the flash. These user data blocks can be of the following types:

Pure Data

The user block contains binary data extracted from a file with no interpretation.

Executable Program

The user block contains an executable program. This is normally a CCS .out file.

Diamond Application

The block contains a Diamond application. This application may be for one or more processors.

S Record File

The user block contains data extracted from a file in Motorola-S format. This is described in section 9.9.3 if the Texas Instruments' publication TMS320C6x Assembly Language Tools. User's Guide.

The number of user data blocks that may be programmed is only limited by the available ROM space.


Executable Programs and Diamond Applications

A program (or Diamond application) that is loaded from ROM must be built to assume that there is no host processor available. This means that programs generated using Code Composer Studio must not use any of the stdio.h features. Diamond applications must only include tasks that have been linked as stand-alone tasks (using 3L ta myprog command in the *.cfg file, for example) and constructed using the configurer's "3L a myprog -a" switch.

The user specifies the "boot area" by using the Flash Programming Utility. When such an area is written to the ROM, the Flash Programming Utility automatically assumes that it should be enabled so that it will be executed following reset.


Flash Programming Utility

This section describes how to use the Flash Programming Utility part of the SMT6001 package.


Starting the program

The Flash Programming Utility is started by clicking on SmtFpu.exe in the installation directory, usually "C:\Program Files\Sundance\SMT6001". The installation procedure also puts a shortcut to the Flash Programming Utility in the Start menu:

"Start" -> "All Programs" -> "Sundance" -> "SMT6001" -> "Flash Programming Utility".

Once started, the Flash Programming Utility attempts to start Code Composer in the background. The following splash screen will appear.


Using the program

The main frame of the Flash Programming Utility contains a tab control from which you can select various sections to configure your TIM:

  • General,
  • User blocks,
  • Dynamics,
  • Advanced.


Selecting a target DSP

The top left of the main window contains a list of all the DSPs (CPUs) in the JTAG chain. This is where you select the DSP that you are interested in. TIMs with more than one DSP usually allow you to access the ROM from only one particular processor; this is commonly the first of the processors on the TIM (DSPA). DSPs that do not have access to the flash are marked with a red cross. DSPs that do have access to the flash are shown with a green tick.

You can switch between target DSPs at any time, and even request multiple operations on different DSPs. When you change your selection, the data to the right of the window will change to show the information for the new DSP.


General

The first tab of the Flash Programming Utility dialog shows the General settings.

This section is to select the target device (TIM type) and to specify its configuration.


TIM type

The Flash Programming Utility needs to know the type of each TIM it is handling before it can access the ROM correctly.

The Flash Programming Utility can automatically determine the type of the TIM that you are using if the ROM has already be programmed as it usually holds this information. In the case the ROM has not been programmed yet or has been erased for security reasons, you have to select the TIM type manually before committing any changes to the ROM.

To do so, use the "TIM" list box to specify which TIM type you are using. Clicking on the "Details" button on the right of the "TIM" list box will bring up a dialog box containing information about the TIM selected.

Please contact Sundance for assistance if the type of the TIM you are using does not appear on the list.


Bootloader and FPGA bitstream

The Flash Programming Utility allows you to program or update the Bootloader and FPGA sections. These two sections are completely independent and you can update either or both of them.

To select a bootloader, go in the "Bootloader" section. Usually the "Standard" button to the right will find the standard bootloader. However, Sundance may release modified bootloaders from time to time or you may need to use a custom-made bootloader. In these cases you can press the "Browse" button to browse for the file containing the appropriate bootloader.

You can select the FPGA data in a similar way using the "FPGA bitstream" section. You can use either the raw .bit, the old .dat or the new .sbf file formats. See "BIT to SBF converter" for more details.

During this process, you can check that the versions of the bootloader and FPGA data are as you expect.


User blocks

The second tab of the Flash Programming Utility dialog shows the User Blocks settings.

This section allows you to modify the user blocks of the Flash ROM.

You can manage the user blocks by either using the buttons at the bottom of the "User blocks" window or by selecting a user block and right clicking on it.


Adding user data

You can add your own user data to the flash ROM by selecting the "User blocks" tab and clicking the "Add" button, or dropping the files you wish to program into the right-hand area.

Clicking on the "Add" button displays the dialog shown below. You have the option of specifying a user ID value as well as a boot flag if the data is an executable block. (for example a diamond .app file, or a CCS .out file).

A version number can also be specified. All of these parameter can be changed afterwards.

When you have selected the file you wish to add, click "Open". Your data will be added to the list of users blocks. Note that at this stage nothing has been written to the ROM. To finish the procedure, click "Commit" button and the new data will be written to the flash.


Edit user block properties

You can edit the properties of a user data block by double clicking the entry in the list, or by selecting the entry and clicking the "Edit" button. The following dialog displays the block properties.

Note that the Flash Programming Utility may object if you attempt to change the "Type" of a user block. For example, it will not let you change from a raw data file to a diamond .app file.

Enabling and disabling the big-endian mode

The "Bigendian" flag specifies that the data in the file are to be interpreted in big-endian order (most significant byte first) when loaded from disk. The data are always stored in little-endian format in the flash; any necessary conversion is performed when the file is stored in the flash.

Enabling and disabling boot from flash

It is possible to specify that the processor should boot from executable data stored in the flash. This is only available for executable data. You may specify the data area that should be booted from by selecting it, and ticking "Boot from ROM" in the Block properties. Clicking it again will disable the boot from this area.

Note, it is usually arranged that the executable data is the first area programmed, because it might very well require the data areas stored after it to operate on.

For details about executable data see Executable Programs and Diamond Applications.


Delete user block

You delete a user block by selecting it and clicking the "Delete" button.


Verify user block properties

You can verify the contents of a user black by clicking on it and selecting "Verify".

The verify feature checks that the contents of the user block in the ROM match the contents of the file that was used to program the block. A message will inform you if the contents match or differ.


Update user block

The update feature checks the contents of the user block in flash against the contents of the file that was used to program the data. If they do not match, the Flash Programming Utility will reprogram the flash with the data from the file. This is useful if you want to make sure that the flash contain the most current data.


Dynamics

The third tab of the Flash Programming Utility dialog shows the Dynamics settings.

The bootloader can perform up to eight assignments of 32-bit values to memory locations at absolute addresses. This facility is usually only needed in unusual circumstances, such as to modify the internal comport connections on some multi-processor TIMs.

These assignments are made immediately after the FPGA has been configured but before any user code is loaded.

Adding a Dynamic Setting

Press "Add" under "Dynamics". This will bring up the following window:

Type in the required address and value, then press "OK".

You can type the values in hex by appending "0x" to the number. for example "0xFFE1"

Removing a Dynamic Setting

Select the setting to be removed and press "Delete". Pressing "Clear" erases all the dynamic values.

Editing a dynamic setting

Select the dynamic value to edit and click the "Edit" button.


Advanced

The fourth tab of the Flash Programming Utility dialog shows the Advanced settings.

This section is reserved for advanced users. The options provided here can destroy the data on the flash ROM so care must be taken when using it.

It may be necessary to remove all data from the ROM under certain circumstances. To do so, press the "Erase Flash" button. This will send a "chip erase" command to the ROM which will set every bit in the memory to 1. Be aware that this process is not quick and can take several minutes on a large ROM.

The "Reset flash" button will put the directory information stored in the flash into a default state.


Committing your changes

Committing the changes

Once the sections to be updated have been selected, you can program them by pressing the "Commit" button at the bottom right of the page. The Flash Programming Utility will not alter the contents of the ROM until you commit your changes. This could be a fairly lengthy process, and depends very much on the amount of data needing to be written as a result of your changes. A progress bar will show you how the update is proceeding.

The Flash Programming Utility will ask for confirmation if you try to close the program without committing your changes.

While the Flash ROM is being reprogrammed, a multicolour progress arrow appears in front of the DSP in the left CPUs list and a yellow spanner appears in front of the Bootloader and FPGA bitstream. When this spanner is replaced by a green tick, the Flash ROM is released and correctly programmed.

The TIM should be available for use once the Flash programming has been completed successfully.


BIT to SBF converter

This section describes how to use the BIT to SBF converter part of the SMT6001 software package.

In the past, Sundance provided firmware bitstreams in the DAT file format. This format has now been superseded by the SBF (Sundance Bistream Format) format. Sundance provides the BIT to SBF converter for customers who wish to convert their .bit files to .sbf files.

The Sundance Bitstream Format provides an easy way to embed some information (such as comments, version number ...) and compressed data inside a bitstream. Also the data inside the SBF file is converted into a format the FPGA expects.

Remark: As an extra feature this program converts also DAT file to SBF file. However it is not possible to add a version number and comments in that case.


Starting the program

The BIT to SBF converter is started by clicking on BitToSbf.exe in the installation directory, usually "C:\Program Files\Sundance\SMT6001". The installation procedure also puts a shortcut to the Flash Programming Utility in the Start menu:

"Start" -> "All Programs" -> "Sundance" -> "SMT6001" -> "BIT to SBF converter".

Once started, the BIT to SBF converter will appear as follows:


Using the program

Build parameters section

  • First you need to select the BIT file you want to convert into an SBF file. Use the button "..." to browse to the right file.

  • Then you can add some information that will be embedded in the SBF file.

Version number: You can add a version number if you wish. By default the version number will be 1.0

Comments: You can add some comments, for example about the implementation of the bitstream. Those comments will be displayed in the Flash Programming Utility when the SBF file is selected.

Target TIMs: You have to select at least one target for which the bitstream is valid. The Flash Programming Utility looks at this feature to determine if your hardware is compatible with the SBF file selected.

Output (.sbf) file section

As soon as the BIT file is selected, a SBF file name is generated automatically based on the name and location of the BIT file and the version number. If you wish to choose the name of the SBF file yourself, you can untick the "Auto-generate name" box and write directly in the "File" edit box the name of the SBF file. You can also browse to an existing file. Be careful, in that case the existed SBF file will be overwritten.

Build

When all the above have been done, you are ready to create the SBF file. To do so, just press the button "Build*.sbf". If the SBF file has been created successfully, a green tick will appear on the left of the "Build *.sbf" button. In case of a failure, the green tick will be replaced by a red cross. Once the SBF file has been built, the information contained in the BIT file will be displayed in the "Info" edit box.

You can now exit this utility program by pressing the button "Close".


Flash Access Library

This section describes how to use the Flash Access Library part of the SMT6001 package.

The Flash Access Library is a DSP library that allows you to create DSP programs that can write data to the flash, or read data from the flash.


Using the library

The Flash Access Library is installed with the SMT6001 package, usually "C:\Program Files\Sundance\SMT6001\Flash_access".

To use the Flash Access library you need to:

  • include the file flash_access.h in your source file
  • link flash_access.obj to your application


Functions Description

The Flash Access Library provides two files:

  • flash_access.h: contains the function prototypes.

  • flash_access.obj: contains the code.

The following functions are part of the flash_access library:

  • flash_lib_init

  • flash_lib_close

  • flash_user_count

  • flash_user_id

  • flash_user_index

  • flash_user_size

  • flash_user_read

  • flash_user_append

  • flash_user_mark_bootable

  • flash_user_erase

  • flash_get_error

 | flash_lib_init
Prototype: | UINT flash_lib_init (UINT flashaddr);
Parameters: | flashaddr | Base address of the flash ROM
Return value: | Returns FLASH_OK on success.
Notes: | This function initialises the flash access library.

 | flash_lib_close
Prototype: | UINT flash_lib_close (void);
Parameters: | None
Return value: | Returns FLASH_OK.
Notes: | This function leaves the flash in a valid state.

 | flash_user_count
Prototype: | UINT flash_user_count (UINT *count);
Parameters: | count | number of user blocks programmed in the flash.
Return value: | Returns FLASH_OK on success.
Notes: | This function sets the parameter to the number of user-blocks currently programmed in the flash.

 | flash_user_id
Prototype: | UINT flash_user_id (UINT index, UINT *id);
Parameters: | index | user block index.
 | id | user block ID.
Return value: | Returns FLASH_OK on success.
Notes: | This function sets the second parameter to the ID value for the user block with the given index.

 | flash_user_index
Prototype: | UINT flash_user_index (UINT id, UINT *index);
Parameters: | id | user block ID.
 | index | user block index.
Return value: | Returns FLASH_OK on success.
Notes: | This function sets the second parameter to the index of the user block with the given ID value.

 | flash_user_size
Prototype: | UINT flash_user_size (UINT index, UINT *bytes);
Parameters: | index | user block index.
 | bytes | size of the user block in bytes
Return value: | Returns FLASH_OK on success.
Notes: | This function sets the second parameter to the size in bytes of the user-block with the given index. The size will always be a multiple of four.

 | flash_user_read
Prototype: | UINT flash_user_read (UINT index, UINT offset, UINT bytes, UINT *buf, UINT *read);
Parameters: | index | user block index.
 | offset | user block offset from where to read
 | bytes | size of the user block to read
 | buf | data read
 | read | number of bytes read
Return value: | Returns FLASH_OK on success.
Notes: | This function reads data from the user-block with the given index. The given number of bytes are read starting at the given byte offset from the start of the area.

 | flash_user_append
Prototype: | UINT flash_user_append (UINT id, UINT bytes, UINT *buf);
Parameters: | id | user block ID.
 | bytes | size of the user block to append
 | buf | data to append
Return value: | Returns FLASH_OK on success.
Notes: | This function appends a user block. If no user-block with the given ID value can be found, a new empty one is created as the final area and is assigned the ID value. The given number of bytes are transfered from buf to the end of the area. Any user-blocks with greater index values will be deleted by this operation.

 | flash_user_mark_bootable
Prototype: | UINT flash_user_mark_bootable(UINT Id, UINT type, UINT boot);
Parameters: | id | user block ID.
 | type | data type: program (0x01), application (0x02), data (0x10) or srecord (0x11)
 | boot | 1 to mark the data bootable 0 otherwise
Return value: | Returns FLASH_OK on success.
Notes: | This function marks a user block as bootable. If no user-block with the given ID value can be found the function returns an error. It is the user's responsibility to mark as bootable data that can be executed. The flash library doesn't check the format of the data mark as bootable and will not return an error if the data is not valid. Use CoffImage.exe to convert an executable file into a comport data file. A comport data file contains all the loaded sections of the executable file in such a format that it can be understood by the Sundance boot loaders.

 | flash_user_erase
Prototype: | UINT flash_user_erase (UINT index);
Parameters: | index | user block index.
Return value: | Returns FLASH_OK on success.
Notes: | This function erases all user-blocks starting at the given index position. flash_user_erase(0) will erase all user-blocks.

 | flash_get_error
Prototype: | CCHAR *flash_get_error (UINT error);
Parameters: | error | error code
Return value: | Returns FLASH_OK on success.
Notes: | This function returns a string representation of the given error code.


Examples

Examples for the Flash Access Library are installed with the SMT6001 package, usually "C:\Program Files\Sundance\SMT6001\Examples". The installation procedure also puts a shortcut to the examples in the Start menu:

"Start" -> "All Programs" -> "Sundance" -> "SMT6001" -> "Open examples".

Example | Description
FlashDataCount.c | Shows how to read the number of user data blocks from the flash.
FlashDataErase.c | Shows how to erase a user data block from the flash.
FlashDataId.c | Shows how to get the ID value for a user data block given its index value.
FlashDataIndex.c | Shows how to get the index value for a user data block given its ID value.
FlashDataRead.c | Shows how to read data from a user data block in the flash.
FlashDataSize.c | Shows how to get the size of a user data block.
FlashDataWrite.c | Shows how to write data to a user data block in the flash.
FlashDataMarkBootable.c | Shows how to mark data that is already in the flash as bootable.

A makefile is included to build all of the examples. You can build the examples by running make.exe from a command line.


Converting from executable to Comport Data File

The flash_access library is a basic library whose one of the feature is to write raw data into the flash. The function flash_user_mark_bootable allows the user to make this data bootable from flash. To boot properly this data has to be recognised by the Sundance bootloaders.

The utility CoffImage to convert a coff file into a Comport Data File which contains all the loaded sections of the executable file in such a format that it can be understood by the Sundance bootloaders.


Using the program

1- Open a command prompt where the SMT6001 has been installed, usually "C:\Program Files\Sundance\SMT6001".

2- Type the following command line:

CoffImage [Source] [Output] \T[TIMType] [\N]

For example: CoffImage file.out output.bin \TSMT395 \N

where: \N = Target used with the new bootloader format
TIMType is one of the valid TIM types.

Remarks:

  • For a complete list of TIM types use:

    CoffImage \L

  • To download the file to the DSP via host comport use:

    CoffImage \D[boardno]


Console Application

This section describes how to use the console application (fpu.exe) part of the SMT6001 package to program the Flash ROM from a command line.


Using the program

1- Open a command prompt where the SMT6001 has been installed, usually "C:\Program Files\Sundance\SMT6001".

2- Type the following command line:

fpu -t[timtype] -b[bootloader] -f[firmware]

where: -t = TIM type, for example SMT361Q
-b = name of the bootloader file
-f = name of the firmware file


Saving FPGA configuration data to file

Sundance provides the GetRawData utility for customers who wish to save the FPGA configuration data into a file.

The raw FPGA data can particularly be useful when using the SMT6025 to configure an FPGA module on the first TIM site of a carrier board or when using FPGA Diamond.


GetRawData: Using the program

Using the program

1- Open a command prompt where the SMT6001 has been installed, usually "C:\Program Files\Sundance\SMT6001".

2- Type the following command line:

GetRawData -b[BitFile] -r[RawDataFile] -k[AddKeys]

where: | BitFile | = | The full path of the bit file
 | RawDataFile | = | The full path of the file where the raw FPGA data will be written. If no file is specify, the raw data will be copy in the same directory as the original bitstream with the extension *.rfd (Raw FPGA Data).
 | AddKeys | = | 1 if the start and end keys should be part of the raw data otherwise 0


Further information

This section provides detailed information about the format of data used by the SMT6001. This will only be of interest to customers wishing to modify or somehow extend the functionality provided by the SMT6001.


The bootloader

The bootloader passes the following registers into the loaded program:

Register | Meaning | Notes
a6 | Boot link number (or -1 when booted from flash ROM) |
a8 | Base address of the FPGA |
a10 | Load checking flag. (0=don't check) |
b6 | TIM type |
b4 | Offset of the next flash word. (When booted from flash ROM) |
b8 | Base address of the flash ROM |
b12 | External memory descriptor |

Note: The state of all the other registers is undefined.


TIM Numbering

Rational

  1. TIMs are identified from the information contained in the flash. The scheme gives a unique number to each possible TIM variant that Sundance is likely to produce.
  2. It provides a simple way to map from the code to a descriptive text string.
  3. There are several classes of TIM that need to be distinguished: currently Processor, ADC/DAC, and FPGA.
  4. Within each class, there are many types of TIM.
  5. Some TIMs are simply minor variants of others. This are indicated this with a "variant" field, rather than make a completely new type.
  6. There is a lot of information that could be encoded, but space is limited to 32 bits. As long as significantly different modules have different codes, information not included in the code is provided in a separate table, not held in the TIM.
  7. Different classes will need to use different units (and resolution) for external memory. These are implied by the class. Some TIMs need to be able to indicate no external memory.
  8. Diamond checks that the TIM actually being used matches the TIM specified in the configuration file. It is possible simply to look for an exact match, but this would prevent an application built for a TIM with 128MB of memory (say) being allowed to run on a TIM that was identical except for having 256MB of memory. It is therefore possible to make simple comparisons of the form "types equal and memory not less than that needed".

Assumptions

  1. There are currently 3 classes of TIM: Processor, ADC/DAC, and FPGA. I assume that this list will grow slightly, but will never exceed 8 classes.
  2. There will never be more than 1024 types of any class.
  3. There will never be more than 7 variants of a type.
  4. Processor TIMs will never need a finer memory resolution than 64KB.

Implementation

 | 31..15 | 15..13 | 12..3 | 2..0
Unknown |  |  |  | 0
Processor | Memory | Variant | Type | 1
ADC/DAC | Memory | Variant | Type | 2
FPGA | Memory | Variant | Type | 3

Type | An integer in the range 1..1023 – plenty of values – giving a code for the basic type of the TIM (1=SMT376, 2=SMT361, or whatever) independent of variation or memory size. Type would be allocated from a central register, with the values being kept dense (1, 2, 3,... rather than 1, 99, 267, 1001...). A 0 Type indicates an unknown TIM type.
Variant | An integer in the range 0..7 giving the variant of the basic type (e,g, to distinguish 365 and 365E). The standard type would have Variant=0
Memory | An integer in the range 0..216-1 giving the size of the external memory. The units depend on the class:
 | 1 | 64KB
 | 2 | 512KB
 | 3 | 1MB


Troubleshooting

This section describes potential problems in using the SMT6001 and how to solve them.


General

The SmtFlash hangs at start-up when I try to use it.

1- Code Composer Studio is not configured properly

Solution: Open Code Composer Setup program and configure it accordingly to your hardware set-up. Note that when using Code Composer Studio 3.00 or above, you need to open CCS and connect to the target DSP before starting the Flash Programming Utility utility.

2- or another Sundance instance of the software is already running.

Solution: Close one of the instance of the Flash Utility Program. You may need to kill the process SmtFpu.exe from the Task Manager window.

The SmtFlash utility reports errors when I try to use it.

Solution: Make sure you have selected the correct type of module from the list on the "General" tab.


Using the program

This section describes how to use the SMT6001 application.