1# This template file can be used as a starting point for implementing support
2# for additional tools for reading and/or conversion of elf files.
3#
4# Although GNU bintools is used as name, then the template can be used to
5# support other tools.
6#
7# Overview of bintools used commands:
8# - memusage    : Tool for reporting target memory usage
9#                 (if linker support memusage reporting leave this property empty)
10# - disassembly : Tool for disassemble the target
11# - elfconvert  : Tool for converting from elf into another format.
12# - readelf     : Tool for elf file processing
13# - strip       : Tool for symbol stripping
14# - symbols     : Tool for listing symbols in a binary
15#
16# Each tool will have the following minimum properties:
17# - <tool>_command : Name of executable to call
18# - <tool>_flag    : Flags that must always be used with this command
19# - <tool>_flag_infile  : Flag to use when specifying the file to process
20# - <tool>_flag_outfile : Flag to use to specify the result of the processing.
21#
22# each tool might require more flags depending on its use, as example:
23# - elfconvert_flag_section_remove : Flag to use when specifying sections to remove
24# - readelf_flags_headers : Flag to use to specify headers should be displayed
25#
26# If a given tool / flag / feature is not supported, then keep the property empty.
27# As bintools_template.cmake default has empty flags, then it is sufficient to
28# only set those flags that a given set of tools support.
29#
30# Commands will default echo a message if called, but no command has been defined.
31# This is done, so that unexpected calls to non-implemented command can be easily detected.
32# To disable the message, simply silence the command with:
33#     set_property(TARGET bintools PROPERTY <command>_command ${CMAKE_COMMAND} -E echo "")
34#
35# The bintools properties are made generic so that implementing support for an
36# additional native tool should be as easy as possible.
37# However, there might be tools and/or use cases where the current property
38# scheme does not cover the exact needs. For those use-cases it is possible
39# to implement the call to a native tool inside a CMake script.
40# For example, to call a custom script for elfconvert command, one can specify:
41#   set_property(TARGET bintools PROPERTY elfconvert_command ${CMAKE_COMMAND})
42#   set_property(TARGET bintools PROPERTY elfconvert_flag "")
43#   set_property(TARGET bintools PROPERTY elfconvert_flag_final     -P custom_elfconvert.cmake)
44#   set_property(TARGET bintools PROPERTY elfconvert_flag_strip_all "-DSTRIP_ALL=True")
45#   set_property(TARGET bintools PROPERTY elfconvert_flag_infile    "-DINFILE=")
46#   set_property(TARGET bintools PROPERTY elfconvert_flag_outfile   "-DOUT_FILE=")
47
48#
49#
50# bintools property overview of all commands:
51#
52# Command:
53# - memusage            : Name of command to execute
54#                         Note: For gcc compilers this command is not used,
55#                               instead a linker flag is used for this)
56#   memusage_flag       : Flags that must always be applied when calling memusage command
57#   memusage_flag_final : Flags that must always be applied last at the memusage command
58#   memusage_flag_infile: Flag for specifying the input file
59#   memusage_byproducts : Byproducts (files) generated when calling memusage
60#
61#
62# - elfconvert  : Name of command for elf file conversion.
63#                 For GNU binary utilities this is objcopy
64#   elfconvert_formats            : Formats supported by this command.
65#   elfconvert_flag               : Flags that must always be applied when calling elfconvert command
66#   elfconvert_flag_final         : Flags that must always be applied last at the elfconvert command
67#   elfconvert_flag_strip_all     : Flag that is used for stripping all symbols when converting
68#   elfconvert_flag_strip_debug   : Flag that is used to strip debug symbols when converting
69#   elfconvert_flag_compress_debug_sections: Flag that is used to compress debug sections when converting
70#   elfconvert_flag_intarget      : Flag for specifying target used for infile
71#   elfconvert_flag_outtarget     : Flag for specifying target to use for converted file.
72#                                   Target value must be one of those listed described by: elfconvert_formats
73#   elfconvert_flag_section_remove: Flag for specifying that following section must be removed
74#   elfconvert_flag_section_only  : Flag for specifying that only the following section should be kept
75#   elfconvert_flag_section_rename: Flag for specifying that following section must be renamed
76#   elfconvert_flag_gapfill       : Flag for specifying the value to fill in gaps between sections
77#   elfconvert_flag_srec_len      : Flag for specifying maximum length of Srecord values
78#   elfconvert_flag_infile        : Flag for specifying the input file
79#   elfconvert_flag_outfile       : Flag for specifying the output file
80#                                   For tools that prints to standard out, this should be ">" to indicate redirection
81#
82#
83# - disassembly : Name of command for disassembly of files
84#                 For GNU binary utilities this is objdump
85#   disassembly_flag               : Flags that must always be applied when calling disassembly command
86#   disassembly_flag_final         : Flags that must always be applied last at the disassembly command
87#   disassembly_flag_inline_source : Flag to use to display source code mixed with disassembly
88#   disassembly_flag_all           : Flag to use for disassemble everything, including zeroes
89#   disassembly_flag_infile        : Flag for specifying the input file
90#   disassembly_flag_outfile       : Flag for specifying the output file
91#                                    For tools that prints to standard out, this should be ">" to indicate redirection
92#
93#
94# - readelf : Name of command for reading elf files.
95#             For GNU binary utilities this is readelf
96#   readelf_flag          : Flags that must always be applied when calling readelf command
97#   readelf_flag_final    : Flags that must always be applied last at the readelf command
98#   readelf_flag_headers  : Flag to use for specifying ELF headers should be read
99#   readelf_flag_infile   : Flag for specifying the input file
100#   readelf_flag_outfile  : Flag for specifying the output file
101#                           For tools that prints to standard out, this should be ">" to indicate redirection
102#
103#
104# - strip: Name of command for stripping symbols
105#          For GNU binary utilities this is strip
106#   strip_flag         : Flags that must always be applied when calling strip command
107#   strip_flag_final   : Flags that must always be applied last at the strip command
108#   strip_flag_all     : Flag for removing all symbols
109#   strip_flag_debug   : Flag for removing debug symbols
110#   strip_flag_dwo     : Flag for removing dwarf sections
111#   strip_flag_infile  : Flag for specifying the input file
112#   strip_flag_outfile : Flag for specifying the output file
113#
114# - symbols : Name of command for printing out symbols
115#             For GNU binary utilities this is nm
116#   symbols_command         : empty
117#   symbols_final   : empty
118#   symbols_infile  : ELF file name
119#   symbols_outfile : output file
120
121set(COMMAND_NOT_SUPPORTED "command not supported on bintools: ")
122
123# If memusage is supported as post-build command, set memusage_type to: command
124# and this value to the command to execute in the form: <command> <arguments>
125# Note: If memusage is supported during linking, please use:
126#       set_property(TARGET linker ... ) found in cmake/linker/linker_flags.cmake instead
127set_property(TARGET bintools PROPERTY memusage_command "")
128set_property(TARGET bintools PROPERTY memusage_flag "")
129set_property(TARGET bintools PROPERTY memusage_flag_final "")
130set_property(TARGET bintools PROPERTY memusage_byproducts "")
131
132# disassembly command to use for generation of list file.
133set_property(TARGET bintools PROPERTY disassembly_command ${CMAKE_COMMAND} -E echo "disassembly ${COMMAND_NOT_SUPPORTED} ${BINTOOLS}")
134set_property(TARGET bintools PROPERTY disassembly_flag "")
135set_property(TARGET bintools PROPERTY disassembly_flag_final "")
136set_property(TARGET bintools PROPERTY disassembly_flag_inline_source "")
137set_property(TARGET bintools PROPERTY disassembly_flag_infile "")
138set_property(TARGET bintools PROPERTY disassembly_flag_outfile "")
139
140# elfconvert to use for transforming an elf file into another format, such as intel hex, s-rec, binary, etc.
141set_property(TARGET bintools PROPERTY elfconvert_command ${CMAKE_COMMAND} -E echo "elfconvert ${COMMAND_NOT_SUPPORTED} ${BINTOOLS}")
142set_property(TARGET bintools PROPERTY elfconvert_formats "")
143set_property(TARGET bintools PROPERTY elfconvert_flag "")
144set_property(TARGET bintools PROPERTY elfconvert_flag_final "")
145set_property(TARGET bintools PROPERTY elfconvert_flag_compress_debug_sections "")
146set_property(TARGET bintools PROPERTY elfconvert_flag_outtarget "")
147set_property(TARGET bintools PROPERTY elfconvert_flag_section_remove "")
148set_property(TARGET bintools PROPERTY elfconvert_flag_gapfill "")
149set_property(TARGET bintools PROPERTY elfconvert_flag_infile "")
150set_property(TARGET bintools PROPERTY elfconvert_flag_outfile "")
151
152# readelf for processing of elf files.
153set_property(TARGET bintools PROPERTY readelf_command ${CMAKE_COMMAND} -E echo "readelf ${COMMAND_NOT_SUPPORTED} ${BINTOOLS}")
154set_property(TARGET bintools PROPERTY readelf_flag "")
155set_property(TARGET bintools PROPERTY readelf_flag_final "")
156set_property(TARGET bintools PROPERTY readelf_flag_headers "")
157set_property(TARGET bintools PROPERTY readelf_flag_infile "")
158set_property(TARGET bintools PROPERTY readelf_flag_outfile "")
159
160# strip command for stripping symbols
161set_property(TARGET bintools PROPERTY strip_command ${CMAKE_COMMAND} -E echo "strip ${COMMAND_NOT_SUPPORTED} ${BINTOOLS}")
162set_property(TARGET bintools PROPERTY strip_flag "")
163set_property(TARGET bintools PROPERTY strip_flag_final "")
164set_property(TARGET bintools PROPERTY strip_flag_all "")
165set_property(TARGET bintools PROPERTY strip_flag_debug "")
166set_property(TARGET bintools PROPERTY strip_flag_dwo "")
167set_property(TARGET bintools PROPERTY strip_flag_infile "")
168set_property(TARGET bintools PROPERTY strip_flag_outfile "")
169
170# list symbols in a binary
171set_property(TARGET bintools PROPERTY symbols_command ${CMAKE_NM})
172set_property(TARGET bintools PROPERTY symbols_flag "")
173set_property(TARGET bintools PROPERTY symbols_final "")
174set_property(TARGET bintools PROPERTY symbols_infile "")
175set_property(TARGET bintools PROPERTY symbols_outfile ">;" )
176