16.2. Invoking the Hex Conversion Utility¶

There are two basic methods for invoking the hex conversion utility:

Specify the options and filenames on the command line. The following example converts the file firmware.out into TI-Tagged format, producing two output files, firm.lsb and firm.msb:
```
tiarmhex -t firmware -o firm.lsb -o firm.msb
```
Specify the options and filenames in a command file. You can create a file that stores command line options and filenames for invoking the hex conversion utility. The following example invokes the utility using a command file called hexutil.cmd:
```
tiarmhex hexutil.cmd
```

In addition to regular command line information, you can use the hex conversion utility ROMS and SECTIONS directives in a command file.

16.2.1. Invoking the Hex Conversion Utility From the Command Line¶

To invoke the hex conversion utility, enter:

tiarmhex [options] filename

tiarmhex is the command that invokes the hex conversion utility.
options supplies additional information that controls the hex conversion process. You can use options on the command line or in a command file. Hex Conversion Utility Options lists the available options.
- All options are preceded by a hyphen and are not case sensitive.
- Several options have an additional parameter that must be separated from the option by at least one space.
- Options with multi-character names must be spelled exactly as shown in this document; no abbreviations are allowed.
- Options are not affected by the order in which they are used. The exception to this rule is the --quiet option, which must be used before any other options.
filename names an object file or a command file. (For more information, see Invoking the Hex Conversion Utility With a Command File.)

16.2.2. Hex Conversion Utility Options¶

In the following list, the shortened alias (if any) is shown in parentheses after the option. Unless otherwise specified, the alias expects the same parameters as the main option syntax.

General Options

--byte (-byte)¶

Syntax: --byte

Number output locations by bytes rather than by target addressing. See Controlling the ROM Device Address.

--entrypoint (-e)¶

Syntax: --entrypoint=addr

Specify the entry point at which to begin execution after boot loading. See How to Build the Boot Table.

--exclude (-exclude)¶

Syntax: --exclude={fname(sname) |sname}

If the filename (fname) is omitted, all sections matching sname will be excluded. See Excluding a Specified Section.

--fill (-fill)¶

Syntax: --fill=value

Fill holes with value. See Specifying a Fill Value.

--help (-options, -h)¶

Syntax: --help

Display the syntax for invoking the utility and list available options. If the option is followed by another option or phrase, detailed information about that option or phrase is displayed. See Invoking the Hex Conversion Utility With a Command File.

--image (-image)¶

Syntax: --image

Select image mode. See Generating a Memory Image.

--linkerfill (-linkerfill)¶

Syntax: --linkerfill

Include linker fill sections in images. See Filling Holes.

--map (-map)¶

Syntax: --map=filename

Generate a map file. See An Example of the ROMS Directive.

--memwidth (-memwidth)¶

Syntax: --memwidth=value

Define the system memory word width (default 16 bits). See Specifying the Memory Width.

--outfile (-o)¶

Syntax: --outfile=filename

Specify an output filename. See Assigning Output Filenames.

--quiet (-q)¶

Syntax: --quiet

Run quietly. If used, this option must appear before other options. See Invoking the Hex Conversion Utility With a Command File.

--romwidth (-romwidth)¶

Syntax: --romwidth=value

Specify the ROM device width (default depends on format used). This option is ignored for the TI-TXT, binary, and TI-Tagged formats. See Partitioning Data Into Output Files.

--zero (-zero, -z)¶

Syntax: --zero

Reset the address origin to 0 in image mode. See Steps to Follow in Using Image Mode.

Diagnostic Options

The hex conversion utility uses certain C/C++ compiler options to control hex-converter-generated diagnostics. See Control Hex Conversion Utility Diagnostics for information about the diagnostic options.

--diag_error¶

Syntax: --diag_error=id

Categorizes the diagnostic identified by id as an error.

--diag_remark¶

Syntax: --diag_remark=id

Categorizes the diagnostic identified by id as a remark.

--diag_suppress¶

Syntax: --diag_suppress=id

Suppresses the diagnostic identified by id.

--diag_warning¶

Syntax: --diag_warning=id

Categorizes the diagnostic identified by id as a warning.

--display_error_number¶

Syntax: --display_error_number

Displays a diagnostic message’s identifiers along with its text.

--issue_remarks¶

Syntax: --issue_remarks

Issues remarks (non-serious warnings).

--no_warnings¶

Syntax: --no_warnings

Suppresses all warning diagnostics. Errors are still issued.

--set_error_limit¶

Syntax: --set_error_limit=count

Sets the error limit to count. The linker abandons linking after the specified number of errors. (The default is 100.)

Boot Options

--boot_align_sect¶

Syntax: --boot_align_sect

Causes boot table records to be aligned to the section alignment. See Building a Table for an On-Chip Boot Loader.

--boot_block_size=size¶

Syntax: --boot_block_size=size

Set the desired block size for output from the hex conversion utility. The size may be specified as a hex or decimal value. The default size is 65535 (0xFFFF). For ARM targets, the boot block size refers to 8-bit bytes. See Building a Table for an On-Chip Boot Loader.

--cmac=file¶

Syntax: --cmac=file

Specify a file containing the CMAC key for use with secure flash boot on TMS320F2838x devices. See Using Secure Flash Boot on TMS320F2838x Devices.

Output Options

The hex conversion utility provides several options to specify the output format. These options are described in Description of the Object Formats and its subsections.

--array¶

Syntax: --array

Select array output format. See Array Output Format.

--ascii (-a)¶

Syntax: --ascii

Select the ASCII-Hex output format. See ASCII-Hex Object Format (--ascii Option).

--binary (-b)¶

Syntax: --binary

Select the binary output format. (The object file must have a memory width of 8 bits.) See Binary Object Format (--binary Option).

--intel (-i)¶

Syntax: --intel

Select the Intel output format. See Intel MCS-86 Object Format (--intel Option).

--motorola=1 (-m1)¶

Syntax: --motorola=1

Select the Motorola-S1 output format. See Motorola Exorciser Object Format (--motorola Option).

--motorola=2 (-m2)¶

Syntax: --motorola=2

Select the Motorola-S2 output format. See Motorola Exorciser Object Format (--motorola Option).

--motorola=3 (-m3)¶

Syntax: --motorola=3

Select the Motorola-S2 output format. See Motorola Exorciser Object Format (--motorola Option).

--tektronix (-x)¶

Syntax: --tektronix

Select the Tektronix output format. This is the default when no output format is specified. See Extended Tektronix Object Format (--tektronix Option).

--ti_tagged (-t)¶

Syntax: --ti_tagged

Select the TI-Tagged output format. (The object file must have a memory width of 16 bits.) See Texas Instruments SDSMAC (TI-Tagged) Object Format (--ti_tagged Option).

--ti_txt¶

Syntax: --ti_txt

Select the TI-Txt output format. (The object file must have a memory width of 8 bits.) See TI-TXT Hex Format (--ti_txt Option).

Load Image Options

The hex conversion utility provides several options to specify the load image and its format. These options are described in The Load Image Format (--load_image Option) and its subsections.

--load_image¶

Syntax: --load_image

Select load image object file format. See The Load Image Format (--load_image Option).

--load_image:combine_sections¶

Syntax: --load_image:combine_sections=[true|false]

Specify whether sections should be combined or not. The default is true.

--load_image:endian¶

Syntax: --load_image:endian=[big|little]

Specify the object file endianness. If this option is omitted, the endianness of the first file on the command line is used.

--load_image:file_type¶

Syntax: --load_image:file_type=[relocatable|executable]

Specify a file type other than object files. Object files can be linked with one another, but addresses are lost. Relocatable files contain the address in the sh_addr field of a section. Executable files maintain address bindings and can be directly loaded.

--load_image:format¶

Syntax: --load_image:format=[coff|elf]

Specify the ABI format of the object file. If this option is omitted, the format is determined from the first file on the command line.

--load_image:globalize¶

Syntax: --load_image:globalize=string

Do not localize the specified symbol. The default can be set with the –load_image:symbol_binding option.

--load_image:localize¶

Syntax: --load_image:localize=string

Make the specified symbol local. The default can be set with the –load_image:symbol_binding option.

--load_image:machine¶

Syntax: --load_image:machine=[ARM|C2000|C6000|C7X|MSP430|PRU]

Specify the object file machine type. If this option is omitted, the machine type from the first file on the command line is used.

--load_image:output_symbols¶

Syntax: --load_image:output_symbols=[true|false]

Specify whether symbols should be output to the file. The default is false.

--load_image:section_addresses¶

Syntax: --load_image:section_addresses=[true|false]

Specify whether the load address should be written in the output file. This option applies to relocatable files only. The default is true.

--load_image:section_prefix¶

Syntax: --load_image:section_prefix=string

Specify a prefix for section names. The default is image_.

--load_image:symbol_binding¶

Syntax: --load_image:symbol_binding=[local|global]

Specify the default binding of symbols in the load image.

16.2.3. Invoking the Hex Conversion Utility With a Command File¶

A command file is useful if you plan to invoke the utility more than once with the same input files and options. It is also useful if you want to use the ROMS and SECTIONS hex conversion utility directives to customize the conversion process.

Command files are ASCII files that contain one or more of the following:

Options and filenames. These are specified in a command file in exactly the same manner as on the command line.
ROMS directive. The ROMS directive defines the physical memory configuration of your system as a list of address-range parameters. (See The ROMS Directive.)
SECTIONS directive. The hex conversion utility SECTIONS directive specifies which sections from the object file are selected. (See The SECTIONS Directive.)
Comments. You can add comments to your command file by using the /* and */ delimiters. For example:
```
/* This is a comment. */
```

To invoke the utility and use the options you defined in a command file, use a command with syntax like this:

tiarmhex command_filename

You can also specify other options and files on the command line. For example, you could invoke the utility by using both a command file and command line options:

tiarmhex firmware.cmd --map=firmware.mxp

The order in which these options and filenames appear is not important. The utility reads all input from the command line and all information from the command file before starting the conversion process. However, if you are using the -q option, it must appear as the first option on the command line or in a command file.

The --help option displays the syntax for invoking the compiler and lists available options. If the --help option is followed by another option or phrase, detailed information about the option or phrase is displayed. For example, to see information about options associated with generating a boot table use --help boot.

The --quiet option suppresses the hex conversion utility’s normal banner and progress information.

Assume that a command file named firmware.cmd contains these lines:

firmware.out           /* input file */
--ti-tagged            /* TI-Tagged */
--outfile=firm.lsb     /* output file */
--outfile=firm.msb     /* output file */

You can invoke the hex conversion utility by entering:

tiarmhex firmware.cmd

This example shows how to convert a file called appl.out into eight hex files in Intel format. Each output file is one byte wide and 4K bytes long.

appl.out           /* input file   */
--intel            /* Intel format */
--map=appl.mxp     /* map file     */

ROMS
{
    ROW1: origin=0x00000000 len=0x4000 romwidth=8
          files={ appl.u0 appl.u1 app1.u2 appl.u3 }
    ROW2: origin=0x00004000 len=0x4000 romwidth=8
          files={ app1.u4 appl.u5 appl.u6 appl.u7 }
}

SECTIONS
{
    .text, .data, .cinit, .sect1, .vectors, .const, .rodata:
}