..
  #
  # Copyright 2020 Casper Meijn <casper@meijn.net>
  #
  # Licensed under the Apache License, Version 2.0 (the "License");
  # you may not use this file except in compliance with the License.
  # You may obtain a copy of the License at
  #
  #     http://www.apache.org/licenses/LICENSE-2.0
  #
  # Unless required by applicable law or agreed to in writing, software
  # distributed under the License is distributed on an "AS IS" BASIS,
  # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  # See the License for the specific language governing permissions and
  # limitations under the License.
  #

Rust Blinky application
===========================================

This tutorial shows you how to convert the Blinky application to Rust. This includes 
integrating Cargo into newt builder.

.. contents::
  :local:
  :depth: 2

Prerequisites
~~~~~~~~~~~~~

Ensure that you meet the following prerequisites before continuing with
this tutorial:

- You have basic knowledge about `Rust <https://doc.rust-lang.org/stable/book/>`__.
- You have basic knowledge about `Rust Embedded <https://rust-embedded.github.io/book/>`__.
- You have rust installed using `rustup <https://doc.rust-lang.org/stable/book/ch01-01-installation.html>`__.
-  Follow :doc:`Blinky tutorial <../blinky/blinky>` to create a 
   project with a basic application. You will extend that application in this 
   tutorial.

Initialize Rust
~~~~~~~~~~~~~~~

The first step is to initialize a crate for developing your application in. You
can do this in the existing `blinky` directory. 

.. code-block:: console

        $ cargo init --lib apps/blinky
        Created library package
        $ tree apps/blinky
        apps/blinky
        ├── Cargo.toml
        ├── pkg.yml
        └── src
            ├── lib.rs
            └── main.c

        1 directory, 4 files

This creates a Cargo.toml configuration file and src/lib.rs. We will use these 
files to place our application in. You may notice that the Rust application is
not configured as an app, but as an lib. This is needed later to allow linking
to the rest of mynewt.

Setup the basics
~~~~~~~~~~~~~~~~

Now we want to actually convert the application code to Rust. Let's open `src/lib.rs`
and remove the contents. Then start with some basic setup:

.. code-block:: rust

    #![no_std]

    extern crate panic_halt;

    #[no_mangle]
    pub extern "C" fn main() {

        loop {
        }
    }

The first line states that this program doesn't use the standard library. This
means that only the core library is linked to the program. See 
`rust-embedded book <https://rust-embedded.github.io/book/intro/no-std.html>`__ 
for more information.

The next line specifies the panic handler. Panicking is an important feature of
Rust. To ease this tutorial we choose to halt the processor on panic. See 
`rust-embedded book <https://docs.rust-embedded.org/book/start/panicking.html>`__
for alternatives.

Then we have the ``main`` function. It contains a endless loop as it should never
return, but doesn't do anything useful yet. It is marked ``no_mangle`` and ``extern "C"``
to make sure it can be called from the mynewt C code.

Converting sysinit
~~~~~~~~~~~~~~~~~~

The next step is to do the sysinit. This is implemented as a C macro, which is
incompatible with Rust. This could be solved by using a C library, but for this
tutorial we will simply execute the macro manually.

.. code-block:: rust
    :emphasize-lines: 3-7, 13-16

    #![no_std]

    extern "C" {
        fn sysinit_start();
        fn sysinit_app();
        fn sysinit_end();
    }

    extern crate panic_halt;

    #[no_mangle]
    pub extern "C" fn main() {
        /* Initialize all packages. */
        unsafe { sysinit_start(); }
        unsafe { sysinit_app(); }
        unsafe { sysinit_end(); }

        loop {
        }
    }

First we manually define the three sysinit functions. This is similar to the
C header file. Then we execute the sysinit as the macro would do. 

We need the ``unsafe`` indication because the C code doesn't have the same memory
guarantees as Rust. Normally we need to build a safe Rust wrapper, but that is 
out of scope for this tutorial.

Doing GPIO and delays
~~~~~~~~~~~~~~~~~~~~~

Now it is time to do some GPIO and add a delay. Again we define the functions 
and then use them in and around the loop. We need some constants that are 
normally defined by the BSP or MCU. These constants need to move to a better 
place later.

.. code-block:: rust
    :emphasize-lines: 7-9, 14, 16, 25, 28-29, 31-32

    #![no_std]

    extern "C" {
        fn sysinit_start();
        fn sysinit_app();
        fn sysinit_end();
        fn hal_gpio_init_out(pin: i32, val: i32) -> i32;
        fn hal_gpio_toggle(pin: i32);
        fn os_time_delay(osticks: u32);
    }

    extern crate panic_halt;

    const OS_TICKS_PER_SEC: u32 = 128;

    const LED_BLINK_PIN: i32 = 23;

    #[no_mangle]
    pub extern "C" fn main() {
        /* Initialize all packages. */
        unsafe { sysinit_start(); }
        unsafe { sysinit_app(); }
        unsafe { sysinit_end(); }

        unsafe { hal_gpio_init_out(LED_BLINK_PIN, 1); }

        loop {
            /* Wait one second */
            unsafe { os_time_delay(OS_TICKS_PER_SEC); }

            /* Toggle the LED */
            unsafe { hal_gpio_toggle(LED_BLINK_PIN); }
        }
    }

Cargo build
~~~~~~~~~~~

Now that the application is converted we need to build it and link it the rest of mynewt. We start with Cargo.toml:

.. code-block:: toml
    :emphasize-lines: 7-8, 10-11

    [package]
    name = "rust-klok"
    version = "0.1.0"
    authors = ["Casper Meijn <casper@meijn.net>"]
    edition = "2018"

    [dependencies]
    panic-halt = "0.2.0"

    [lib]
    crate-type = ["staticlib"]

This adds the ``panic-halt`` dependency, which is needed for the panic handler as 
mentioned earlier. It also configures the crate as staticlib, which causes the
application to be build as .a-library. This will be needed in a later step.

Next we need a script for running ``cargo`` and moving the library to the correct 
place. Create a new file named ``apps/blinky/cargo_build.sh`` with the following contents:

.. code-block:: bash
    :emphasize-lines: 1-21

    #!/bin/bash

    set -eu

    if [[ ${MYNEWT_VAL_ARCH_NAME} == '"cortex_m0"' ]]; then
      TARGET="thumbv6m-none-eabi"
    elif [[ ${MYNEWT_VAL_ARCH_NAME} == '"cortex_m3"' ]]; then
      TARGET="thumbv7m-none-eabi"
    elif [[ ${MYNEWT_VAL_ARCH_NAME} == '"cortex_m4"' || ${MYNEWT_VAL_ARCH_NAME} == '"cortex_m7"' ]]; then
      if [[ $MYNEWT_VAL_HARDFLOAT -eq 1 ]]; then
        TARGET="thumbv7em-none-eabihf"
      else
        TARGET="thumbv7em-none-eabi"
      fi
    else
      echo "The ARCH_NAME ${MYNEWT_VAL_ARCH_NAME} is not supported"
      exit 1
    fi

    cargo build --target="${TARGET}" --target-dir="${MYNEWT_PKG_BIN_DIR}"
    cp "${MYNEWT_PKG_BIN_DIR}"/${TARGET}/debug/*.a "${MYNEWT_PKG_BIN_ARCHIVE}"

The script first sets the name of the target as the Rust compiler knows it. Sadly
this is not the same as the names mynewt uses. You need to choose the same type of
compiler as mynewt uses. The following targets are available depending on the
MCU type:

* ``thumbv6m-none-eabi`` - use this for Cortex-M0 and Cortex-M0+.
* ``thumbv7m-none-eabi`` - use this for Cortex-M3.
* ``thumbv7em-none-eabi`` - use this for Cortex-M4 and Cortex-M7.
* ``thumbv7em-none-eabihf`` - use this for Cortex-M4 and Cortex-M7 with the
  ``HARDFLOAT`` syscfg enabled.

Then it runs ``cargo build`` with
the target directory set to a path that ``newt`` provides. Lastly it copies the 
generated library to the correct path.

Don't forget to mark the script as executable: 

.. code-block:: console

    $ chmod +x apps/blinky/cargo_build.sh 

Newt integration
~~~~~~~~~~~~~~~~

To automatically run ``cargo`` we need to add the following to pkg.yml:

.. code-block:: yaml
    :emphasize-lines: 3-4, 5-7

    ...

    pkg.pre_build_cmds:
        './cargo_build.sh': 1

    pkg.lflags:
        - '-Wl,--allow-multiple-definition'

The first section tells the mynewt build system to run ``cargo_build.sh`` as part 
of ``newt build``. The second section tells the linker to ignore double function
definitions. This is needed as the Rust compiler adds some functions that are
also in baselibc.

Now we are ready to build a firmware! Remove ``main.c`` and start the build:

.. code-block:: console

    $ rm apps/blinky/src/main.c
    $ newt build nrf52_blinky

If this command complains about a target may not be installed, then you need to 
install it. You need the same toolchain as configured earlier for the ``TARGET``
variable:

.. code-block:: console

    $ rustup target add <your-target>

Conclusion
~~~~~~~~~~

You now have a firmware where the application is written in Rust. It is nicely 
integrated into newt builder. However it still needs some work: it misses safe
Rust wrappers for the mynewt libraries and there are some magic constants that
need to be moved to a better location.