Difference between revisions of "How to configure OP-TEE"

[quality revision] [unchecked revision]
m (Bare Environment: fix typo in internal info: missing ' in command line)
m
Renaming.png This page is a candidate for renaming (move).
The requested new name is: STM32 MPU OP-TEE .
The supplied reason is: Article start to be generic .
-- LDE.
Wiki maintainers: remember to update the pages that link this page before renaming (moving) it.

1 Purpose[edit]

This article describes the configuration and process used for building several OP-TEE components from sources and deploying them the target.

The build example is based on the OpenSTLinux Developer Package or Distribution Package, and also presents build instructions for a bare environment.

2 Overview[edit]

OP-TEE is a trusted execution environment for Arm®v7-A and Arm®v8-A platforms. OP-TEE is made of several components described in OP-TEE architecture overview.

OP-TEE components generate boot images and files stored in the filesystem embedded in the target.

  • OP-TEE OS generates 3 boot image files to be loaded in the platform boot media, in the predefined partitions. The generated boot images include a STM32 binary header enabling the use of the authenticated boot and flash programming facilities.
  • OP-TEE client (package optee_client) can be built to generate non-secure services for the OP-TEE OS. The files generated from optee_client build are stored in the embedded filesystem.
  • OP-TEE project releases other packages intended for test and demonstration. These can be built and embedded in the target filesystem. Building optee_examples and optee_test generates client and trusted applications together with libraries which are all stored in the target filesystem. Note the OP-TEE Linux driver is built into the Linux kernel image and is part of the OP-TEE ecosystem.

OP-TEE can be embedded as BL32 in the STM32MP1 platform STM32 MPU platforms for the ST trusted configuration.

3 OP-TEE core configuration[edit]

3.1 STM32MP15[edit]

OP-TEE OS requires more than 256Ko RAM. SYSRAM is only 256Ko, the OP-TEE core must ise the pager mode to extends memory using DDR.

OP-TEE OS is loaded at the beginning of the SYSRAM by the FSBL. The OP-TEE could extend the memory to the full SYSRAM. As pager is used, a second part of the code is loaded in DDR (pageable part) in a restricted secure accessible area.

OP-TEE OS manages low power mode by saving its context in DDR (encrypted area) that is restored by a protected execution code saved in secured backup SRAM.

OP-TEE OS implements the following secure services:

  • PSCI services
    • System reset
    • CPU hotplug
    • Low power
  • SCMI services
    • Clock management
    • Reset management
  • OTP access services
  • PWR services
    • PWR regulator access for non secure IPs
    • Wakeup source management
  • RCC services Limited access
    • OPP request management
    • Calibration triggering

4 Build with the Distribution Package[edit]

The Distribution Package provides means to build the following OP-TEE components from their related bitbake target:

PC $> bitbake optee-os-stm32mp                # OP-TEE core firmware
PC $> bitbake optee-os-sdk-stm32mp            # OP-TEE development kit for Trusted Applications
PC $> bitbake optee-client                    # OP-TEE client
PC $> bitbake optee-test                      # OP-TEE test suite (optional)
PC $> bitbake optee-examples                  # TA and CA examples

Distribution Package build process includes fetching the source files, compiling them and installing them to the target images.

The Yocto recipes for the OP-TEE packages can be found in:

meta-st/meta-st-stm32mp/recipes-security/optee/optee-os-stm32mp*
meta-st/meta-st-openstlinux/recipes-security/optee/optee-client*
meta-st/meta-st-openstlinux/recipes-security/optee/optee-examples*
meta-st/meta-st-openstlinux/recipes-security/optee/optee-test*

4 5 Build with the Developer Package or a Bare Environment[edit]

Both Developer Package and bare build environments expect you to fetch/download the OP-TEE package source file trees in order to build the embedded binary images.

The instruction set below assumes all OP-TEE package source trees are available in the base directory referred as <sources>/. The source files are available from the github repositories:

PC $> cd <sources>/
PC $> git clone https://github.com/STMicroelectronics/optee_os.git
PC $> git clone https://github.com/OP-TEE/optee_client.git
PC $> git clone https://github.com/OP-TEE/optee_test.git
PC $> git clone https://github.com/linaro-swg/optee_examples.git
PC $> ls -1 <sources>/
optee_client
optee_examples
optee_os
optee_test
PC $> 

Warning white.png Warning
The STM32MP1 STM32 MPU platform is may not yet be fully merged in the official OP-TEE repository [1] hence the URL provided above refers to the ST distribution [2]


45.1 Initialize the cross compile environment[edit]

The compilation toolchain provided by the Developer Package can be used, refer to Setup Cross Compile Environment.

Alternatively other bare toolchains can be used to build the OP-TEE secure parts. In such case, the instructions below expect the toolchain to be part of the PATH and its prefix is defined by CROSS_COMPILE. One can use something like:

PC $> export PATH=<path-to-toolchain>:$PATH
PC $> export CROSS_COMPILE=<toolchain-prefix>-

45.2 Build OP-TEE OS[edit]

45.2.1 Developer Package SDK[edit]

The OP-TEE OS can be built from the Developer Package Makefile.sdk script that is present in the tarball. It automatically sets the proper configuration for the OP-TEE OS build. To build from shell command:

PC $> make -f Makefile.sdk CFG_EMBED_DTB_SOURCE_FILE=<board_dts_file_name>.dts

45.2.2 Bare Environment[edit]

Alternatively one can also build OP-TEE OS based a bare cross compilation toolchains, for example for the stm32mp157c-ev1 board:

PC $> cd <optee-os>
PC $> make PLATFORM=stm32mp1 \
           CFG_EMBED_DTB_SOURCE_FILE=stm32mp157c-ev1.dts \
           CFG_TEE_CORE_LOG_LEVEL=2 O=out all

45.2.3 Generated Files[edit]

The 3 OP-TEE boot images are generated at following paths:

<optee-os>/out/core/tee-header_v2.stm32bin
<optee-os>/out/core/tee-pageable_v2.stm32bin
<optee-os>/out/core/tee-pager_v2.stm32bin

One can get the configuration directives used for the build are available in this file:

<optee-os>/out/conf.mk

The build also generates a development kit used to build Trusted Application binaries:

<optee-os>/out/export-ta_arm32/

45.2.4 Details on build directives[edit]

Mandatory directives to build OP-TEE OS:

  • PLATFORM=<platform>
    • Ex: PLATFORM=stm32mp1 : builds an stm32mp1 platform
  • CFG_EMBED_DTB_SOURCE_FILE=<device-tree-source-file>: in-tree (core/arch/arm/dts/ ) device tree filename with its .dts extension.

Common optional directives:

  • CFG_TEE_CORE_DEBUG={n|y}: disable/enable debug support
  • CFG_TEE_CORE_LOG_LEVEL={0|1|2|3|4}: define the trace level (0: no trace, 4: overflow of traces)
  • CFG_UNWIND={n|y}: disable/enable stack unwind support

Note: internal memory size constrains the debug support level that can be provided.

45.2.5 Troubleshoot[edit]

The Developer Package toolchain may report dependency error in the traces such as:

PC $> make PLATFORM=stm32mp1 ...
arm-openstlinux_weston-linux-gnueabi-ld.bfd: cannot find libgcc.a: No such file or directory

To overcome the issue, add the directive comp-cflagscoreLIBGCC_LOCATE_CFLAGS=--sysroot=$SDKTARGETSYSROOT. I.e:

PC $> cd <optee-os>
PC $> make PLATFORM=stm32mp1 \
           CFG_EMBED_DTB_SOURCE_FILE=stm32mp157c-ev1.dts \
           CFG_TEE_CORE_LOG_LEVEL=2 \
           comp-cflagscoreLIBGCC_LOCATE_CFLAGS=--sysroot=$SDKTARGETSYSROOT${SDKTARGETSYSROOT} \
           O=out all

45.3 Build commands for other OP-TEE components[edit]

This section describes how the several OP-TEE components (excluding OP-TEE OS described in above section) can be built. All those components generate files targeting the embedded Linux OS based filesystem (i.e the rootfs). These files are the secure Trusted Applications (TAs) binaries as well as non-secure Client Applications (CAs), libraries and test files.

There are several ways to build the OP-TEE components. The examples given below refer to OP-TEE client, test and examples source file tree paths as <optee-client>, <optee-test> and <optee-examples>.

Building these components expect, at least for the trusted applications, that the OP-TEE OS was built and the generated TA development kit is available at <optee-os>/out/export-ta_arm32/.

It is recommended to use CMake for building the Linux userland part whereas secure world binaries (TAs) must be build from their GNU makefiles as the OP-TEE project has not yet ported the secure world binaries build process over CMake.

45.3.1 Build the secure components[edit]

Build the TAs: This step expects OP-TEE OS is built to generate the 32bit TA development kit. Assuming OP-TEE OS was built at path <optee-os>/out, the TA development kit is available from path <optee-os>/out/export-ta_arm32/.

Instructions below build and copy the Trusted Application binaries to a local ./target/ directory that can be used to populate the target filesystem.

PC $> export TA_DEV_KIT_DIR=$PWD/optee_os/out/export-ta_arm32
PC $> mkdir -p ./target/lib/optee_armtz
PC $> for f in optee_test/ta/*/Makefile; do \
            make -C `dirname $f` O=out; \
            cp -f `dirname $f`/out/*.ta ./target/lib/optee_armtz; \
      done

Content in local directory ./target/ are the TA binary files:

PC $> tree target/
target
└── lib
  └── optee_armtz
   ├── 614789f2-39c0-4ebf-b235-92b32ac107ed.ta
   ├── 731e279e-aafb-4575-a771-38caa6f0cca6.ta
   └── (...)

These files need to be copied to the the target filesystem.

45.3.2 Build the non-secure components[edit]

Download the OP-TEE source files in a base directory and create a CMakeLists.txt file in the base directory that lists all package to be built through CMake. For example:

PC $> ls
optee_client
optee_examples
optee_os
optee_test
CMakeLists.txt
PC $> cat CMakeLists.txt
add_subdirectory (optee_client)
add_subdirectory (optee_test)
add_subdirectory (optee_examples)
PC $> 

From base directory, run cmake then make. The example below also creates the tree file system ./target/ that is populated with files generated that need to be installed in the target file system.
Note this examples also sets the toolchain environment:

PC $> cmake -DOPTEE_TEST_SDK=$PWD/optee_os/out/export-ta_arm32 \
            -DCMAKE_INSTALL_PREFIX=  -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=y
PC $> make
PC $> make DESTDIR=target install 

Note the empty CMAKE_INSTALL_PREFIX value to get thing installed from root /, not from /usr/. DESTDIR=target makes the embedded files be populated in the local ./target/ directory.

Note also that stm32mp15 stm32mp1 expects tool tee-supplicant to be located in directory /usr/bin whereas CMake installs it in directory /usr/sbin. To overcome this issue, one can build a link to the effective location, i.e:

PC $> ln -s ../bin/tee-supplicant target/sbin/tee-supplicant

Once done, local directory ./target/ contains the files to be copied in the target filesystem.

PC $> tree target/
target/
├── bin
│   ├── benchmark
│   ├── optee_example_acipher
│   ├── optee_example_aes
│   ├── optee_example_hello_world
│   ├── optee_example_hotp
│   ├── optee_example_random
│   ├── optee_example_secure_storage
│   ├── tee-supplicant
│   └── xtest
├── include
│   ├── tee_bench.h
│   ├── tee_client_api_extensions.h
│   ├── tee_client_api.h
│   └── teec_trace.h
├── lib
│   ├── libteec.so -> libteec.so.1
│   ├── libteec.so.1 -> libteec.so.1.0.0
│   └── libteec.so.1.0.0
│   └── optee_armtz
│       └── (...)                 # This directory was previously filled with TAs
└── sbin
    └── tee-supplicant -> ../bin/tee-supplicant

5 Update software on board6 Update OP-TEE boot images[edit]

The OP-TEE OS boot images shall be loaded into the related partitions of the boot media.
are included in the FIP binary loaded by the TF-A BL2 FSBL.
FIP binary package must be created or updated following these instructions.

7 Update OP-TEE Linux files[edit]

8 Update on board[edit]

The other OP-TEE images are stored in the target filesystem.

For example, if using an SD card as target boot media, the card can be plugged in its PC card reader and the images copied. OP-TEE core boot images can be loaded using tool dd while other The files can be simply copied into the mounted rootfs.

58.1 Update OP-TEE Core Boot Partitions in an SD card[edit]

If booting the target from an SD card, the core OP-TEE firmware can be updated using the tool dd.
Plug the SD card into the computer slot reader and copy the binary to the dedicated partition; on an SDCard/USB disk the OP-TEE OS boot partitions are partition 4 to 6.

The target partition is located from the partition labels of the SD card, i.e:

PC $> ls -l /dev/disk/by-partlabel/
total 0
lrwxrwxrwx 1 root root 10 Jan 28 16:35 bootfs -> ../../sdd7        (Linux kernel boot filesystem)
lrwxrwxrwx 1 root root 10 Jan 28 16:35 fsbl1 -> ../../sdd1         (part#1 is TF-A)
lrwxrwxrwx 1 root root 10 Jan 28 16:35 fsbl2 -> ../../sdd2         (part#2 is TF-A backup)
lrwxrwxrwx 1 root root 10 Jan 28 16:35 rootfs -> ../../sdd9        (Linux kernel root filesystem)
lrwxrwxrwx 1 root root 10 Jan 28 16:35 ssbl -> ../../sdd3          (part#3# is U-Boot)
lrwxrwxrwx 1 root root 10 Jan 28 16:35 teed -> ../../sdd5          (OP-TEE OS paged data)
lrwxrwxrwx 1 root root 10 Jan 28 16:35 teeh -> ../../sdd4          (OP-TEE OS header image)
lrwxrwxrwx 1 root root 10 Jan 28 16:35 teex -> ../../sdd6          (OP-TEE OS resident core)
lrwxrwxrwx 1 root root 11 Jan 28 16:35 userfs -> ../../sdd10       (Linux kernel user filesystem)
lrwxrwxrwx 1 root root 10 Jan 28 16:35 vendorfs -> ../../sdd8      (Linux kernel vendor filesystem)

For the SD card described above, the 3 OP-TEE core images can then be updated with:

PC $> dd conv=fdatasync of=/dev/sdd4 if=<optee-os>/out/core/tee-header_v2.stm32
PC $> dd conv=fdatasync of=/dev/sdd5 if=<optee-os>/out/core/tee-pageable_v2.stm32
PC $> dd conv=fdatasync of=/dev/sdd6 if=<optee-os>/out/core/tee-pager_v2.stm32 

5.2 Update OP-TEE Linux Files in a SD card[edit]

The OP-TEE files that need to be copied to the target filesystem were installed in a local directory ./target/.

They can now be copied to the target SD card rootfs partition once the SD card is plugged to the host computer and its filesystems are mounted in the host, i.e

PC $> cp -ar target/* /media/$USERNAME/rootfs/

5.3 Update via USB mass storage on U-boot[edit]

See How to use USB mass storage in U-Boot and follow the previous sections to load binary files tee-*_v2.stm32 onto target partitions.

5.4 Update

9 Update your boot device (including SD card on the target)[edit]

Refer to the STM32CubeProgrammer documentation to update your target.

6 10 References[edit]



{{ArticleToRename | STM32 MPU OP-TEE | Article start to be generic | LDE}}== Purpose ==
This article describes the configuration and process used for building several OP-TEE components from sources and deploying them the target.<br>


The build example is based on the OpenSTLinux [[STM32MP1_Developer_Package|Developer Package]] or [[STM32MP1_Distribution_Package|Distribution Package]], and also presents build instructions for a bare environment.

== Overview ==
OP-TEE is a trusted execution environment for Arm<sup>&reg;</sup>v7-A and Arm<sup>&reg;</sup>v8-A platforms.
OP-TEE is made of several components described in [[OP-TEE_overview#Architecture|OP-TEE architecture overview]].<br>


OP-TEE components generate boot images and files stored in the filesystem embedded in the target.

* OP-TEE OS generates 3 boot image files to be loaded in the platform boot media, in the predefined partitions. The generated boot images include a [[STM32MP15_secure_boot#STM32_Header|STM32 binary header]] enabling the use of the authenticated boot and flash programming facilities.

* OP-TEE client (package optee_client) can be built to generate non-secure services for the OP-TEE OS. The files generated from optee_client build are stored in the embedded filesystem.

* OP-TEE project releases other packages intended for test and demonstration. These can be built and embedded in the target filesystem. Building optee_examples and optee_test generates client and trusted applications together with libraries which are all stored in the target filesystem. Note the OP-TEE Linux driver is built into the Linux kernel image and is part of the OP-TEE ecosystem.

OP-TEE can be embedded as BL32 in the STM32MP1 platform STM32 MPU platforms for the ST trusted configuration.<br>


== OP-TEE core configuration ==
=== STM32MP15 ===
OP-TEE OS requires more than 256Ko RAM. [[SYSRAM_internal_memory|SYSRAM]] is only 256Ko, the OP-TEE core must ise the pager mode to extends memory using DDR.

OP-TEE OS is loaded at the beginning of the [[SYSRAM_internal_memory|SYSRAM]] by the FSBL. The OP-TEE could extend the memory to the full [[SYSRAM_internal_memory|SYSRAM]].
As pager is used, a second part of the code is loaded in DDR (pageable part) in a restricted secure accessible area.

OP-TEE OS manages low power mode by saving its context in DDR (encrypted area) that is restored by a protected execution code saved in secured [[BKPSRAM_internal_memory|backup SRAM]].

OP-TEE OS implements the following secure services:
* PSCI services
** System reset
** CPU hotplug
** Low power
* [[SCMI_overview|SCMI services]]
** Clock management
** Reset management
* OTP access services
* [[PWR_internal_peripheral|PWR services]]
** PWR regulator access for non secure IPs
** Wakeup source management
* [[RCC_internal_peripheral|RCC services]] Limited access
** OPP request management
** Calibration triggering

== Build with the Distribution Package ==

The [[STM32MP1_Distribution_Package|Distribution Package]] provides means to build the following OP-TEE components from their related bitbake target:

 {{PC$}} bitbake optee-os-stm32mp                # OP-TEE core firmware
 {{PC$}} bitbake optee-os-sdk-stm32mp            # OP-TEE development kit for Trusted Applications
 {{PC$}} bitbake optee-client                    # OP-TEE client
 {{PC$}} bitbake optee-test                      # OP-TEE test suite (optional)
 {{PC$}} bitbake optee-examples                  # TA and CA examples

[[STM32MP1_Distribution_Package|Distribution Package]] build process includes fetching the source files, compiling them and installing them to the target images.

The Yocto recipes for the OP-TEE packages can be found in:<br>

 meta-st/meta-st-stm32mp/recipes-security/optee/optee-os-stm32mp*
 meta-st/meta-st-openstlinux/recipes-security/optee/optee-client*
 meta-st/meta-st-openstlinux/recipes-security/optee/optee-examples*
 meta-st/meta-st-openstlinux/recipes-security/optee/optee-test*

== Build with the Developer Package or a Bare Environment ==

Both [[STM32MP1_Developer_Package|Developer Package]] and bare build environments expect you to fetch/download the OP-TEE package source file trees in order to build the embedded binary images.

The instruction set below assumes all OP-TEE package source trees are available in the base directory referred as <sources>/. The source files are available from the github repositories:
 {{PC$}} cd <sources>/
 {{PC$}} git clone https://github.com/STMicroelectronics/optee_os.git
 {{PC$}} git clone https://github.com/OP-TEE/optee_client.git
 {{PC$}} git clone https://github.com/OP-TEE/optee_test.git
 {{PC$}} git clone https://github.com/linaro-swg/optee_examples.git
 {{PC$}} ls -1 <sources>/
 optee_client
 optee_examples
 optee_os
 optee_test
 {{PC$}} 

{{Warning|The STM32MP1 STM32 MPU platform ismay not yetbe fully merged in the official OP-TEE repository <ref name=OP-TEE/optee_os>https://github.com/OP-TEE/optee_os</ref> hence the URL provided above refers to the ST distribution <ref name=STMicroelectronics/optee_os>https://github.com/STMicroelectronics/optee_os</ref>}}

{{InternalInfo |
Download optee_os source code from the internal Git:
 {{PC$}} git clone ssh://gerrit.st.com:29418/mpu/oe/optee/optee_os.git
}}

=== Initialize the cross compile environment ===

The compilation toolchain provided by the [[STM32MP1_Developer_Package|Developer Package]] can be used, refer to [[Cross-compile with OpenSTLinux SDK|Setup Cross Compile Environment]].

Alternatively other bare toolchains can be used to build the OP-TEE '''secure''' parts. In such case, the instructions below expect the toolchain to be part of the '''PATH''' and its prefix is defined by '''CROSS_COMPILE'''. One can use something like:
 {{PC$}} export PATH=<path-to-toolchain>:$PATH
 {{PC$}} export CROSS_COMPILE=<toolchain-prefix>-

=== Build OP-TEE OS ===

==== Developer Package SDK ====
The OP-TEE OS can be built from the [[STM32MP1_Developer_Package|Developer Package]] '''Makefile.sdk''' script that is present in the tarball. It automatically sets the proper configuration for the OP-TEE OS build. To build from shell command:<br>

 {{PC$}} make -f Makefile.sdk CFG_EMBED_DTB_SOURCE_FILE=<board_dts_file_name>.dts

==== Bare Environment ===={{InternalInfo | 
Started from 3.11.0, Build commands are changing:<pre>

 {{PC$}} make PLATFORM=stm32mp1 \
            CFG_EMBED_DTB_SOURCE_FILE=stm32mp157c-ev1.dts \
            CFG_TEE_CORE_LOG_LEVEL=2 O=out \
            LIBGCC_LOCATE_CFLAGS='--sysroot='${SDKTARGETSYSROOT} \ 
            CFLAGS='-std=gnu99' all </pre>

}}
Alternatively one can also build OP-TEE OS based a bare cross compilation toolchains, for example for the stm32mp157c-ev1 board:
 {{PC$}} cd <optee-os>

 {{PC$}} make PLATFORM=stm32mp1 \
            CFG_EMBED_DTB_SOURCE_FILE=stm32mp157c-ev1.dts \
            CFG_TEE_CORE_LOG_LEVEL=2 O=out all

==== Generated Files ====
The 3 OP-TEE boot images are generated at following paths:<optee-os>/out/core/tee-header_v2.stm32bin
<optee-os>/out/core/tee-pageable_v2.stm32bin
<optee-os>/out/core/tee-pager_v2.stm32bin


One can get the configuration directives used for the build are available in this file:<optee-os>/out/conf.mk

The build also generates a development kit used to build Trusted Application binaries:<optee-os>/out/export-ta_arm32/

==== Details on build directives ====

Mandatory directives to build OP-TEE OS:
* '''PLATFORM=stm32mp1'''<platform>'''
** Ex: '''PLATFORM=stm32mp1''' : builds an stm32mp1 platform
* '''CFG_EMBED_DTB_SOURCE_FILE=<device-tree-source-file>''': in-tree ({{CodeSource | OP-TEE_OS | core/arch/arm/dts/}}) device tree filename with its '''.dts''' extension.

Common optional directives:
* '''CFG_TEE_CORE_DEBUG={n|y}''': disable/enable debug support
* '''CFG_TEE_CORE_LOG_LEVEL={0|1|2|3|4}''': define the trace level (0: no trace, 4: overflow of traces)
* '''CFG_UNWIND={n|y}''': disable/enable stack unwind support

Note: internal memory size constrains the debug support level that can be provided.

==== Troubleshoot ====
The [[STM32MP1_Developer_Package|Developer Package]] toolchain may report dependency error in the traces such as:
 {{PC$}} make PLATFORM=stm32mp1 ...
 arm-openstlinux_weston-linux-gnueabi-ld.bfd: cannot find libgcc.a: No such file or directory

To overcome the issue, add the directive '''comp-cflagscoreLIBGCC_LOCATE_CFLAGS=--sysroot=$SDKTARGETSYSROOT'''. I.e:
 {{PC$}} cd <optee-os>

 {{PC$}} make PLATFORM=stm32mp1 \
            CFG_EMBED_DTB_SOURCE_FILE=stm32mp157c-ev1.dts \
            CFG_TEE_CORE_LOG_LEVEL=2 \comp-cflagscoreLIBGCC_LOCATE_CFLAGS=--sysroot=$SDKTARGETSYSROOT${SDKTARGETSYSROOT} \
            O=out all

=== Build commands for other OP-TEE components ===

This section describes how the several OP-TEE components (excluding OP-TEE OS described in above section) can be built. All those components generate files targeting the embedded Linux OS based filesystem (i.e the rootfs). These files are the secure Trusted Applications (TAs) binaries as well as non-secure Client Applications (CAs), libraries and test files.

There are several ways to build the OP-TEE components. The examples given below refer to OP-TEE client, test and examples source file tree paths as<optee-client>, <optee-test> and <optee-examples>.

Building these components expect, at least for the trusted applications, that the OP-TEE OS was built and the generated TA development kit is available at <optee-os>/out/export-ta_arm32/.

It is recommended to use CMake for building the Linux userland part whereas secure world binaries (TAs) must be build from their GNU makefiles as the OP-TEE project has not yet ported the secure world binaries build process over CMake.

==== Build the secure components====

Build the TAs: This step expects OP-TEE OS is built to generate the 32bit TA development kit. Assuming OP-TEE OS was built at path <optee-os>/out, the TA development kit is available from path <optee-os>/out/export-ta_arm32/.

Instructions below build and copy the Trusted Application binaries to a local '''./target/''' directory that can be used to populate the target
filesystem.

 {{PC$}} export TA_DEV_KIT_DIR=$PWD/optee_os/out/export-ta_arm32
 {{PC$}} mkdir -p ./target/lib/optee_armtz
 {{PC$}} for f in optee_test/ta/*/Makefile; do \
             make -C `dirname $f` O=out; \
             cp -f `dirname $f`/out/*.ta ./target/lib/optee_armtz; \
       done

Content in local directory '''./target/''' are the TA binary files: 

 {{PC$}} tree target/
 target
 └── lib
   └── optee_armtz
    ├── 614789f2-39c0-4ebf-b235-92b32ac107ed.ta
    ├── 731e279e-aafb-4575-a771-38caa6f0cca6.ta
    └── (...)

These files need to be copied to the the target filesystem.

==== Build the non-secure components====

Download the OP-TEE source files in a base directory and create a '''CMakeLists.txt''' file in the base directory that lists all package to be built through CMake. For example:

 {{PC$}} ls
 optee_client
 optee_examples
 optee_os
 optee_test
 CMakeLists.txt
 {{PC$}} cat CMakeLists.txt
 add_subdirectory (optee_client)
 add_subdirectory (optee_test)
 add_subdirectory (optee_examples)
 {{PC$}} 

From base directory, run '''cmake''' then '''make'''. The example below also creates the tree file system '''./target/''' that is populated with files generated that need to be installed in the target file system.<br>

Note this examples also sets the toolchain environment:

 {{PC$}} cmake -DOPTEE_TEST_SDK=$PWD/optee_os/out/export-ta_arm32 \
             -DCMAKE_INSTALL_PREFIX=  -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=y
 {{PC$}} make
 {{PC$}} make DESTDIR=target install 

Note the empty '''CMAKE_INSTALL_PREFIX''' value to get thing installed from root '''/''', not from '''/usr/'''.
'''DESTDIR=target''' makes the embedded files be populated in the local '''./target/''' directory.

Note also that stm32mp15stm32mp1 expects tool '''tee-supplicant''' to be located in directory '''/usr/bin''' whereas CMake installs it in directory '''/usr/sbin'''. To overcome this issue, one can build a link to the effective location, i.e:

 {{PC$}} ln -s ../bin/tee-supplicant target/sbin/tee-supplicant

Once done, local directory '''./target/''' contains the files to be copied in the target filesystem.

 {{PC$}} tree target/
 target/
 ├── bin
 │   ├── benchmark
 │   ├── optee_example_acipher
 │   ├── optee_example_aes
 │   ├── optee_example_hello_world
 │   ├── optee_example_hotp
 │   ├── optee_example_random
 │   ├── optee_example_secure_storage
 │   ├── tee-supplicant
 │   └── xtest
 ├── include
 │   ├── tee_bench.h
 │   ├── tee_client_api_extensions.h
 │   ├── tee_client_api.h
 │   └── teec_trace.h
 ├── lib
 │   ├── libteec.so -> libteec.so.1
 │   ├── libteec.so.1 -> libteec.so.1.0.0
 │   └── libteec.so.1.0.0
 │   └── optee_armtz
 │       └── (...)                 # This directory was previously filled with TAs
 └── sbin
     └── tee-supplicant -> ../bin/tee-supplicant

== Update software on board ==

The OP-TEE boot images ==
OP-TEE OS boot images shall be loaded into the related partitions of the boot media.<br>

The other OP-TEE images are stored in the target filesystem.<br>


For example, if using an SD card as target boot media, the card can be plugged in its PC card reader and the images copied. OP-TEE core boot images can be loaded using tool '''dd''' while other files can be simply copied into the mounted rootfs.

=== Update OP-TEE Core Boot Partitions in an SD card ===

If booting the target from an SD card, the core OP-TEE firmware can be updated using the tool '''dd'''.<br>

Plug the SD card into the computer slot reader and copy the binary to the dedicated partition; on an SDCard/USB disk the OP-TEE OS boot partitions are partition 4 to 6.

The target partition is located from the partition labels of the SD card, i.e:
 {{PC$}} ls -l /dev/disk/by-partlabel/
 total 0
 lrwxrwxrwx 1 root root 10 Jan 28 16:35 bootfs -> ../../sdd7        (Linux kernel boot filesystem)
 lrwxrwxrwx 1 root root 10 Jan 28 16:35 fsbl1 -> ../../sdd1         (part#1 is TF-A)
 lrwxrwxrwx 1 root root 10 Jan 28 16:35 fsbl2 -> ../../sdd2         (part#2 is TF-A backup)
 lrwxrwxrwx 1 root root 10 Jan 28 16:35 rootfs -> ../../sdd9        (Linux kernel root filesystem)
 lrwxrwxrwx 1 root root 10 Jan 28 16:35 ssbl -> ../../sdd3          (part#3# is U-Boot)
 lrwxrwxrwx 1 root root 10 Jan 28 16:35 teed -> ../../sdd5          (OP-TEE OS paged data)
 lrwxrwxrwx 1 root root 10 Jan 28 16:35 teeh -> ../../sdd4          (OP-TEE OS header image)
 lrwxrwxrwx 1 root root 10 Jan 28 16:35 teex -> ../../sdd6          (OP-TEE OS resident core)
 lrwxrwxrwx 1 root root 11 Jan 28 16:35 userfs -> ../../sdd10       (Linux kernel user filesystem)
 lrwxrwxrwx 1 root root 10 Jan 28 16:35 vendorfs -> ../../sdd8      (Linux kernel vendor filesystem)

For the SD card described above, the 3 OP-TEE core images can then be updated with:
 {{PC$}} dd conv=fdatasync of=/dev/sdd4 if=<optee-os>/out/core/tee-header_v2.stm32
 {{PC$}} dd conv=fdatasync of=/dev/sdd5 if=<optee-os>/out/core/tee-pageable_v2.stm32
 {{PC$}} dd conv=fdatasync of=/dev/sdd6 if=<optee-os>/out/core/tee-pager_v2.stm32 

=== Update OP-TEE Linux Files are included in the [[link to FIP|FIP binary]] loaded by the [[STM32MP15_TF-A|TF-A BL2 FSBL]].<br>

[[link to FIP|FIP binary]] package must be created or updated following [[FIP|these instructions]].

== Update OP-TEE Linux files ==
== Update on board ==
The other OP-TEE images are stored in the target filesystem.<br>


For example, if using an SD card as target boot media, the card can be plugged in its PC card reader and the images copied.
The files can be simply copied into the mounted rootfs.

=== Update in a SD card ===
The OP-TEE files that need to be copied to the target filesystem were installed in a local directory '''./target/'''.

They can now be copied to the target SD card rootfs partition once the SD card is plugged to the host computer and its filesystems are mounted in the host, i.e
 {{PC$}} cp -ar target/* /media/$USERNAME/rootfs/

=== Update via USB mass storage on U-boot ===
See [[How to use USB mass storage in U-Boot]] and follow the previous sections to 
load binary files '''tee-*_v2.stm32''' onto target partitions.

=== Update your boot device (including SD card on the target) ===

Refer to the [[STM32CubeProgrammer]] documentation to update your target.

== References ==<references />

<noinclude>

{{PublicationRequestId | 10619 | 2019-02-01 | Gregorys}}
[[Category:OP-TEE secure OS]]</noinclude>
Line 1: Line 1:
  +
{{ArticleToRename | STM32 MPU OP-TEE | Article start to be generic | LDE}}
 
== Purpose ==
 
== Purpose ==
This article describes the process used for building several OP-TEE components from sources and deploying them the target.<br>
+
This article describes the configuration and process used for building several OP-TEE components from sources and deploying them the target.<br>
   
 
The build example is based on the OpenSTLinux [[STM32MP1_Developer_Package|Developer Package]] or [[STM32MP1_Distribution_Package|Distribution Package]], and also presents build instructions for a bare environment.
 
The build example is based on the OpenSTLinux [[STM32MP1_Developer_Package|Developer Package]] or [[STM32MP1_Distribution_Package|Distribution Package]], and also presents build instructions for a bare environment.
Line 16: Line 17:
 
* OP-TEE project releases other packages intended for test and demonstration. These can be built and embedded in the target filesystem. Building optee_examples and optee_test generates client and trusted applications together with libraries which are all stored in the target filesystem. Note the OP-TEE Linux driver is built into the Linux kernel image and is part of the OP-TEE ecosystem.
 
* OP-TEE project releases other packages intended for test and demonstration. These can be built and embedded in the target filesystem. Building optee_examples and optee_test generates client and trusted applications together with libraries which are all stored in the target filesystem. Note the OP-TEE Linux driver is built into the Linux kernel image and is part of the OP-TEE ecosystem.
   
OP-TEE can be embedded in the STM32MP1 platform for the ST trusted configuration.<br>
+
OP-TEE can be embedded as BL32 in the STM32 MPU platforms for the ST trusted configuration.<br>
  +
 
  +
== OP-TEE core configuration ==
  +
=== STM32MP15 ===
  +
OP-TEE OS requires more than 256Ko RAM. [[SYSRAM_internal_memory|SYSRAM]] is only 256Ko, the OP-TEE core must ise the pager mode to extends memory using DDR.
  +
 
  +
OP-TEE OS is loaded at the beginning of the [[SYSRAM_internal_memory|SYSRAM]] by the FSBL. The OP-TEE could extend the memory to the full [[SYSRAM_internal_memory|SYSRAM]].
  +
As pager is used, a second part of the code is loaded in DDR (pageable part) in a restricted secure accessible area.
  +
 
  +
OP-TEE OS manages low power mode by saving its context in DDR (encrypted area) that is restored by a protected execution code saved in secured [[BKPSRAM_internal_memory|backup SRAM]].
  +
 
  +
OP-TEE OS implements the following secure services:
  +
* PSCI services
  +
** System reset
  +
** CPU hotplug
  +
** Low power
  +
* [[SCMI_overview|SCMI services]]
  +
** Clock management
  +
** Reset management
  +
* OTP access services
  +
* [[PWR_internal_peripheral|PWR services]]
  +
** PWR regulator access for non secure IPs
  +
** Wakeup source management
  +
* [[RCC_internal_peripheral|RCC services]] Limited access
  +
** OPP request management
  +
** Calibration triggering
   
 
== Build with the Distribution Package ==
 
== Build with the Distribution Package ==
Line 53: Line 79:
 
  {{PC$}}  
 
  {{PC$}}  
   
{{Warning|The STM32MP1 platform is not yet fully merged in the official OP-TEE repository <ref name=OP-TEE/optee_os>https://github.com/OP-TEE/optee_os</ref> hence the URL provided above refers to the ST distribution <ref name=STMicroelectronics/optee_os>https://github.com/STMicroelectronics/optee_os</ref>}}
+
{{Warning|The STM32 MPU platform may not be fully merged in the official OP-TEE repository <ref name=OP-TEE/optee_os>https://github.com/OP-TEE/optee_os</ref> hence the URL provided above refers to the ST distribution <ref name=STMicroelectronics/optee_os>https://github.com/STMicroelectronics/optee_os</ref>}}
   
 
{{InternalInfo |
 
{{InternalInfo |
Line 75: Line 101:
   
 
==== Bare Environment ====
 
==== Bare Environment ====
{{InternalInfo |
 
Started from 3.11.0, Build commands are changing:
 
<pre>
 
{{PC$}} make PLATFORM=stm32mp1 \
 
            CFG_EMBED_DTB_SOURCE_FILE=stm32mp157c-ev1.dts \
 
            CFG_TEE_CORE_LOG_LEVEL=2 O=out \
 
            LIBGCC_LOCATE_CFLAGS='--sysroot='${SDKTARGETSYSROOT} \
 
            CFLAGS='-std=gnu99' all
 
</pre>
 
}}
 
 
 
Alternatively one can also build OP-TEE OS based a bare cross compilation toolchains, for example for the stm32mp157c-ev1 board:
 
Alternatively one can also build OP-TEE OS based a bare cross compilation toolchains, for example for the stm32mp157c-ev1 board:
 
  {{PC$}} cd <optee-os>
 
  {{PC$}} cd <optee-os>
Line 94: Line 109:
 
==== Generated Files ====
 
==== Generated Files ====
 
The 3 OP-TEE boot images are generated at following paths:
 
The 3 OP-TEE boot images are generated at following paths:
  <optee-os>/out/core/tee-header_v2.stm32
+
  <optee-os>/out/core/tee-header_v2.bin
  <optee-os>/out/core/tee-pageable_v2.stm32
+
  <optee-os>/out/core/tee-pageable_v2.bin
  <optee-os>/out/core/tee-pager_v2.stm32
+
  <optee-os>/out/core/tee-pager_v2.bin
   
 
One can get the configuration directives used for the build are available in this file:
 
One can get the configuration directives used for the build are available in this file:
Line 107: Line 122:
   
 
Mandatory directives to build OP-TEE OS:
 
Mandatory directives to build OP-TEE OS:
* '''PLATFORM=stm32mp1''': builds an stm32mp1 platform
+
* '''PLATFORM=<platform>'''
* '''CFG_EMBED_DTB_SOURCE_FILE=<device-tree-source-file>''': in-tree (core/arch/arm/dts/) device tree filename with its '''.dts''' extension.
+
** Ex: '''PLATFORM=stm32mp1''' : builds an stm32mp1 platform
  +
* '''CFG_EMBED_DTB_SOURCE_FILE=<device-tree-source-file>''': in-tree ({{CodeSource | OP-TEE_OS | core/arch/arm/dts/}}) device tree filename with its '''.dts''' extension.
   
 
Common optional directives:
 
Common optional directives:
Line 122: Line 138:
 
  arm-openstlinux_weston-linux-gnueabi-ld.bfd: cannot find libgcc.a: No such file or directory
 
  arm-openstlinux_weston-linux-gnueabi-ld.bfd: cannot find libgcc.a: No such file or directory
   
To overcome the issue, add the directive '''comp-cflagscore=--sysroot=$SDKTARGETSYSROOT'''. I.e:
+
To overcome the issue, add the directive '''LIBGCC_LOCATE_CFLAGS=--sysroot=$SDKTARGETSYSROOT'''. I.e:
 
  {{PC$}} cd <optee-os>
 
  {{PC$}} cd <optee-os>
 
  {{PC$}} make PLATFORM=stm32mp1 \
 
  {{PC$}} make PLATFORM=stm32mp1 \
 
             CFG_EMBED_DTB_SOURCE_FILE=stm32mp157c-ev1.dts \
 
             CFG_EMBED_DTB_SOURCE_FILE=stm32mp157c-ev1.dts \
 
             CFG_TEE_CORE_LOG_LEVEL=2 \
 
             CFG_TEE_CORE_LOG_LEVEL=2 \
             comp-cflagscore=--sysroot=$SDKTARGETSYSROOT \
+
             LIBGCC_LOCATE_CFLAGS=--sysroot=${SDKTARGETSYSROOT} \
 
             O=out all
 
             O=out all
   
Line 194: Line 210:
 
'''DESTDIR=target''' makes the embedded files be populated in the local '''./target/''' directory.
 
'''DESTDIR=target''' makes the embedded files be populated in the local '''./target/''' directory.
   
Note also that stm32mp15 expects tool '''tee-supplicant''' to be located in directory '''/usr/bin''' whereas CMake installs it in directory '''/usr/sbin'''. To overcome this issue, one can build a link to the effective location, i.e:
+
Note also that stm32mp1 expects tool '''tee-supplicant''' to be located in directory '''/usr/bin''' whereas CMake installs it in directory '''/usr/sbin'''. To overcome this issue, one can build a link to the effective location, i.e:
   
 
  {{PC$}} ln -s ../bin/tee-supplicant target/sbin/tee-supplicant
 
  {{PC$}} ln -s ../bin/tee-supplicant target/sbin/tee-supplicant
Line 226: Line 242:
 
      └── tee-supplicant -> ../bin/tee-supplicant
 
      └── tee-supplicant -> ../bin/tee-supplicant
   
== Update software on board ==
+
== Update OP-TEE boot images ==
  +
 
  +
OP-TEE OS boot images are included in the [[link to FIP|FIP binary]] loaded by the [[STM32MP15_TF-A|TF-A BL2 FSBL]].<br>
  +
[[link to FIP|FIP binary]] package must be created or updated following [[FIP|these instructions]].
   
The OP-TEE OS boot images shall be loaded into the related partitions of the boot media.<br>
+
== Update OP-TEE Linux files ==
  +
== Update on board ==
 
The other OP-TEE images are stored in the target filesystem.<br>
 
The other OP-TEE images are stored in the target filesystem.<br>
   
For example, if using an SD card as target boot media, the card can be plugged in its PC card reader and the images copied. OP-TEE core boot images can be loaded using tool '''dd''' while other files can be simply copied into the mounted rootfs.
+
For example, if using an SD card as target boot media, the card can be plugged in its PC card reader and the images copied.
 
+
The files can be simply copied into the mounted rootfs.
=== Update OP-TEE Core Boot Partitions in an SD card ===
 
   
If booting the target from an SD card, the core OP-TEE firmware can be updated using the tool '''dd'''.<br>
+
=== Update in a SD card ===
Plug the SD card into the computer slot reader and copy the binary to the dedicated partition; on an SDCard/USB disk the OP-TEE OS boot partitions are partition 4 to 6.
 
 
 
The target partition is located from the partition labels of the SD card, i.e:
 
{{PC$}} ls -l /dev/disk/by-partlabel/
 
total 0
 
lrwxrwxrwx 1 root root 10 Jan 28 16:35 bootfs -> ../../sdd7        (Linux kernel boot filesystem)
 
lrwxrwxrwx 1 root root 10 Jan 28 16:35 fsbl1 -> ../../sdd1        (part#1 is TF-A)
 
lrwxrwxrwx 1 root root 10 Jan 28 16:35 fsbl2 -> ../../sdd2        (part#2 is TF-A backup)
 
lrwxrwxrwx 1 root root 10 Jan 28 16:35 rootfs -> ../../sdd9        (Linux kernel root filesystem)
 
lrwxrwxrwx 1 root root 10 Jan 28 16:35 ssbl -> ../../sdd3          (part#3# is U-Boot)
 
lrwxrwxrwx 1 root root 10 Jan 28 16:35 teed -> ../../sdd5          (OP-TEE OS paged data)
 
lrwxrwxrwx 1 root root 10 Jan 28 16:35 teeh -> ../../sdd4          (OP-TEE OS header image)
 
lrwxrwxrwx 1 root root 10 Jan 28 16:35 teex -> ../../sdd6          (OP-TEE OS resident core)
 
lrwxrwxrwx 1 root root 11 Jan 28 16:35 userfs -> ../../sdd10      (Linux kernel user filesystem)
 
lrwxrwxrwx 1 root root 10 Jan 28 16:35 vendorfs -> ../../sdd8      (Linux kernel vendor filesystem)
 
 
 
For the SD card described above, the 3 OP-TEE core images can then be updated with:
 
{{PC$}} dd conv=fdatasync of=/dev/sdd4 if=<optee-os>/out/core/tee-header_v2.stm32
 
{{PC$}} dd conv=fdatasync of=/dev/sdd5 if=<optee-os>/out/core/tee-pageable_v2.stm32
 
{{PC$}} dd conv=fdatasync of=/dev/sdd6 if=<optee-os>/out/core/tee-pager_v2.stm32
 
 
 
=== Update OP-TEE Linux Files in a SD card ===
 
 
The OP-TEE files that need to be copied to the target filesystem were installed in a local directory '''./target/'''.
 
The OP-TEE files that need to be copied to the target filesystem were installed in a local directory '''./target/'''.
   
Line 263: Line 260:
 
  {{PC$}} cp -ar target/* /media/$USERNAME/rootfs/
 
  {{PC$}} cp -ar target/* /media/$USERNAME/rootfs/
   
=== Update via USB mass storage on U-boot ===
+
== Update your boot device (including SD card on the target) ==
See [[How to use USB mass storage in U-Boot]] and follow the previous sections to
 
load binary files '''tee-*_v2.stm32''' onto target partitions.
 
 
 
=== Update your boot device (including SD card on the target) ===
 
 
Refer to the [[STM32CubeProgrammer]] documentation to update your target.
 
Refer to the [[STM32CubeProgrammer]] documentation to update your target.