Syntax

-a

For use with

ielfdumpriscv

Description

Use this option as a shortcut for ‑‑all ‑‑no_strtab.

Syntax

‑‑all

For use with

ielfdumpriscv

Description

Use this option to include the contents of all ELF sections in the output, in addition to the general properties of the input file. Sections are output in index order, except that each relocation section is output immediately after the section it holds relocations for.

By default, no section contents are included in the output.

Syntax

‑‑bin[=range]

Parameters

See Specifying ielftool address ranges.

For use with

ielftool

Description

Sets the format of the output file to raw binary, a binary format that includes only the raw bytes, with no address information. If no range is specified, the output file will include all the bytes from the lowest address for which there is content in the ELF file to the highest address for which there is content. If a range is specified, only bytes from that range are included. Note that in both cases, any gaps for which there is no content will be generated as zeros.

Syntax

‑‑bin-multi[=range[;range...]]

Parameters

See Specifying ielftool address ranges.

For use with

ielftool

Description

Use this option to produce one or more raw binary output files. If no ranges are specified, a raw binary output file is generated for each range for which there is content in the ELF file. If ranges are specified, a raw binary output file is generated for each range specified for which there is content. In each case, the name of each output file will include the start address of its range. For example, if the output file is specified as out.bin and the ranges 0x0-0x1F and 0x8000-0x8147 are output, there will be two files, named out-0x0.bin and out-0x8000.bin.

Syntax

‑‑code

For use with

ielfdumpriscv

Description

Use this option to dump all sections that contain executable code—sections with the ELF section attribute SHF_EXECINSTR.

Syntax

‑‑create libraryfileobjectfile1 ... objectfileN

Parameters

See also Rules for specifying a filename or directory as parameters.

For use with

iarchive

Description

Use this command to build a new library from a set of object files (modules) and/or archive files. The modules are added to the library in the order that they are specified on the command line.

If no command is specified on the command line, ‑‑create is used by default.

Syntax

‑‑delete libraryfile objectfile1 ... objectfileN
-d libraryfile objectfile1 ... objectfileN

Parameters

See also Rules for specifying a filename or directory as parameters.

For use with

iarchive

Description

Use this command to remove object files (modules) from an existing library. All object files that are specified on the command line will be removed from the library.

Syntax

‑‑disasm_data

For use with

ielfdumpriscv

Description

Use this command to instruct the dumper to dump data sections as if they were code sections.

Syntax

‑‑edit steering_file

Parameters

See Rules for specifying a filename or directory as parameters.

For use with

isymexport

Description

Use this option to specify a steering file for controlling which symbols are included in the isymexport output file, and if desired, also for renaming some of the symbols.

See also

Steering files.

Syntax

‑‑export_locals [=symbol_prefix]

Parameters

For use with

isymexport

Description

Use this option to export local symbols from a ROM image file, in addition to absolute symbols. The default name of the exported symbol is LOCAL_filename_symbolname. Use the optional parameter symbol_prefix to replace LOCAL with your custom prefix.

Example

When exported from the ROM image file, the symbol symb in the source file myFile.c becomes LOCAL_myFile_c_symb.

Syntax

‑‑extract libraryfile [objectfile1 ... objectfileN]
-x libraryfile [objectfile1 ... objectfileN]

Parameters

See also Rules for specifying a filename or directory as parameters.

For use with

iarchive

Description

Use this command to extract object files (modules) from an existing library. If a list of object files is specified, only these files are extracted. If a list of object files is not specified, all object files in the library are extracted.

Syntax

‑‑fake_time

For use with

iarchive

Description

Use this option to generate library files with identical timestamps. The value used is 0x5CF00000, which corresponds to approximately 30th May 2019 at 18:08:32 (the exact time will vary depending on the time settings). This option enables you to generate identical libraries for identical object files. Without this option, the timestamp will generate unique library files from the same input files.

Syntax

‑‑fill [v;]pattern;range[;range...]

Parameters

See also Specifying ielftool address ranges.

For use with

ielftool

Description

Use this option to fill all gaps in one or more ranges with a pattern, which can be either an expression or a hexadecimal string. The contents will be calculated as if the fill pattern was repeatedly filled from the start address until the end address is passed, and then the real contents will overwrite that pattern.

You might want to take alignment into consideration. If you generate fill that will be accessed by half-word or word accesses, you should ensure that the addresses in the filler range are half-word or word aligned.

If the ‑‑fill option is used more than once on the command line, the fill ranges cannot overlap each other.

Syntax

‑‑front_headers

For use with

ielftool

Description

Use this option to output ELF program and section headers in the beginning of the file, instead of at the end.

Syntax

‑‑ihex

For use with

ielftool

Description

Sets the format of the output file to 32-bit linear Intel Extended hex, a hexadecimal text format defined by Intel.

Syntax

‑‑ihex-len=length

Parameters

For use with

ielftool

Description

Sets the maximum number of data bytes in an Intel Hex record. This option can only be used together with the ‑‑ihex option. By default, the number of data bytes in an Intel Hex record is 16.

Syntax

‑‑json

For use with

ielfdumpriscv

Description

Use this option to format the output from ielfdumpriscv in JSON format. The information is the same as without the ‑‑json option, it is merely output in a machine-readable format. However, an important difference is the behavior of ‑‑all, ‑a, and similar options. Without the ‑‑json option, the first dump is information from the ELF header, and subsequent dumps are by each section in turn. With the --json option, a single large object is produced.

The JSON format contains descriptions of all fields and is recommended if you want explanations of the output.

See also

‑‑just_json

Syntax

‑‑json_schema

For use with

ielfdumpriscv

Description

Output from ielfdumpriscv can be generated in JSON format, by using the option ‑‑json. Use this option to generate the JSON schema. The schema contains descriptions of all fields.

See also

‑‑json

Syntax

--just_json

For use with

ielfdumpriscv

Description

Use this option to format the output from ielfdumpriscv in JSON format, without implicitly setting other options that make the output more machine-readable, like the option --json does.

See also

‑‑json

Syntax

‑‑no_bom

For use with

iarchive, ielfdumpriscv, iobjmanip, and isymexport

Description

Use this option to omit the Byte Order Mark (BOM) when generating a UTF-8 output file.

See also

‑‑text_out and Text encodings

Syntax

‑‑no_header

For use with

ielfdumpriscv

Description

By default, a standard list header is added before the actual file content. Use this option to suppress output of the list header.

Syntax

‑‑no_rel_sections

For use with

ielfdumpriscv

Description

By default, whenever the contents of a section of a relocatable file are generated as output, the associated section, if any, is also included in the output. Use this option to suppress output of the relocation sections.

Syntax

‑‑no_strtab

For use with

ielfdumpriscv

Description

Use this option to suppress dumping of string table sections (sections of type SHT_STRTAB).

Syntax

‑‑no_utf8_in

For use with

ielfdumpriscv

Description

The dumper can normally determine whether ELF files produced by IAR tools use the UTF-8 text encoding or not, and produce the correct output. For ELF files produced by non-IAR tools, the dumper will assume UTF-8 encoding unless this option is used, in which case the encoding is assumed to be according to the current system default locale.

See also

Text encodings

Syntax

‑‑offset [-]offset

Parameters

For use with

ielftool

Description

Use this option to add or subtract an offset to the address of each output record in the generated output file. The option only works on Motorola S-records, Intel Hex, TI-Txt, and Simple-Code. The option has no effect when generating an ELF file or when binary files (‑‑bin contain no address information) are generated. No content, including the entry point, will be changed by using this option, only the addresses in the output format.

Example

‑‑offset 0x30000

This will add an offset of 0x30000 to all addresses. As a result, content that was linked at address 0x4000 will be placed at 0x34000.

Syntax

-o {filename|directory} 
‑‑output {filename|directory} 

Parameters

See Rules for specifying a filename or directory as parameters.

For use with

iarchive and ielfdumpriscv.

Description

iarchive

By default, iarchive assumes that the first argument after the iarchive command is the name of the destination library. Use this option to explicitly specify a different filename for the library.

ielfdumpriscv

By default, output from the dumper is directed to the console. Use this option to direct the output to a file instead. The default name of the output file is the name of the input file with an added id filename extension

You can also specify the output file by specifying a file or directory following the name of the input file.

Syntax

‑‑parity{symbol[+offset]|address}:size,algo:flashbase[:flags];range[;range...]

Parameters

For use with

ielftool

Description

Use this option to generate parity bytes over specified ranges. The range is traversed left to the right and the parity bits are generated using the odd or even algorithm. The parity bits are finally stored in the specified symbol where they can be accessed by your application.

Syntax

‑‑ram_reserve_ranges[=symbol_prefix]

Parameters

For use with

isymexport

Description

Use this option to generate symbols for the areas in RAM that the image uses. One symbol will be generated for each such area. The name of each symbol is based on the name of the area and is prefixed by the optional parameter symbol_prefix.

Generating symbols that cover an area in this way prevents the linker from placing other content at the affected addresses. This can be useful when linking against an existing image.

If ‑‑ram_reserve_ranges is used together with ‑‑reserve_ranges, the RAM areas will get their prefix from the ‑‑ram_reserve_ranges option and the non-RAM areas will get their prefix from the ‑‑reserve_ranges option.

See also

‑‑reserve_ranges.

Syntax

‑‑range start-end

Parameters

For use with

ielfdumpriscv

Description

Use this option to specify a range for which code from an executable will be dumped.

Syntax

‑‑raw

For use with

ielfdumpriscv

Description

By default, many ELF sections will be dumped using a text format specific to a particular kind of section. Use this option to dump each selected ELF section using the generic text format.

The generic text format dumps each byte in the section in hexadecimal format, and where appropriate, as ASCII text.

Syntax

--raw_io

For use with

ielfdumpriscv

Description

Use this option to make ielfdumpriscv generate maximum machine-readable output, without, for example, extra newline characters. Note that this option also sets the option ‑‑no_bom implicitly.

Syntax

‑‑remove_file_path

For use with

iobjmanip

Description

Use this option to make iobjmanip remove information about the directory structure of the project source tree from the generated object file, which means that the file symbol in the ELF object file is modified.

This option must be used in combination with ‑‑remove_section ".comment".

Syntax

‑‑remove_section {section|number}

Parameters

For use with

iobjmanip

Description

Use this option to make iobjmanip omit the specified section when generating the output file.

Syntax

‑‑rename_section {oldname|oldnumber}=newname

Parameters

For use with

iobjmanip

Description

Use this option to make iobjmanip rename the specified section when generating the output file.

Syntax

‑‑rename_symbol oldname =newname

Parameters

For use with

iobjmanip

Description

Use this option to make iobjmanip rename the specified symbol when generating the output file.

Syntax

‑‑replace libraryfile objectfile1 ... objectfileN
-r libraryfile objectfile1 ... objectfileN

Parameters

See also Rules for specifying a filename or directory as parameters.

For use with

iarchive

Description

Use this command to replace or add object files (modules) and/or archive files to an existing library. The modules specified on the command line either replace existing modules in the library—if they have the same name—or are appended to the library.

Syntax

‑‑reserve_ranges[=symbol_prefix]

Parameters

For use with

isymexport

Description

Use this option to generate symbols for the areas in ROM and RAM that the image uses. One symbol will be generated for each such area. The name of each symbol is based on the name of the area and is prefixed by the optional parameter symbol_prefix.

Generating symbols that cover an area in this way prevents the linker from placing other content at the affected addresses. This can be useful when linking against an existing image.

If ‑‑reserve_ranges is used together with ‑‑ram_reserve_ranges, the RAM areas will get their prefix from the ‑‑ram_reserve_ranges option and the non-RAM areas will get their prefix from the ‑‑reserve_ranges option.

See also

‑‑ram_reserve_ranges.

Syntax

‑‑section sec_number|sec_name[,...]
‑s sec_number|sec_name[,...]

Parameters

For use with

ielfdumpriscv

Description

Use this option to dump the contents of a section with the specified number, or any section with the specified name. If a relocation section is associated with a selected section, its contents are output as well.

If you use this option, the general properties of the input file will not be included in the output.

You can specify multiple section numbers or names by separating them with commas, or by using this option more than once. If a specified section cannot be found, its contents are excluded from the output but the contents of all other segments are included.

By default, no section contents are included in the output.

Example

-s 3,17                  /* Sections #3 and #17
-s .debug_frame,42       /* Any sections named .debug_frame and
                            also section #42 */ 

Syntax

‑‑segment seg_number[,...]
‑g seg_number[,...]

Parameters

For use with

ielfdumpriscv

Description

Use this option to select specific segments—parts of an executable image indicated by program headers—for inclusion in the output. If a specified segment cannot be found, it is excluded from the output but all other segments are included.

You can specify multiple segment numbers by separating them with commas, or by using this option more than once.

Syntax

‑‑self_reloc

For use with

ielftool

Description

This option is intentionally not documented because it is not intended for general use.

Syntax

‑‑show_entry_as name

Parameters

For use with

isymexport

Description

Use this option to export the entry point of the application given as input under the name name.

Syntax

‑‑silent

For use with

iarchive and ielftool

Description

Causes the tool to operate without sending any messages to the standard output stream.

By default, the tool sends various messages via the standard output stream. You can use this option to prevent this. The tool sends error and warning messages to the error output stream, so they are displayed regardless of this setting.

Syntax

‑‑simple

For use with

ielftool

Description

Sets the format of the output file to Simple-code, a binary format that includes address information.

Syntax

‑‑simple-ne

For use with

ielftool

Description

Sets the format of the output file to Simple code, but no entry record is generated.

Syntax

‑‑source

For use with

ielfdumpriscv

Description

Use this option to make ielftool include source for each statement before the code for that statement, when dumping code from an executable file. To make this work, the executable image must be built with debug information, and the source code must still be accessible in its original location.

Syntax

‑‑srec

For use with

ielftool

Description

Sets the format of the output file to Motorola S-records, a hexadecimal text format defined by Motorola. Note that you can use the ielftool options ‑‑srec-len and ‑‑srec-s3only to modify the exact format used.

Syntax

‑‑srec-len=length

Parameters

For use with

ielftool

Description

Sets the maximum number of data bytes in an S-record. This option can only be used together with the ‑‑srec option. By default, the number of data bytes in an S-record is 16.

Syntax

‑‑srec-s3only

For use with

ielftool

Description

Restricts the S-record output to contain only a subset of records, that is S0, S3 and S7 records. This option can be used in combination with the ‑‑srec option.

Syntax

‑‑strip

For use with

iobjmanip and ielftool.

Description

Use this option to remove all sections containing debug information before the output file is written. iobjmanip will also remove the names of all module-local function, variable, and section symbols.

Syntax

‑‑symbols libraryfile

Parameters

See also Rules for specifying a filename or directory as parameters.

For use with

iarchive

Description

Use this command to list all external symbols that are defined by any object file (module) in the specified library, together with the name of the object file (module) that defines it.

In silent mode (‑‑silent), this command performs symbol table-related syntax checks on the library file and displays only errors and warnings.

Syntax

‑‑text_out{utf8|utf16le|utf16be|locale}

Parameters

For use with

iarchive, ielfdumpriscv, iobjmanip, and isymexport

Description

Use this option to specify the encoding to be used when generating a text output file.

The default for the list files is to use the same encoding as the main source file. The default for all other text files is UTF-8 with a Byte Order Mark (BOM).

If you want text output in UTF-8 encoding without BOM, you can use the option ‑‑no_bom as well.

See also

‑‑no_bom and Text encodings

Syntax

‑‑titxt

For use with

ielftool

Description

Sets the format of the output file to Texas Instruments TI–TXT, a hexadecimal text format defined by Texas Instruments.

Syntax

‑‑toc libraryfile
-t libraryfile

Parameters

See also Rules for specifying a filename or directory as parameters.

For use with

iarchive

Description

Use this command to list the names of all object files (modules) in a specified library.

In silent mode (‑‑silent), this command performs basic syntax checks on the library file, and displays only errors and warnings.

Syntax

‑‑utf8_text_in

For use with

iarchive, ielfdumpriscv, iobjmanip, and isymexport

Description

Use this option to specify that the tool shall use the UTF-8 encoding when reading a text input file with no Byte Order Mark (BOM).

See also

Text encodings

Syntax

‑‑update_symbol symbol,{hexstring|(filename)}[,force]

Parameters

For use with

ielftool

Description

This option replaces the ELF file content for the specified symbol. ielftool checks that the number of new content bytes (specified by a hexadecimal string, or read from a file) matches the current size of the symbol in the ELF file. If the sizes do not match, the operation is aborted.

Use the force parameter to make ielftool perform the operation even if the sizes do not match—some ELF symbols do not have sizes (typically assembler-generated, or generated by a toolchain that does not set symbol sizes in general). If you force the operation, you must be careful so you do not accidentally use the file you are updating as input, because that will corrupt it.

Syntax

‑‑update_typeless_globals[=codeSectionName,dataSectionName]

Parameters

For use with

iobjmanip

Description

Use this option to update the type of relevant global symbols in an object file.

A global symbol that does not have an ELF type (ELF attribute STT_NOTYPE) will have its type set to Code (STT_FUNC) or Data (STT_OBJECT). When no parameters are specified, the attributes of the section that contains the symbol are used to determine if this is a Code or a Data symbol.

If the optional section names are used, then the symbols in sections that match the dataSectionName will be treated as Data. Similarly, the symbols in sections that match the codeSectionName will be treated as Code. If a section does not match either the dataSectionName or the codeSectionName, then a warning will be generated and any symbols in that section will not be updated.

Syntax

‑‑verbose
-V (iarchive only)

For use with

iarchive and ielftool.

Description

Use this option to make the tool report which operations it performs, in addition to giving diagnostic messages.

Syntax

‑‑version

For use with

iarchive, ielfdumpriscv, ielftool, iobjmanip, isymexport

Description

Use this option to make the tool send version information to the console and then exit.

Syntax

‑‑vtoc libraryfile

Parameters

See also Rules for specifying a filename or directory as parameters.

For use with

iarchive

Description

Use this command to list the names, sizes, and modification times of all object files (modules) in a specified library.

In silent mode (‑‑silent), this command performs basic syntax checks on the library file, and displays only errors and warnings.