<
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 User's Guide. Please refer to the [User's Guide](https://www.ti.com/tool/TI-CGT#technicaldocuments) for the processor family you are working with.
#Hex Output Files
The key options discussed in this page 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.
##C2000
If the executable (.out) file contains sections allocated to multiple pages, then separate output files will be generated for each page.
For example, if the linker command file allocates some initialized sections (like .text) to Page 0 and others (like .econst) to Page 1, then the hex utility will generate two output files. This is easy to overlook as you may only be expecting a single .hex output file. Since the output is in two files, loading just one .hex file using the Flash programmer is not sufficient for the program to work properly.
In newer compiler releases, a diagnostic will be issued whenever the hex utility creates additional output files that are not explicitly named by the user.
To fix the issue, change the linker command file so that all initialized sections are allocated to Page 0. Then all the sections will be converted into a single hex file.
To see the names of all intialized sections generated by the compiler take a look at the [C28x Compiler User's Guide](https://www.ti.com/lit/spru514).
#Default Options Set by CCS
When a new project is created for certain devices (such as MSP430) the values of romwidth and memwidth may be pre-set. In the case of MSP430 it defaults to 8.
Note that 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, 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. This is not desired as this command line is only applicable to the hex utility. To avoid this, 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.
<!-- End of markdown source -->
<div id="footer"></div>
]]>