Hex Utility in CCS
In CCSv6 and higher, the Hex Utility is integrated into the CCS GUI under Project Properties->Build. You can directly enable the Hex Utility from there and have access to all the options supported by the utility.
As there are several hex output formats and other options supported by the hex utility, before generating a hex output it is important to be aware of the requirements of the tool that will be reading in the hex file (typically a flash programmer).
The hex utility supports a plethora of options that are documented in the Assembly Language Tools Users Guide. Please refer to the Users Guide for the processor family you are working with.
Hex output files
The key options discussed in this article are hex output format, and memwidth and romwidth options.
Memory width is the physical width (in bits) of the memory system, which is usually the same width as the target processor width, (ie) a 16-bit processor has a 16-bit memory architecture. However, some applications may require target words to be broken into multiple, consecutive, and narrower memory words. By default, the hex conversion utility sets memory width to the target width, but this can be changed using the --memwidth option.
ROM width determines how the hex utility partitions the data into output files. In older hex programmers, ROM width was used to specify the physical width (in bits) of each ROM device. After the object file data is mapped to the memory words, the memory words are broken into one or more output files. Most modern flash programmers don't require a specific ROM width, but it is best to check if the programmer imposes any restrictions.
The values specified for memwidth and romwidth determine the number of hex output files:
- If memory width ≥ ROM width: number of files = memory width ÷ ROM width
- If memory width < ROM width: number of files = 1
For example, for a memory width of 16, you could specify a ROM width value of 16 and get a single output file containing 16-bit words. Or you can use a ROM width value of 8 to get two files, each containing 8 bits of each word.
The default ROM width that the hex conversion utility uses (when one is not explicitly specified) depends on the output format:
- For all hex formats except TI-Tagged the default ROM width is 8 bits.
- For TI-Tagged the default ROM width is 16 bits.
So for example, if you are working with a Cortex ARM device (that has a default memory width of 32), and you select the Intel hex format (with a default ROM width set to 8), the hex utility will generate 4 output hex files. To get a single output file, you can set the --romwidth option to 32.
Default options set by CCS
When a new project is created in CCSv6, for certain devices (such as MSP430) the values of romwidth and memwidth are set to be 8.
But these defaults may not be set for all devices, so be sure to double-check these options if the hex output is not what you are expecting or does not produce the expected behavior after programming.
Passing a hex command file
The hex utility can accept command files, which are nothing but ASCII files that contain additional options and/or ROMS and SECTIONS directives. However, in CCSv6, the Hex Utility in the GUI does not have a built-in method to pass the command file. As a workaround, you can pass the command file by adding the file name to the command-line pattern as shown below. The path to the file can be absolute or relative (to the build configuration directory such as \Debug or \Release).
NOTE: If you have a file with .cmd extension (such as hex.cmd) in the project directory, or any sub-directory within the project directory, the linker will think it is a linker command file and try to use it during linking (which is not desired as this command line is only applicable to the hex utility). To avoid this, you can either:
- right-click on the hex.cmd file in the Project Explorer view and select "Exclude from build", or
- name the file with a different extension and change the above command-line pattern accordingly.