BSP Porting
===========

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

Introduction
~~~~~~~~~~~~

The Apache Mynewt core repo contains support for several different boards. For each supported board, there is a Board
Support Package (BSP) package in the ``hw/bsp`` directory. If there isn't a BSP package for your hardware, then you will need to make one
yourself. This document describes the process of creating a BSP package from scratch.

While creating your BSP package, the following documents will probably come in handy:

-  The datasheet for the MCU you have chosen.
-  The schematic of your board.
-  The information on the CPU core within your MCU if it is not included in your MCU documentation.

This document is applicable to any hardware, but it will often make reference to a specific board as an example. Our
example BSP has the following properties:

-  **Name:** ``hw/bsp/myboard``
-  **MCU:** Nordic nRF52

Download the BSP package template
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

We start by downloading a BSP package template. This template will serve as a good starting point for our new BSP.

Execute the ``newt pkg new`` command, as below:

.. code-block:: console

    $ newt pkg new -t bsp hw/bsp/myboard
    Download package template for package type bsp.
    Package successfuly installed into /home/me/myproj/hw/bsp/myboard.

Our new package has the following file structure:

.. code-block:: console

    $ tree hw/bsp/myboard
    hw/bsp/myboard
    ├── README.md
    ├── boot-myboard.ld
    ├── bsp.yml
    ├── include
    │   └── myboard
    │       └── bsp.h
    ├── myboard.ld
    ├── myboard_debug.sh
    ├── myboard_download.sh
    ├── pkg.yml
    ├── src
    │   ├── hal_bsp.c
    │   └── sbrk.c
    └── syscfg.yml

    3 directories, 11 files

We will be adding to this package throughout the remainder of this document. See `Appendix A: BSP files`_ for a full
list of files typically found in a BSP package.

Create a set of Mynewt targets
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

We'll need two :ref:`targets <mynewt-target>` to test our BSP as we go:

1. Boot loader
2. Application

A minimal application is best, since we are just interested in getting the BSP up and running. A good app for our
purposes is :doc:`blinky <../../../tutorials/blinky/blinky>`.

We create our targets with the following set of newt commands:

::

    newt target create boot-myboard &&
    newt target set boot-myboard app=@apache-mynewt-core/apps/boot  \
                                 bsp=hw/bsp/myboard                 \
                                 build_profile=optimized

    newt target create blinky-myboard &&
    newt target set blinky-myboard app=apps/blinky      \
                                   bsp=hw/bsp/myboard   \
                                   build_profile=debug

Which generates the following output:

::

    Target targets/boot-myboard successfully created
    Target targets/boot-myboard successfully set target.app to @apache-mynewt-core/apps/boot
    Target targets/boot-myboard successfully set target.bsp to hw/bsp/myboard
    Target targets/boot-myboard successfully set target.build_profile to debug
    Target targets/blinky-myboard successfully created
    Target targets/blinky-myboard successfully set target.app to apps/blinky
    Target targets/blinky-myboard successfully set target.bsp to hw/bsp/myboard
    Target targets/blinky-myboard successfully set target.build_profile to debug

Fill in the ``bsp.yml`` file
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The template ``hw/bsp/myboard/bsp.yml`` file is missing some values that need to be added. It also assumes certain
information that may not be appropriate for your BSP. We need to get this file into a usable state.

Missing fields are indicated by the presence of ``XXX`` markers. Here are the first several lines of our ``bsp.yml``
file where all the incomplete fields are located:

::

    bsp.arch: # XXX <MCU-architecture>
    bsp.compiler: # XXX <compiler-package>
    bsp.linkerscript:
        - 'hw/bsp/myboard/myboard.ld'
        # - XXX mcu-linker-script
    bsp.linkerscript.BOOT_LOADER.OVERWRITE:
        - 'hw/bsp/myboard/myboard/boot-myboard.ld'
        # - XXX mcu-linker-script

So we need to specify the following:

-  MCU architecture
-  Compiler package
-  MCU linker script

Our example BSP uses an nRF52 MCU, which implements the ``cortex_m4`` architecture. We use this information to fill in
the incomplete fields:

.. code-block:: yaml
   :emphasize-lines: 1, 2, 5, 8

    bsp.arch: cortex_m4
    bsp.compiler: '@apache-mynewt-core/compiler/arm-none-eabi-m4'
    bsp.linkerscript:
        - 'hw/bsp/myboard/myboard.ld'
        - '@apache-mynewt-core/hw/mcu/nordic/nrf52xxx/nrf52.ld'
    bsp.linkerscript.BOOT_LOADER.OVERWRITE:
        - 'hw/bsp/myboard/boot-myboard.ld'
        - '@apache-mynewt-core/hw/mcu/nordic/nrf52xxx/nrf52.ld'

Naturally, these values must be adjusted accordingly for other MCU types.

Flash map
~~~~~~~~~

At the bottom of the ``bsp.yml`` file is the flash map. The flash map partitions the BSP's flash memory into sections
called areas. Flash areas are further categorized into two types: 1) system areas, and 2) user areas. These two area
types are defined below.

**System areas**

-  Used by Mynewt core components.
-  BSP support is mandatory in most cases.
-  Use reserved names.

**User areas**

-  Used by application code and supplementary libraries.
-  Identified by user-assigned names.
-  Have unique user-assigned numeric identifiers for access by C code.

The flash map in the template ``bsp.yml`` file is suitable for an MCU with 512kB of internal flash. You may need to
adjust the area offsets and sizes if your BSP does not have 512kB of internal flash.

The system flash areas are briefly described below:

+--------------------------------+---------------------------------------------------------+
| Flash area                     | Description                                             |
+================================+=========================================================+
| ``FLASH_AREA_BOOTLOADER``      | Contains the Mynewt boot loader.                        |
+--------------------------------+---------------------------------------------------------+
| ``FLASH_AREA_IMAGE_0``         | Contains the active Mynewt application image.           |
+--------------------------------+---------------------------------------------------------+
| ``FLASH_AREA_IMAGE_1``         | Contains the secondary image; used for image upgrade.   |
+--------------------------------+---------------------------------------------------------+
| ``FLASH_AREA_IMAGE_SCRATCH``   | Used by the boot loader during image swap.              |
+--------------------------------+---------------------------------------------------------+

Add the MCU dependency to ``pkg.yml``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A package's dependencies are listed in its ``pkg.yml`` file. A BSP package always depends on its corresponding MCU
package, so let's add that dependency to our BSP now. The ``pkg.deps`` section of our ``hw/bsp/myboard/pkg.yml`` file
currently looks like this:

.. code-block:: yaml

    pkg.deps:
        # - XXX <MCU-package>
        - '@apache-mynewt-core/kernel/os'
        - '@apache-mynewt-core/libc/baselibc'

Continuing with our example nRF52 BSP, we replace the marked line as follows:

.. code-block:: yaml
   :emphasize-lines: 2

    pkg.deps:
        - '@apache-mynewt-core/hw/mcu/nordic/nrf52xxx'
        - '@apache-mynewt-core/kernel/os'
        - '@apache-mynewt-core/libc/baselibc'

Again, the particulars depend on the MCU that your BSP uses.

Check the BSP linker scripts
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Linker scripts are a key component of the BSP package. They specify how code and data are arranged in the MCU's memory.
Our BSP package contains two linker scripts:

+-----------------------+------------------------------------------------+
| **Filename**          | **Description**                                |
+=======================+================================================+
| ``myboard.ld``        | Linker script for Mynewt application images.   |
+-----------------------+------------------------------------------------+
| ``boot-myboard.ld``   | Linker script for the Mynewt boot loader.      |
+-----------------------+------------------------------------------------+

First, we will deal with the application linker script. You may have noticed that the ``bsp.linkerscript`` item in
``bsp.yml`` actually specifies two linker scripts:

-  BSP linker script (``hw/bsp/myboard.ld``)
-  MCU linker script (``@apache-mynewt-core/hw/mcu/nordic/nrf52xxx/nrf52.ld``)

Both linker scripts get used in combination when you build a Mynewt image. Typically, all the complexity is isolated to
the MCU linker script, while the BSP linker script just contains minimal size and offset information. This makes the job
of creating a BSPpackage much simpler.

Our ``myboard.ld`` file has the following contents:

.. code-block:: c

    MEMORY
    {
      FLASH (rx) : ORIGIN = 0x00008000, LENGTH = 0x3a000
      RAM (rwx) : ORIGIN = 0x20000000, LENGTH = 0x10000
    }

    /* This linker script is used for images and thus contains an image header */
    _imghdr_size = 0x20;

Our task is to ensure the offset (``ORIGIN``) and size (``LENGTH``) values are correct for the ``FLASH`` and ``RAM``
regions. Note that the ``FLASH`` region does not specify the board's entire internal flash; it only describes the area
of the flash dedicated to containing the running Mynewt image. The bounds of the ``FLASH`` region should match those of
the ``FLASH_AREA_IMAGE_0`` area in the BSP's flash map.

The ``_imghdr_size`` is always ``0x20``, so it can remain unchanged.

The second linker script, ``boot-myboard.ld``, is quite similar to the first. The important difference is the ``FLASH``
region: it describes the area of flash which contains the boot loader rather than an image. The bounds of this region
should match those of the ``FLASH_AREA_BOOTLOADER`` area in the BSP's flash map. For more information about the Mynewt
boot loader, see :doc:`this page <../../modules/bootloader/bootloader/>`.

Copy the download and debug scripts
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The newt command line tool uses a set of scripts to load and run Mynewt images. It is the BSP package that provides
these scripts.

As with the linker scripts, most of the work done by the download and debug scripts is isolated to the MCU package. The
BSP scripts are quite simple, and you can likely get away with just copying them from another BSP. The template
``myboard_debug.sh`` script indicates which BSP to copy from:

.. code-block:: bash

    #!/bin/sh

    # This script attaches a gdb session to a Mynewt image running on your BSP.

    # If your BSP uses JLink, a good example script to copy is:
    #     repos/apache-mynewt-core/hw/bsp/nrf52dk/nrf52dk_debug.sh
    #
    # If your BSP uses OpenOCD, a good example script to copy is:
    #     repos/apache-mynewt-core/hw/bsp/rb-nano2/rb-nano2_debug.sh

Our example nRF52 BSP uses JLink, so we will copy the nRF52dk BSP's scripts:

::

    cp repos/apache-mynewt-core/hw/bsp/nrf52dk/nrf52dk_debug.sh hw/bsp/myboard/myboard_debug.sh
    cp repos/apache-mynewt-core/hw/bsp/nrf52dk/nrf52dk_download.sh hw/bsp/myboard/myboard_download.sh

Fill in BSP functions and defines
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

There are a few particulars missing from the BSP's C code. These areas are marked with ``XXX`` comments to make them
easier to spot. The missing pieces are summarized in the table below:

+-------------------------+-------------------------------------------------------------------------------------------------+--------------------------------------------------------------+
| File                    | Description                                                                                     | Notes                                                        |
+=========================+=================================================================================================+==============================================================+
| ``src/hal_bsp.c``       | ``hal_bsp_flash_dev()`` needs to return a pointer to the MCU's flash object when ``id == 0``.   | The flash object is defined in MCU's ``hal_flash.c`` file.   |
+-------------------------+-------------------------------------------------------------------------------------------------+--------------------------------------------------------------+
| ``include/bsp/bsp.h``   | Define ``LED_BLINK_PIN`` to the pin number of the BSP's primary LED.                            | Required by the blinky application.                          |
+-------------------------+-------------------------------------------------------------------------------------------------+--------------------------------------------------------------+

For our nRF52 BSP, we modify these files as follows:

**src/hal\_bsp.c:**

.. code-block:: c
   :emphasize-lines: 1

    #include "mcu/nrf52_hal.h"

.. code-block:: c
   :emphasize-lines: 7

    const struct hal_flash *
    hal_bsp_flash_dev(uint8_t id)
    {
        switch (id) {
        case 0:
            /* MCU internal flash. */
            return &nrf52k_flash_dev;

        default:
            /* External flash.  Assume not present in this BSP. */
            return NULL;
        }
    }

**include/bsp/bsp.h:**

.. code-block:: c
   :emphasize-lines: 5

    #define RAM_SIZE        0x10000

    /* Put additional BSP definitions here. */

    #define LED_BLINK_PIN   17

Add startup code
~~~~~~~~~~~~~~~~

Now we need to add the BSP's assembly startup code. Among other things, this is the code that gets executed immediately
on power up, before the Mynewt OS is running. This code must perform a few basic tasks:

-  Assign labels to memory region boundaries.
-  Define some interrupt request handlers.
-  Define the ``Reset_Handler`` function, which:

   -  Zeroes the ``.bss`` section.
   -  Copies static data from the image to the ``.data`` section.
   -  Starts the Mynewt OS.

This file is named according to the following pattern: ``hw/bsp/myboard/src/arch/<ARCH>/gcc_startup_<MCU>.s``

The best approach for creating this file is to copy from other BSPs. If there is another BSP that uses the same MCU, you
might be able to use most or all of its startup file.

For our example BSP, we'll just copy the nRF52dk BSP's startup code:

.. code-block:: console

    $ mkdir -p hw/bsp/myboard/src/arch/cortex_m4
    $ cp repos/apache-mynewt-core/hw/bsp/nrf52dk/src/arch/cortex_m4/gcc_startup_nrf52.s hw/bsp/myboard/src/arch/cortex_m4/

Satisfy MCU requirements
~~~~~~~~~~~~~~~~~~~~~~~~

The MCU package probably requires some build-time configuration. Typically, it is the BSP which provides this configuration.
Completing this step will likely involve some trial and error as each unmet requirement gets reported as a build error.

Our example nRF52 BSP requires the following changes:

1.  Macro indicating MCU type. We add this to our BSP's ``pkg.yml`` file:

    .. code-block:: yaml
       :emphasize-lines: 2

        pkg.cflags:
            - '-DNRF52'

2.  Enable exactly one low-frequency timer setting in our BSP's ``syscfg.yml`` file. This is required by the nRF51 and nRF52 MCU packages:

    .. code-block:: yaml
       :emphasize-lines: 3

        # Settings this BSP overrides.
        syscfg.vals:
            XTAL_32768: 1

Test it
~~~~~~~

Now it's finally time to test the BSP package. Build and load your boot and blinky targets as follows:

.. code-block:: console

    $ newt build boot-myboard
    $ newt load boot-myboard
    $ newt run blinky-myboard 0

If everything is correct, the blinky app should successfully build, and you should be presented with a gdb prompt. Type
``c <enter>`` (continue) to see your board's LED blink.

Appendix A: BSP files
~~~~~~~~~~~~~~~~~~~~~

The table below lists the files required by all BSP packages. The naming scheme assumes a BSP called "myboard".

+---------------------------------------------+-----------------------------------------------------------------------+
| **File Path Name**                          | **Description**                                                       |
+=============================================+=======================================================================+
| ``pkg.yml``                                 | Defines a Mynewt package for the BSP.                                 |
+---------------------------------------------+-----------------------------------------------------------------------+
| ``bsp.yml``                                 | Defines BSP-specific settings.                                        |
+---------------------------------------------+-----------------------------------------------------------------------+
| ``include/bsp/bsp.h``                       | Contains additional BSP-specific settings.                            |
+---------------------------------------------+-----------------------------------------------------------------------+
| ``src/hal_bsp.c``                           | Contains code to initialize the BSP's peripherals.                    |
+---------------------------------------------+-----------------------------------------------------------------------+
| ``src/sbrk.c``                              | Low level heap management required by ``malloc()``.                   |
+---------------------------------------------+-----------------------------------------------------------------------+
| ``src/arch/<ARCH>/gcc_startup_myboard.s``   | Startup assembly code to bring up Mynewt                              |
+---------------------------------------------+-----------------------------------------------------------------------+
| ``myboard.ld``                              | A linker script providing the memory map for a Mynewt application.    |
+---------------------------------------------+-----------------------------------------------------------------------+
| ``boot-myboard.ld``                         | A linker script providing the memory map for the Mynewt bootloader.   |
+---------------------------------------------+-----------------------------------------------------------------------+
| ``myboard_download.sh``                     | A bash script to download code onto your platform.                    |
+---------------------------------------------+-----------------------------------------------------------------------+
| ``myboard_debug.sh``                        | A bash script to initiate a gdb session with your platform.           |
+---------------------------------------------+-----------------------------------------------------------------------+

A BSP can also contain the following optional files:

+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+
| **File Path Name**                                | **Description**                                                                                                          |
+===================================================+==========================================================================================================================+
| ``split-myboard.ld``                              | A linker script providing the memory map for the "application" half of a :doc:`split image <../../modules/split/split>`  |
+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+
| ``no-boot-myboard.ld``                            | A linker script providing the memory map for your bootloader                                                             |
+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+
| ``src/arch/<ARCH>/gcc_startup_myboard_split.s``   | Startup assembly code to bring up the "application" half of a :doc:`split image <../../modules/split/split>`.            |
+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+
| ``myboard_download.cmd``                          | An MSDOS batch file to download code onto your platform; required for Windows support.                                   |
+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+
| ``myboard_debug.cmd``                             | An MSDOS batch file to intiate a gdb session with your platform; required for Windows support.                           |
+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+