Skip to content

Commit

Permalink
General fixes to Build and Run
Browse files Browse the repository at this point in the history 
Signed-off-by: Joakim Bech <joakim.bech@linaro.org>
  • Loading branch information
@jbech-linaro
jbech-linaro committed Feb 8, 2019
1 parent 0881918 commit 110d63c
Show file tree
Hide file tree
Showing 5 changed files with 212 additions and 101 deletions.
172 changes: 80 additions & 92 deletions building/build_general.rst
View file
Original file line number Diff line number Diff line change
@@ -1,13 +1,17 @@
General build information
=========================
Yada yada
.. _build_system:

Build System
^^^^^^^^^^^^
The OP-TEE build system is based on GNU make and CMake. It consists of a main
``Makefile`` in the root of the project together with ``sub.mk`` files in all
source directories. In addition, some supporting files are used to recursively
process all ``sub.mk`` files and generate the build rules.
============
Build system
============
.. todo::

Joakim: Move this section to "optee_os"?

The OP-TEE build system is based on both GNU make and CMake (Linux user space
applications). :ref:`optee_os` consists of a main ``Makefile`` in the root of
the project together with ``sub.mk`` files in all source directories. In
addition, some supporting files are used to recursively process all ``sub.mk``
files and generate the build rules.

+------------------------------------------------+-------------------------------+
| Name | Description |
Expand Down Expand Up @@ -58,32 +62,30 @@ process all ``sub.mk`` files and generate the build rules.
invocation of make itself.

Choosing the build target
~~~~~~~~~~~~~~~~~~~~~~~~~
The target architecture, platform and build directory may be selected by
setting environment or make variables (``VAR=value make`` or ``make
VAR=value``).

**ARCH - CPU architecture**
^^^^^^^^^^^^^^^^^^^^^^^^^
The target architecture, platform and build directory may be selected by setting
environment or make variables (``VAR=value make`` or ``make VAR=value``).

ARCH - CPU architecture
~~~~~~~~~~~~~~~~~~~~~~~
``$(ARCH)`` is the CPU architecture to be built. Currently, the only supported
value is ``arm`` for 32-bit or 64-bit Armv7-A or Armv8-A. Please note that
contrary to the Linux kernel, ``$(ARCH)`` should **not** be set to ``arm64``
for 64-bit builds. The ``ARCH`` variable does not need to be set explicitly
before building either, because the proper instruction set is selected from the
``$(PLATFORM)`` value. For platforms that support both 32-bit and 64-bit
builds, ``CFG_ARM64_core=y`` should be set to select 64-bit and not set (or set
to ``n``) to select 32-bit.
contrary to the Linux kernel, ``$(ARCH)`` should **not** be set to ``arm64`` for
64-bit builds. The ``ARCH`` variable does not need to be set explicitly before
building either, because the proper instruction set is selected from the
``$(PLATFORM)`` value. For platforms that support both 32-bit and 64-bit builds,
``CFG_ARM64_core=y`` should be set to select 64-bit and not set (or set to
``n``) to select 32-bit.

Architecture-specific source code belongs to sub-directories that follow the
``arch/$(ARCH)`` pattern, such as: ``core/arch/arm``, ``lib/libmpa/arch/arm``,
``lib/libutee/arch/arm`` and so on.

**CROSS_COMPILE**

CROSS_COMPILE
~~~~~~~~~~~~~
``$(CROSS_COMPILE)`` is the prefix used to invoke the (32-bit) cross-compiler
toolchain. The default value is ``arm-linux-gnueabihf-``. This is the variable
you want to change in case you want to use `ccache
<https://ccache.samba.org/>`_ to speed you recompilations:
you want to change in case you want to use ccache_ to speed you recompilations:

.. code-block:: bash
Expand All @@ -92,10 +94,10 @@ you want to change in case you want to use `ccache
If the build includes a mix of 32-bit and 64-bit code, for instance if you set
``CFG_ARM64_core=y`` to build a 64-bit secure kernel, then two different
toolchains are used, that are controlled by ``$(CROSS_COMPILE32)`` and
``$(CROSS_COMPILE64)``. The default value of ``$(CROSS_COMPILE32)`` is the
value of ``CROSS_COMPILE``, which defaults to ``arm-linux-gnueabihf-`` as
mentioned above. The default value of ``$(CROSS_COMPILE64)`` is
``aarch64-linux-gnu-``. Examples:
``$(CROSS_COMPILE64)``. The default value of ``$(CROSS_COMPILE32)`` is the value
of ``CROSS_COMPILE``, which defaults to ``arm-linux-gnueabihf-`` as mentioned
above. The default value of ``$(CROSS_COMPILE64)`` is ``aarch64-linux-gnu-``.
Examples:

.. code-block:: bash
Expand Down Expand Up @@ -123,40 +125,38 @@ mentioned above. The default value of ``$(CROSS_COMPILE64)`` is
.. _platform_flavor:

**PLATFORM / PLATFORM_FLAVOR**

A *platform* is a family of closely related hardware configurations. A platform
*flavor* is a variant of such configurations. When used together they define
the target hardware on which OP-TEE will be run.
PLATFORM / PLATFORM_FLAVOR
~~~~~~~~~~~~~~~~~~~~~~~~~~
A `platform` is a family of closely related hardware configurations. A platform
`flavor` is a variant of such configurations. When used together they define the
target hardware on which OP-TEE will be run.

For instance ``PLATFORM=stm PLATFORM_FLAVOR=b2260`` will build for the ST
Microelectronics 96boards/cannes2 board, while ``PLATFORM=vexpress
PLATFORM_FLAVOR=qemu_virt`` will generate code for a para-virtualized Arm
Versatile Express board running on QEMU.

For convenience, the flavor may be appended to the platform name with a dash,
so ``make PLATFORM=stm-b2260`` is a shortcut for ``make PLATFORM=stm
PLATFORM_FLAVOR=b2260``. Note that in both cases the value of ``$(PLATFORM)``
is ``stm`` in the makefiles.

Platform-specific source code belongs to
``core/arch/$(ARCH)/plat-$(PLATFORM)``, for instance:
``core/arch/arm/plat-vexpress`` or ``core/arch/arm/plat-stm``.
For convenience, the flavor may be appended to the platform name with a dash, so
``make PLATFORM=stm-b2260`` is a shortcut for ``make PLATFORM=stm
PLATFORM_FLAVOR=b2260``. Note that in both cases the value of ``$(PLATFORM)`` is
``stm`` in the makefiles.

**O - output directory**
Platform-specific source code belongs to ``core/arch/$(ARCH)/plat-$(PLATFORM)``,
for instance: ``core/arch/arm/plat-vexpress`` or ``core/arch/arm/plat-stm``.

O - output directory
~~~~~~~~~~~~~~~~~~~~
All output files go into a platform-specific build directory, which is by
default ``out/$(ARCH)-plat-$(PLATFORM)``.

The output directory has basically the same structure as the source tree. For
instance, assuming ``ARCH=arm PLATFORM=stm``, ``core/kernel/panic.c`` will
compile into ``out/arm-plat-stm/core/kernel/panic.o``.

However, some libraries are compiled several times: once or twice for user
mode, and once for kernel mode. This is because they may be used by the TEE
Core as well as by the Trusted Applications. As a result, the ``lib`` source
directory gives two or three build directories: ``ta_arm{32,64}-lib`` and
``core-lib``.
However, some libraries are compiled several times: once or twice for user mode,
and once for kernel mode. This is because they may be used by the TEE Core as
well as by the Trusted Applications. As a result, the ``lib`` source directory
gives two or three build directories: ``ta_arm{32,64}-lib`` and ``core-lib``.

The output directory also has an ``export-ta_arm{32,64}`` directory, which
contains:
Expand All @@ -173,34 +173,32 @@ contains:
- In ``mk/``: ``ta_dev_kit.mk``, which is a Make include file with
suitable rules to build a TA, and its dependencies

- ``scripts/sign.py``: a Python script used by ``ta_dev_kit.mk`` to
sign TAs.
- ``scripts/sign.py``: a Python script used by ``ta_dev_kit.mk`` to sign
TAs.

- In ``src``: ``user_ta_header.c``: source file to add a suitable
header to the Trusted Application (as expected by the loader code in
the TEE Core).
- In ``src``: ``user_ta_header.c``: source file to add a suitable header
to the Trusted Application (as expected by the loader code in the TEE
Core).

- Some files needed to build host applications (using the Client API),
under ``export-ta_arm{32,64}/host_include``.
- Some files needed to build host applications (using the Client API), under
``export-ta_arm{32,64}/host_include``.

Finally, the build directory contains the auto-generated configuration file for
the TEE Core: ``$(O)/include/generated/conf.h`` (see below).

.. _configuration_and_flags:

Configuration and flags
~~~~~~~~~~~~~~~~~~~~~~~

^^^^^^^^^^^^^^^^^^^^^^^
The following variables are defined in ``core/arch/$(ARCH)/$(ARCH).mk``:

- ``$(core-platform-aflags)``, ``$(core-platform-cflags)`` and
``$(core-platform-cppflags)`` are added to the assembler / C compiler /
preprocessor flags for all source files compiled for TEE Core including
the kernel versions of ``libmpa.a`` and ``libutils.a``.

- ``$(ta_arm{32,64}-platform-aflags)``,
``$(ta_arm{32,64}-platform-cflags``) and
``$(ta_arm{32,64}-platform-cppflags)`` are added to the assembler / C
- ``$(ta_arm{32,64}-platform-aflags)``, ``$(ta_arm{32,64}-platform-cflags``)
and ``$(ta_arm{32,64}-platform-cppflags)`` are added to the assembler / C
compiler / preprocessor flags when building the user-mode libraries
(``libutee.a``, ``libutils.a``, ``libmpa.a``) or Trusted Applications.

Expand All @@ -215,15 +213,14 @@ The following variables are defined in ``core/arch/$(ARCH)/$(ARCH).mk``:
- ``$(core-platform-subdirs)`` is the list of the subdirectories that are
added to the TEE Core.


Linker scripts
~~~~~~~~~~~~~~
^^^^^^^^^^^^^^
The file ``core/arch/$(ARCH)/plat-$(PLATFORM)/link.mk`` contains the rules to
link the TEE Core and perform any related tasks, such as running ``objdump`` to
produce a dump file. ``link.mk`` adds files to the ``all:`` target.

Source files
~~~~~~~~~~~~
^^^^^^^^^^^^
Each directory that contains source files has a file called ``sub.mk``. This
makefile defines the source files that should be included in the build, as well
as any subdirectories that should be processed, too. For example:
Expand All @@ -243,17 +240,17 @@ as any subdirectories that should be processed, too. For example:
subdirs-y += drivers
The ``-y`` suffix is meant to facilitate conditional compilation. See
*Configuration* below.
section :ref:`configuration_variables` below.

``srcs-y`` and ``subdirs-y`` are often not used together in the same
``sub.mk``, because source files are usually alone in leaf directories. But
this is not a hard rule.
``srcs-y`` and ``subdirs-y`` are often not used together in the same ``sub.mk``,
because source files are usually alone in leaf directories. But this is not a
hard rule.

In addition to source files, ``sub.mk`` may define compiler flags, include
directories and/or configuration variables as explained below.

Compiler flags
~~~~~~~~~~~~~~
^^^^^^^^^^^^^^
Default compiler flags are defined in ``mk/compile.mk``. Note that
platform-specific flags must not appear in this file which is common to all
platforms.
Expand Down Expand Up @@ -288,16 +285,18 @@ affect all the source files that belong to the library: ``cppflags-lib-y`` and
``cflags-lib-y``.

Include directories
~~~~~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^^^^^
Include directories may be added to ``global-incdirs-y``, in which case they
will be accessible from all the source files and will be copied to
``export-ta_arm{32,64}/include`` and ``export-ta_arm{32,64}/host_include``.

When ``sub.mk`` is used to build a library, ``incdirs-lib-y`` may receive
additional directories that will be used for that library only.

.. _configuration_variables:

Configuration variables
~~~~~~~~~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^^^^^^^^^
Some features may be enabled, disabled or otherwise controlled at compile time
through makefile variables. Default values are normally provided in makefiles
with the ``?=`` operator so that their value may be easily overridden by
Expand All @@ -321,11 +320,11 @@ source file is built.
Depending on their value, variables may be considered either boolean or
non-boolean, which affects how they are translated into ``conf.h``.

**Boolean configuration variables**

Boolean configuration variables
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When a configuration variable controls the presence or absence of a feature,
``y`` means *enabled*, while ``n``, empty value or an undefined variable means
*disabled*. For instance, the following commands are equivalent and would
``y`` means **enabled**, while ``n``, empty value or an undefined variable means
**disabled**. For instance, the following commands are equivalent and would
disable feature ``CFG_CRYPTO_GCM``:

.. code-block:: bash
Expand Down Expand Up @@ -354,9 +353,9 @@ conditional compilation:
subdirs-$(CFG_CRYPTO_CCM) += ccm
subdirs-$(CFG_CRYPTO_GCM) += gcm
When a configuration variable is *enabled* (``y``), ``<generated/conf.h>``
When a configuration variable is **enabled** (``y``), ``<generated/conf.h>``
contains a macro with the same name as the variable and the value ``1``. If it
is *disabled*, however, no macro definition is output. This allows the C code
is **disabled**, however, no macro definition is output. This allows the C code
to use constructs like:

.. code-block:: c
Expand All @@ -372,8 +371,8 @@ to use constructs like:
};
#endif
**Non-boolean configuration variables**

Non-boolean configuration variables
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Configuration variables that are not recognized as booleans are simply output
unchanged into `<generated/conf.h>`. For instance:

Expand All @@ -387,21 +386,10 @@ unchanged into `<generated/conf.h>`. For instance:
#define CFG_TEE_CORE_LOG_LEVEL 4 /* '4' */
**Configuration dependencies**

Configuration dependencies
~~~~~~~~~~~~~~~~~~~~~~~~~~
Some combinations of configuration variables may not be valid. This should be
dealt with by custom checks in makefiles. ``mk/checkconf.h`` provides functions
to help detect and deal with such situations.


Buildroot
^^^^^^^^^

CMake
^^^^^

GNU Make
^^^^^^^^

OpenEmbedded
^^^^^^^^^^^^
.. _ccache: https://ccache.samba.org/

0 comments on commit 110d63c

Please sign in to comment.