1#
2# Copyright (c) 2023-2024, Arm Limited and Contributors. All rights reserved.
3#
4# SPDX-License-Identifier: BSD-3-Clause
5#
6
7#
8# TF-A uses three toolchains:
9#
10#   - The host toolchain (`host`) for building native tools
11#   - The AArch32 toolchain (`aarch32`) for building Arm AArch32 images
12#   - The AArch64 toolchain (`aarch64`) for building Arm AArch64 images
13#
14# In the main Makefile only one of the two Arm toolchains is enabled in any
15# given build, but individual tools and libraries may need access to both.
16#
17
18ifndef toolchain-mk
19        toolchain-mk := $(lastword $(MAKEFILE_LIST))
20
21        toolchains ?= host $(ARCH)
22
23        include $(dir $(lastword $(MAKEFILE_LIST)))build_env.mk
24        include $(dir $(lastword $(MAKEFILE_LIST)))utilities.mk
25
26        include $(addprefix $(dir $(lastword $(MAKEFILE_LIST)))toolchains/, \
27                $(addsuffix .mk,$(toolchains)))
28
29        #
30        # Configure tool classes that we recognize.
31        #
32        # In the context of this build system, a tool class identifies a
33        # specific role or type of tool in the toolchain.
34        #
35
36        tool-classes := cc
37        tool-class-name-cc := C compiler
38
39        tool-classes += cpp
40        tool-class-name-cpp := C preprocessor
41
42        tool-classes += as
43        tool-class-name-as := assembler
44
45        tool-classes += ld
46        tool-class-name-ld := linker
47
48        tool-classes += oc
49        tool-class-name-oc := object copier
50
51        tool-classes += od
52        tool-class-name-od := object dumper
53
54        tool-classes += ar
55        tool-class-name-ar := archiver
56
57        tool-classes += dtc
58        tool-class-name-dtc := device tree compiler
59
60        #
61        # Configure tools that we recognize.
62        #
63        # Here we declare the list of specific toolchain tools that we know how
64        # to interact with. We don't organize these into tool classes yet - that
65        # happens further down.
66        #
67
68        # Arm® Compiler for Embedded
69        tools := arm-clang
70        tool-name-arm-clang := Arm® Compiler for Embedded `armclang`
71
72        tools += arm-link
73        tool-name-arm-link := Arm® Compiler for Embedded `armlink`
74
75        tools += arm-ar
76        tool-name-arm-ar := Arm® Compiler for Embedded `armar`
77
78        tools += arm-fromelf
79        tool-name-arm-fromelf := Arm® Compiler for Embedded `fromelf`
80
81        # LLVM Project
82        tools += llvm-clang
83        tool-name-llvm-clang := LLVM Clang (`clang`)
84
85        tools += llvm-lld
86        tool-name-llvm-lld := LLVM LLD (`lld`)
87
88        tools += llvm-objcopy
89        tool-name-llvm-objcopy := LLVM `llvm-objcopy`
90
91        tools += llvm-objdump
92        tool-name-llvm-objdump := LLVM `llvm-objdump`
93
94        tools += llvm-ar
95        tool-name-llvm-ar := LLVM `llvm-ar`
96
97        # GNU Compiler Collection & GNU Binary Utilities
98        tools += gnu-gcc
99        tool-name-gnu-gcc := GNU GCC (`gcc`)
100
101        tools += gnu-ld
102        tool-name-gnu-ld := GNU LD (`ld.bfd`)
103
104        tools += gnu-objcopy
105        tool-name-gnu-objcopy := GNU `objcopy`
106
107        tools += gnu-objdump
108        tool-name-gnu-objdump := GNU `objdump`
109
110        tools += gnu-ar
111        tool-name-gnu-ar := GNU `ar`
112
113        # Other tools
114        tools += generic-dtc
115        tool-name-generic-dtc := Device Tree Compiler (`dtc`)
116
117        #
118        # Assign tools to tool classes.
119        #
120        # Multifunctional tools, i.e. tools which can perform multiple roles in
121        # a toolchain, may be specified in multiple tool class lists. For
122        # example, a C compiler which can also perform the role of a linker may
123        # be placed in both `tools-cc` and `tools-ld`.
124        #
125
126        # C-related tools
127        tools-cc := arm-clang llvm-clang gnu-gcc # C compilers
128        tools-cpp := arm-clang llvm-clang gnu-gcc # C preprocessors
129
130        # Assembly-related tools
131        tools-as := arm-clang llvm-clang gnu-gcc # Assemblers
132
133        # Linking and object-handling tools
134        tools-ld := arm-clang arm-link llvm-clang llvm-lld gnu-gcc gnu-ld # Linkers
135        tools-oc := arm-fromelf llvm-objcopy gnu-objcopy # Object copiers
136        tools-od := arm-fromelf llvm-objdump gnu-objdump # Object dumpers
137        tools-ar := arm-ar llvm-ar gnu-ar # Archivers
138
139        # Other tools
140        tools-dtc := generic-dtc # Device tree compilers
141
142        define check-tool-class-tools
143                $(eval tool-class := $(1))
144
145                ifndef tools-$(tool-class)
146                        $$(error no tools registered to handle tool class `$(tool-class)`)
147                endif
148        endef
149
150        $(foreach tool-class,$(tool-classes), \
151                $(eval $(call check-tool-class-tools,$(tool-class))))
152
153        #
154        # Default tools for each toolchain.
155        #
156        # Toolchains can specify a default path to any given tool with a tool
157        # class. These values are used in the absence of user-specified values,
158        # and are configured by the makefile for each toolchain using variables
159        # of the form:
160        #
161        #   - $(toolchain)-$(tool-class)-default
162        #
163        # For example, the default C compiler for the AArch32 and AArch64
164        # toolchains could be configured with:
165        #
166        #   - aarch32-cc-default
167        #   - aarch64-cc-default
168        #
169
170        define check-toolchain-tool-class-default
171                $(eval toolchain := $(1))
172                $(eval tool-class := $(2))
173
174                ifndef $(toolchain)-$(tool-class)-default
175                        $$(error no default value specified for tool class `$(tool-class)` of toolchain `$(toolchain)`)
176                endif
177        endef
178
179        define check-toolchain-tool-class-defaults
180                $(eval toolchain := $(1))
181
182                $(foreach tool-class,$(tool-classes), \
183                        $(eval $(call check-toolchain-tool-class-default,$(toolchain),$(tool-class))))
184        endef
185
186        $(foreach toolchain,$(toolchains), \
187                $(eval $(call check-toolchain-tool-class-defaults,$(toolchain))))
188
189        #
190        # Helper functions to identify toolchain tools.
191        #
192        # The functions defined in this section return a tool identifier when
193        # given a path to a binary. We generally check a help or version string
194        # to more reliably identify tools than by looking at the path alone
195        # (e.g. `gcc` on macOS is actually Apple Clang).
196        #
197        # Each tool-guessing function (`guess-tool-$(tool)`) takes a single
198        # argument giving the path to the tool to guess, and returns a non-empty
199        # value if the tool corresponds to the tool identifier `$(tool)`:
200        #
201        #     $(call guess-tool-llvm-clang,aarch64-none-elf-gcc) # <empty>
202        #     $(call guess-tool-gnu-gcc,aarch64-none-elf-gcc) # <non-empty>
203        #
204        # The `guess-tool` function tries to find the corresponding tool
205        # identifier for a tool given its path. It takes two arguments:
206        #
207        #   - $(1): a list of candidate tool identifiers to check
208        #   - $(2): the path to the tool to identify
209        #
210        # If any of the guess functions corresponding to candidate tool
211        # identifiers return a non-empty value then the tool identifier of the
212        # first function to do so is returned:
213        #
214        #     $(call guess-tool,gnu-gcc llvm-clang,armclang) # <empty>
215        #     $(call guess-tool,gnu-gcc llvm-clang,clang-14) # llvm-clang
216        #     $(call guess-tool,gnu-gcc llvm-clang,aarch64-none-elf-gcc-12) # gnu-gcc
217        #
218        # Tools are checked in the order that they appear in
219        # `tools-$(tool-class)`, and the first match is returned.
220        #
221
222        # Arm Compiler for Embedded
223        guess-tool-arm-clang = $(shell $(1) --version 2>&1 <$(nul) | grep -o "Tool: armclang")
224        guess-tool-arm-link = $(shell $(1) --help 2>&1 <$(nul) | grep -o "Tool: armlink")
225        guess-tool-arm-fromelf = $(shell $(1) --help 2>&1 <$(nul) | grep -o "Tool: fromelf")
226        guess-tool-arm-ar = $(shell $(1) --version 2>&1 <$(nul) | grep -o "Tool: armar")
227
228        # LLVM Project
229        guess-tool-llvm-clang = $(shell $(1) -v 2>&1 <$(nul) | grep -o "clang version")
230        guess-tool-llvm-lld = $(shell $(1) --help 2>&1 <$(nul) | grep -o "OVERVIEW: lld")
231        guess-tool-llvm-objcopy = $(shell $(1) --help 2>&1 <$(nul) | grep -o "llvm-objcopy tool")
232        guess-tool-llvm-objdump = $(shell $(1) --help 2>&1 <$(nul) | grep -o "llvm object file dumper")
233        guess-tool-llvm-ar = $(shell $(1) --help 2>&1 <$(nul) | grep -o "LLVM Archiver")
234
235        # GNU Compiler Collection & GNU Binary Utilities
236        guess-tool-gnu-gcc = $(shell $(1) -v 2>&1 <$(nul) | grep -o "gcc version")
237        guess-tool-gnu-ld = $(shell $(1) -v 2>&1 <$(nul) | grep -o "GNU ld")
238        guess-tool-gnu-objcopy = $(shell $(1) --version 2>&1 <$(nul) | grep -o "GNU objcopy")
239        guess-tool-gnu-objdump = $(shell $(1) --version 2>&1 <$(nul) | grep -o "GNU objdump")
240        guess-tool-gnu-ar = $(shell $(1) --version 2>&1 <$(nul) | grep -o "GNU ar")
241
242        # Other tools
243        guess-tool-generic-dtc = $(shell $(1) --version 2>&1 <$(nul) | grep -o "Version: DTC")
244
245        guess-tool = $(firstword $(foreach candidate,$(1), \
246                $(if $(call guess-tool-$(candidate),$(2)),$(candidate))))
247
248        #
249        # Locate and identify tools belonging to each toolchain.
250        #
251        # Each tool class in each toolchain receives a variable of the form
252        # `$(toolchain)-$(tool)` giving the associated path to the program. For
253        # example:
254        #
255        #   - `aarch64-ld` gives the linker for the AArch64 toolchain,
256        #   - `aarch32-oc` gives the object copier for the AArch32 toolchain, and
257        #   - `host-cc` gives the C compiler for the host toolchain.
258        #
259        # For each of these variables, if no program path is explicitly provided
260        # by the parent Makefile then the C compiler is queried (if supported)
261        # for its location. This is done via the `guess-$(tool)-$(tool-class)`
262        # set of functions. For example:
263        #
264        #   - `guess-arm-clang-ld` guesses the linker via Arm Clang,
265        #   - `guess-llvm-clang-as` guesses the assembler via LLVM Clang, and
266        #   - `guess-gnu-gcc-od` guesses the object dumper via GNU GCC.
267        #
268        # If the C compiler cannot provide the location (or the tool class is
269        # the C compiler), then it is assigned the value of the
270        # `$(toolchain)-$(tool)-default` variable.
271        #
272
273        guess-arm-clang-cpp = $(1)
274        guess-arm-clang-as = $(1)
275        guess-arm-clang-ld = # Fall back to `$(toolchain)-ld-default`
276        guess-arm-clang-oc = # Fall back to `$(toolchain)-oc-default`
277        guess-arm-clang-od = # Fall back to `$(toolchain)-od-default`
278        guess-arm-clang-ar = # Fall back to `$(toolchain)-ar-default`
279
280        guess-llvm-clang-cpp = $(1)
281        guess-llvm-clang-as = $(1)
282        guess-llvm-clang-ld = $(shell $(1) --print-prog-name ld.lld 2>$(nul))
283        guess-llvm-clang-oc = $(shell $(1) --print-prog-name llvm-objcopy 2>$(nul))
284        guess-llvm-clang-od = $(shell $(1) --print-prog-name llvm-objdump 2>$(nul))
285        guess-llvm-clang-ar = $(shell $(1) --print-prog-name llvm-ar 2>$(nul))
286
287        guess-gnu-gcc-cpp = $(1)
288        guess-gnu-gcc-as = $(1)
289        guess-gnu-gcc-ld = $(1)
290        guess-gnu-gcc-oc = $(shell $(1) --print-prog-name objcopy 2>$(nul))
291        guess-gnu-gcc-od = $(shell $(1) --print-prog-name objdump 2>$(nul))
292        guess-gnu-gcc-ar = $(call which,$(call decompat-path,$(patsubst %$(call file-name,$(1)),%$(subst gcc,gcc-ar,$(call file-name,$(1))),$(call compat-path,$(1)))))
293
294        define toolchain-warn-unrecognized
295                $$(warning )
296                $$(warning The configured $$($(1)-name) $$(tool-class-name-$(2)) could not be identified and may not be supported:)
297                $$(warning )
298                $$(warning $$(space)   $$($(1)-$(2)))
299                $$(warning )
300                $$(warning The default $$($(1)-name) $$(tool-class-name-$(2)) is:)
301                $$(warning )
302                $$(warning $$(space)   $$($(1)-$(2)-default))
303                $$(warning )
304                $$(warning The following tools are supported:)
305                $$(warning )
306
307                $$(foreach tool,$$(tools-$(2)), \
308                        $$(warning $$(space) - $$(tool-name-$$(tool))))
309
310                $$(warning )
311                $$(warning The build system will treat this $$(tool-class-name-$(2)) as $$(tool-name-$$($(1)-$(2)-id-default)).)
312                $$(warning )
313        endef
314
315        define toolchain-determine-tool
316                $(1)-$(2)-guess = $$(if $$(filter-out cc,$(2)),$\
317                        $$(call guess-$$($(1)-cc-id)-$(2),$$($(1)-cc)))
318
319                $(1)-$(2) := $$(or $$($(1)-$(2)),$$($(1)-$(2)-guess))
320                $(1)-$(2) := $$(or $$($(1)-$(2)),$$($(1)-$(2)-default))
321
322                ifneq ($$(call which,$$($(1)-$(2))),)
323                        # If we can resolve this tool to a program on the `PATH`
324                        # then escape it for use in a shell, which allows us to
325                        # preserve spaces.
326
327                        $(1)-$(2) := $$(call escape-shell,$$($(1)-$(2)))
328                endif
329
330                $(1)-$(2)-id := $$(call guess-tool,$$(tools-$(2)),$$($(1)-$(2)))
331
332                ifndef $(1)-$(2)-id
333                        $(1)-$(2)-id := $$($(1)-$(2)-id-default)
334
335                        $$(eval $$(call toolchain-warn-unrecognized,$(1),$(2)))
336                endif
337        endef
338
339        define toolchain-determine
340                $$(foreach tool-class,$$(tool-classes), \
341                        $$(eval $$(call toolchain-determine-tool,$(1),$$(tool-class))))
342        endef
343
344        $(foreach toolchain,$(toolchains), \
345                $(eval $(call toolchain-determine,$(toolchain))))
346endif
347