.. _optee_with_rust:

################ 
OP-TEE with Rust
################

This document describes how to build OP-TEE client and trusted applications
written in `Rust <https://www.rust-lang.org>`_ with `Teaclave TrustZone SDK
<https://github.com/apache/incubator-teaclave-trustzone-sdk>`_.

Clone OP-TEE repo 
*****************

Currently, Teaclave TrustZone SDK is compatible with QEMUv8 (aarch64).

Before building examples written with Teaclave TrustZone SDK, you should 
clone the OP-TEE repo first. For QEMUv8, run:

.. code-block:: bash

    $ mkdir YOUR_OPTEE_DIR && cd YOUR_OPTEE_DIR
    $ repo init -u https://github.com/OP-TEE/manifest.git -m qemu_v8.xml 
    $ repo sync

The source code of Teaclave TrustZone SDK is located in 
``YOUR_OPTEE_DIR/optee_rust/`` containing a set of examples written in Rust
using the SDK.

For more information about building OP-TEE using QEMUv8, see `run OP-TEE using
QEMU
<https://optee.readthedocs.io/en/latest/building/devices/qemu.html#qemu-v8>`_ .

Compile Rust examples 
*********************

Rust example applications are located in ``optee_rust/examples/``. To build
and install them with Buildroot, run:

.. code-block:: bash

    $ (cd build && make toolchains && make OPTEE_RUST_ENABLE=y CFG_TEE_RAM_VA_SIZE=0x00300000)

Then start QEMUv8:

.. code-block:: bash

    $ (cd build && make run-only)

.. hint::

    Note that if you are under the environment without GUI, you can use
    ``soc_term`` instead.

    Access to normal world terminal:

    .. code-block:: bash

       $ ./build/soc_term.py 54320

    Access to secure world terminal:

    .. code-block:: bash

       $ ./build/soc_term.py 54321

    Run QEMU:

    .. code-block:: bash

       $ (cd build && make run-only)

To differentiate from client applications generated by `optee_examples
<https://optee.readthedocs.io/en/latest/building/gits/optee_examples/optee_examples.html#>`_
, OP-TEE Rust examples are not prefixed with ``optee_example_`` but suffixed with
``-rs``. More description about Rust examples can be found in `Overview of
OP-TEE Rust Examples
<https://teaclave.apache.org/trustzone-sdk-docs/overview-of-optee-rust-examples/>`_
.

During the build process, host applications are installed to ``/usr/bin/`` and
TAs are installed to ``/lib/optee_armtz/``. After QEMU boots up, you can run
host applications in normal world terminal. For example:

.. code-block:: bash

    $ hello_world-rs 
    original value is 29 
    inc value is 129 
    dec value is 29
    Success

TA log will be printed correspondingly in the secure terminal.

Development Documents
*********************

More information about developing OP-TEE applications in Rust can be found in
`Teaclave TrustZone SDK Documentation
<https://teaclave.apache.org/trustzone-sdk-docs/>`_.