12.1. c29objcopy - Object Copying and Editing Tool

The c29objcopy 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).

12.1.1. Usage

c29objcopy [options] input file [output file]

  • c29objcopy - is the command that invokes the object copying and editing tool.

  • options - affect the behavior of c29objcopy.

  • input file - identifies an object file or archive of object files. If - is specified as the input file argument, then c29objcopy takes its input from stdin. If the input file is an archive, then any requested operations are applied to each archive member individually.

  • output file - specifies where the c29objcopy output is written. This is typically a file name, where the named file is created or overwritten with the c29objcopy output. If no output file argument is specified, then the input file is modified in-place. If - is specified for the output file argument, then the c29objcopy output is written to stdout.

12.1.2. Options

The following c29objcopy 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) is SHT_NOTE. Otherwise, the <section> type is <SHT_PROGBITS.

The --add_section option can be specified multiple times on the c29objcopy command line to add multiple sections.

--discard-all, -x

Remove most local symbols from the output. File and section symbols are not 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 c29objcopy and as such the normal copying and editing operations are still 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 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 c29objcopy 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 c29objcopy to remove sections even if it would leave invalid section references. Any invalid sh_link fields in the section header table are 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 are 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, c29objcopy attempts 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.

--localize-hidden

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 gets 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 c29objcopy 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 are not 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.

12.1.2.1. Supported Target Formats

The following values are supported by c29objcopy for the <format> argument to the --input-target, --output-target, and --target options.

  • binary

  • elf32-c29

  • 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 are ignored and c29objcopy attempts to guess the input format.

12.1.2.2. Binary Input and Output

If binary is used as the <format> value for the --input-target option, the input file is 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 is a raw binary file, containing the memory image of the input file. Symbols and relocation information are discarded. The image starts at the address of the first loadable section in the output.

12.1.2.3. ihex Object Format

The ihex (Intel HEX) object format supports 16-bit addresses and 32-bit extended addresses. Intel format consists of a 9-character (4-field) prefix (which defines the start of record, byte count, load address, and record type), the data, and a 2-character checksum suffix.

The 9-character prefix represents three record types:

Record Type

Description

00

Data record

01

End-of-file record

04

Extended linear address record

Record type 00, the data record, begins with a colon ( : ) and is followed by the byte count, the address of the first data byte, the record type (00), and the checksum. The address is the least significant 16 bits of a 32-bit address; this value is concatenated with the value from the most recent 04 (extended linear address) record to create a full 32-bit address. The checksum is the 2s complement (in binary form) of the preceding bytes in the record, including byte count, address, and data bytes.

Record type 01, the end-of-file record, also begins with a colon ( : ), followed by the byte count, the address, the record type (01), and the checksum.

Record type 04, the extended linear address record, specifies the upper 16 address bits. It begins with a colon ( : ), followed by the byte count, a dummy address of 0h, the record type (04), the most significant 16 bits of the address, and the checksum. The subsequent address fields in the data records contain the least significant bytes of the address.

The following figure illustrates the Intel hexadecimal object format.

Figure: Intel Hexadecimal Object Format

../../_images/intel_hex_tdz079.png

12.1.2.4. ti-txt Format

The ti-txt format supports 8-bit hexadecimal data. It consists of section start addresses, data byte, and an end-of-file character. The following restrictions apply:

  • The number of sections is unlimited.

  • Each hexadecimal start address must be even.

  • Each line must have 8 data bytes, except the last line of a section.

  • Data bytes are separated by a single space.

  • The end-of-file termination tag q is mandatory.

The data record contains the following information:

Item

Description

@ADDR

Hexadecimal start address of a section

DATAn

Hexadecimal data byte

q

End-of-file termination character

Figure: TI-TXT Object Format

../../_images/ti_txt_tdz079.png

Example: TI-TXT Object Format

@F000
31 40 00 03 B2 40 80 5A 20 01 D2 D3 22 00 D2 E3
21 00 3F 40 E8 FD 1F 83 FE 23 F9 3F
@FFFE
00 F0
Q

12.1.3. Exit Status

The c29objcopy utility exits with a non-zero exit code if there is an error. Otherwise, it exits with code 0.