14.2. tiarmobjcopy - Object Copying and Editing Tool¶
The tiarmobjcopy tool can be used to copy and manipulate object files. In basic usage, it makes a semantic copy of the input to the output. If any options are specified, the output may be modified along the way (e.g. by removing sections).
14.2.1. Usage¶
tiarmobjcopy [options] input file [output file]
tiarmobjcopy - is the command that invokes the object copying and editing tool.
options - affect the behavior of tiarmobjcopy.
input file - identifies an object file or archive of object files. If - is specified as the input file argument, then tiarmobjcopy will take its input from stdin. If the input file is an archive, then any requested operations will be applied to each archive member individually.
output file - specifies where the tiarmobjcopy output will be written. This is typically a file name, where the named file will be created or overwritten with the tiarmobjcopy output. If no output file argument is specified, then the input file will be modified in-place. If - is specified for the output file argument, then the tiarmobjcopy output is written to stdout.
14.2.2. Options¶
The following tiarmobjcopy options are either agnostic of the object file format, or apply to multiple file formats:
- --add-section <section>=<file>¶
Add a section named <section> with the contents of <file> to the output. If the specified <section> name starts with “.note”, then the type of the <section> (indicated in the ELF section header) will be SHT_NOTE. Otherwise, the <section> type will be <SHT_PROGBITS.
The --add_section option can be specified multiple times on the tiarmobjcopy command line to add multiple sections.
- --discard-all, -x¶
Remove most local symbols from the output. File and section symbols will not be discarded from ELF object files.
- --dump-section <section>=<file>¶
Dump the contents of the specified <section> into the specified <file>. This option can be specified multiple times to dump multiple sections to different files. The indicated <file> argument is unrelated to the input and output files provided to tiarmobjcopy and as such the normal copying and editing operations will still be performed. No operations are performed on the specified sections prior to dumping them.
- --help, -h¶
Print a summary of command line options.
- --only-keep-debug¶
Produce a debug file as the output that only preserves contents of sections useful for debugging purposes.
For ELF object files, this removes the contents of SHF_ALLOC sections that are not SHT_NOTE type by making them SHT_NOBITS type and shrinking the program headers where possible.
- --only-section <section>, -j <section>¶
Remove all sections from the output, except for specified <sections>. This option can be specified multiple times to keep multiple sections.
- --redefine-sym <old symbol>=<new symbol>¶
Rename symbols called <old symbol> to <new symbol> in the output. This option can be specified multiple times to rename multiple symbols.
- --redefine-syms <file>¶
Rename symbols in the output as described in the specified <file>. Each line in the <file> represents a single symbol to rename, with the old symbol name and new symbol name separated by whitespace. Leading and trailing whitespace is ignored, as is anything following a #. This option can be specified multiple times to read names from multiple files.
- --remove-section <section>, -R <section>¶
Remove the specified <section> from the output. Can be specified multiple times to remove multiple sections simultaneously.
- --set-section-alignment <section>=<align>¶
Set the alignment of specified <section> to <align>. This option can be specified multiple times to update multiple sections.
- --set-section-flags <section>=<flag>[,<flag>,...]¶
Set section properties in the output of a <section> based on the specified <flag> values. This option can be specified multiple times to update multiple sections.
Supported <flag> names include:
alloc - Add the SHF_ALLOC flag.
load - If the section has SHT_NOBITS type, mark it as a SHT_PROGBITS section.
readonly - If this flag is not specified, add the SHF_WRITE flag.
exclude - Add the SHF_EXCLUDE flag.
code - Add the SHF_EXECINSTR flag.
merge - Add the SHF_MERGE flag.
strings - Add the SHF_STRINGS flag.
contents - If the section has SHT_NOBITS type, mark it as a SHT_PROGBITS section.
- --strip-all, -S¶
Remove from the output all symbols and non-alloc sections not within segments, except for .ARM.attribute section and the section name table.
- --strip-debug, -g¶
Remove all debug sections from the output.
- --strip-symbol <symbol>, -N <symbol>¶
Remove specified <symbol> from the output. This option can be specified multiple times to remove multiple symbols.
- --strip-symbols <file>¶
Remove all symbols whose names appear in the specified <file> from the output. Each line in the <file> represents a single symbol name, with leading and trailing whitespace ignored, as is anything following a #. This option can be specified multiple times to read names from multiple files.
- --strip-unneeded-symbol <symbol>¶
Remove from the output all symbols named <symbol> that are local or undefined and are not required by any relocation.
- --strip-unneeded-symbols <file>¶
Remove all symbols whose names appear in the specified <file> from the output, if they are local or undefined and are not required by any relocation. Each line in the <file> represents a single symbol name, with leading and trailing whitespace ignored, as is anything following a #. This option can be specified multiple times to read names from multiple files.
- --strip-unneeded¶
Remove from the output all local or undefined symbols that are not required by relocations. Also remove all debug sections.
- --version, -V¶
Display the version of the tiarmobjcopy executable.
- --wildcard, -w¶
Allow wildcards (like “*” and “?”) for symbol-related option arguments. Wildcards are available for section-related option arguments by default.
- @<file>¶
Read command-line options and commands from specified <file>.
- --add-symbol <name>=[<section>:]<value>[,<flags>]¶
Add a new symbol called <name> to the output symbol table in the specified <section>, defined with the given <value>. If <section> is not specified, the symbol is added as an absolute symbol. The <flags> affect the symbol properties.
Accepted values for <flags> include:
global - The symbol will have global binding.
local - The symbol will have local binding.
weak - The symbol will have weak binding.
default - The symbol will have default visibility.
hidden - The symbol will have hidden visibility.
protected - The symbol will have protected visibility.
file - The symbol will be an STT_FILE symbol.
section - The symbol will be an STT_SECTION symbol.
object - The symbol will be an STT_OBJECT symbol.
function - The symbol will be an STT_FUNC symbol.
This option can be specified multiple times to add multiple symbols.
- --allow-broken-links¶
Allow tiarmobjcopy to remove sections even if it would leave invalid section references. Any invalid sh_link fields in the section header table will be set to zero.
- --change-start <incr>, --adjust-start <incr>¶
Add <incr> to the program’s start address. This option can be specified multiple times, in which case the <incr> values will be applied cumulatively.
- --compress-debug-sections [<style>]¶
Compress DWARF debug sections in the output, using the specified <style>. Supported styles are zlib-gnu and zlib. If <style> is not specified, zlib is assumed by default.
- --decompress-debug-sections¶
Decompress any compressed DWARF debug sections in the output.
- --discard-locals, -X¶
Remove local symbols starting with “.L” from the output.
- --extract-dwo¶
Remove all sections that are not DWARF .dwo sections from the output.
- --extract-main-partition¶
Extract the main partition from the output.
- --extract-partition <name>¶
Extract the <name> partition from the output.
- --globalize-symbol <symbol>¶
Mark any defined symbols named <symbol> as global symbols in the output. This option can be specified multiple times to mark multiple symbols.
- --globalize-symbols <file>¶
Read a list of names from the specified <file> and mark defined symbols with those names as global in the output. Each line in the <file> represents a single symbol, with leading and trailing whitespace ignored, as is anything following a #. This option can be specified multiple times to read names from multiple files.
- --input-target <format>, -I¶
Read the input as the specified <format>. See the Supported Target Formats section below for a list of valid <format> values. If unspecified, tiarmobjcopy will attempt to determine the format automatically.
- --keep-file-symbols¶
Keep symbols of type STT_FILE, even if they would otherwise be stripped.
- --keep-global-symbol <symbol>¶
Make all symbols local in the output, except for symbols with the name <symbol>. This option can be specified multiple times to ignore multiple symbols.
- --keep-global-symbols <file>¶
Make all symbols local in the output, except for symbols named in the specified <file>. Each line in the <file> represents a single symbol, with leading and trailing whitespace ignored, as is anything following a #. This option can be specified multiple times to read names from multiple files.
- --keep-section <section>¶
When removing sections from the output, do not remove sections named <section>. This option can be specified multiple times to keep multiple sections.
- --keep-symbol <symbol>, -K <symbol>¶
When removing symbols from the output, do not remove symbols named <symbol>. This option can be specified multiple times to keep multiple symbols.
- --keep-symbols <file>¶
When removing symbols from the output do not remove symbols named in the specified <file>. Each line in the <file> represents a single symbol, with leading and trailing whitespace ignored, as is anything following a #. This option can be specified multiple times to read names from multiple files.
Make all symbols with hidden or internal visibility local in the output.
- --localize-symbol <symbol>, -L <symbol>¶
Mark any defined non-common symbol named <symbol> as a local symbol in the output. This option can be specified multiple times to mark multiple symbols as local.
- --localize-symbols <file>¶
Read a list of names from the specified <file> and mark defined non-common symbols with those names as local in the output. Each line in the <file> represents a single symbol, with leading and trailing whitespace ignored, as is anything following a #. This option can be specified multiple times to read names from multiple files.
- --new-symbol-visibility <visibility_kind>¶
Specify the <visibility_kind> of the symbols automatically created when using binary input or the --add-symbol option. Valid <visibility_kind> argument values are:
default
hidden
protected
An automatically created symbol will get default visibility unless otherwise specified with the --new-symbol-visibility option.
- --output-target <format>, -O <format>¶
Write the output as the specified <format>. See the Supported Target Formats section below for a list of valid <format> values. If a <format> argument is not specified, the output format is assumed to be the same as the value specified for --input-target or the input file’s format if that option is also unspecified.
- --prefix-alloc-sections <prefix>¶
Add <prefix> to the front of the names of all allocatable sections in the output.
- --prefix-symbols <prefix>¶
Add <prefix> to the front of every symbol name in the output.
- --preserve-dates, -p¶
Preserve access and modification timestamps in the output.
- --rename-section <old section>=<new section>[,<flag>,...]¶
Rename sections called <old section> to <new section> in the output, and apply any specified <flag> values. See the --set-section-flags option description for a list of supported <flag> values. This option can be specified multiple times to rename multiple sections.
- --set-start-addr <addr>¶
Set the start address of the output to <addr>. This option overrides any previously specified --change-start or --adjust-start options.
- --split-dwo <dwo-file>¶
Equivalent to running tiarmobjcopy with the --extract-dwo option and <dwo-file> as the output file and no other options, and then with the --strip-dwo option on the input file.
- --strip-dwo¶
Remove all DWARF .dwo sections from the output.
- --strip-non-alloc¶
Remove from the output all non-allocatable sections that are not within segments.
- --strip-sections¶
Remove from the output all section headers and all section data not within segments. Note that many tools will not be able to use an object without section headers.
- --target <format>, -F <format>¶
Equivalent to using the --input-target and --output-target for the specified <format>. See the Supported Target Formats for a list of valid <format> values.
- --weaken-symbol <symbol>, -W <symbol>¶
Mark any global symbol named <symbol> as a weak symbol in the output. This option can be specified multiple times to mark multiple symbols as weak.
- --weaken-symbols <file>¶
Read a list of names from the specified <file> and mark global symbols with those names as weak in the output. Each line in the <file> represents a single symbol, with leading and trailing whitespace ignored, as is anything following a #. This option can be specified multiple times to read names from multiple files.
- --weaken¶
Mark all defined global symbols as weak in the output.
14.2.2.1. Supported Target Formats¶
The following values are supported by tiarmobjcopy for the <format> argument to the --input-target, --output-target, and --target options.
binary
elf32-littlearm
elf32-littlearm-freebsd
ihex
ti-txt
Note
There is currently a known issue with --input-target and --target causing only binary and ihex <format> values to have any effect. Other <format> values will be ignored and tiarmobjcopy will attempt to guess the input format.
Note
The ti-txt format is the same as the TI-TXT format supported by the TI hex conversion utility. See TI-TXT Hex Format (--ti_txt Option) for more details.
14.2.2.2. Binary Input and Output¶
If binary is used as the <format> value for the --input-target option, the input file will be embedded as a data section in an ELF relocatable object, with symbols _binary_<file_name>_start, _binary_<file_name>_end, and _binary_<file_name>_size representing the start, end and size of the data, where <file_name> is the path of the input file as specified on the command line with non-alphanumeric characters converted to _.
If binary is used as the <format> value for --the output-target, the output file will be a raw binary file, containing the memory image of the input file. Symbols and relocation information will be discarded. The image will start at the address of the first loadable section in the output.
14.2.3. Exit Status¶
tiarmobjcopy exits with a non-zero exit code if there is an error. Otherwise, it exits with code 0.