blob: 3ae68231d0f16c05a86abb9ea559399fc61fc452 [file] [log] [blame]
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012012/03/30 - Mark Hatle <mark.hatle@windriver.com>
2 - Initial Revision
3
4
5Introduction
6============
7The individual CPU, and ABI tunings are contained in this directory. A
8number of local and global variables are used to control the way the
9tunings are setup and how they work together to specify an optimized
10configuration.
11
12The following is brief summary of the generic components that are used
13in these tunings.
14
15AVAILTUNES - This is a list of all of the tuning definitions currently
16available in the system. Not all tunes in this list may be compatible
17with the machine configuration, or each other in a multilib
18configuration. Each tuning file can add to this list using "+=", but
19should never replace the list using "=".
20
21DEFAULTTUNE - This specifies the tune to use for a particular build.
22Each tune should specify a reasonable default, which can be overriden by
23a machine or multilib configuration. The specified tune must be listed
24in the AVAILTUNES.
25
26TUNEVALID[feature] - The <feature> is defined with a human readable
27explanation for what it does. All architectural, cpu, abi, etc tuning
28features must be defined using TUNEVALID.
29
30TUNECONFLICTS[feature] - A list of features which conflict with <feature>.
31New sanity checks will try to reject combinations in which a single
32tuning ends up with features which conflict with each other.
33
Patrick Williams213cb262021-08-07 19:21:33 -050034TUNE_FEATURES - This is automatically defined as TUNE_FEATURES:tune-<tune>.
35See TUNE_FEATURES:tune-<tune> for more information.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050036
Patrick Williams213cb262021-08-07 19:21:33 -050037TUNE_FEATURES:tune-<tune> - Specify the features used to describe a
Patrick Williamsc124f4f2015-09-15 14:41:29 -050038specific tune. This is a list of features that a tune support, each
39feature must be in the TUNEVALID list. Note: the tune and a given
40feature name may be the same, but they have different purposes. Only
41features may be used to change behavior, while tunes are used to
42describe an overall set of features.
43
44ABIEXTENSION - An ABI extension may be specified by a specific feature
45or other tuning setting, such as TARGET_FPU. Any ABI extensions either
46need to be defined in the architectures base arch file, i.e.
47ABIEXTENSION = "eabi" in the arm case, or appended to in specific tune
48files with a ".=". Spaces are not allowed in this variable.
49
50TUNE_CCARGS - Setup the cflags based on the TUNE_FEATURES settings.
51These should be additive when defined using "+=". All items in this
52list should be dynamic! i.e.
53${@bb.utils.contains("TUNE_FEATURES", "feature", "cflag", "!cflag", d)}
54
55TUNE_ARCH - The GNU canonical arch for a specific architecture. i.e.
56arm, armeb, mips, mips64, etc. This value is used by bitbake to setup
57configure. TUNE_ARCH definitions are specific to a given architecture.
58They may be a single static definition, or may be dynamically adjusted.
59See each architecture's README for details for that CPU family.
60
61TUNE_PKGARCH - The package architecture used by the packaging systems to
62define the architecture, abi and tuning of a particular package.
63Similarly to TUNE_ARCH, the definition of TUNE_PKGARCH is specific to
64each architecture. See each architectures README for details for that
65CPU family.
66
67PACKAGE_EXTRA_ARCHS - Lists all runtime compatible package
68architectures. By default this is equal to
Patrick Williams213cb262021-08-07 19:21:33 -050069PACKAGE_EXTRA_ARCHS:tune-<tune>. If an architecture deviates from the
Patrick Williamsc124f4f2015-09-15 14:41:29 -050070default it will be listed in the architecture README.
71
Patrick Williams213cb262021-08-07 19:21:33 -050072PACKAGE_EXTRA_ARCHS:tune-<tune> - List all of the package architectures
Patrick Williamsc124f4f2015-09-15 14:41:29 -050073that are compatible with this specific tune. The package arch of this
74tune must be in the list.
75
76TARGET_FPU - The FPU setting for a given tune, hard (generate floating
77point instructions), soft (generate internal gcc calls), "other"
78architecture specific floating point. This is synchronized with the
79compiler and other toolchain items. This should be dynamically
80configured in the same way that TUNE_CCARGS is.
81
Patrick Williams213cb262021-08-07 19:21:33 -050082BASE_LIB:tune-<tune> - The "/lib" location for a specific ABI. This is
Patrick Williamsc124f4f2015-09-15 14:41:29 -050083used in a multilib configuration to place the libraries in the correct,
84non-conflicting locations.
85
86
87Best Practice
88=============
89The tune infrastructure is designed to be hierarchical. When writing a
90new tune file for a "fast-forward" CPU architecture (one that supports
91everything from a previous generation), it is recommended to require the
92previous generation tune file and specify PACKAGE_EXTRA_ARCHS using the
93previous generation's override and appending the new tune. Note that
94only one previous tune file should be included to avoid mutiple includes
95of the base arch which could lead to a broken configuration due to
96multiple prepend and append assignments.
97
98For example, for x86, there is a common x86/arch-x86.inc which is
99included in the base i586 tune file. The core2 tune builds
100on that, and corei7 builds on core2.