Google Git
Sign in
apache / mynewt-site / 8528acea806ecedcedbaec90568a1524b3ae623d / . / v1_3_0 / os / core_os / porting / port_bsp / index.html
blob: cdd10fa5dfa0a2c807e98f37a4d73706f091b028 [file] [log] [blame]
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<!-- This is broken by doc revisioning.
-->
<link rel="shortcut icon" href="../../../../img/favicon.ico">
<title>BSP Porting - Apache Mynewt</title>
<link href="../../../../css/bootstrap-3.0.3.min.css" rel="stylesheet">
<link rel="stylesheet" href="../../../../css/highlight.css">
<link href="../../../../css/base.css" rel="stylesheet">
<link href="../../../../css/custom.css" rel="stylesheet">
<link href="../../../../css/v2.css" rel="stylesheet">
<link href="https://fonts.googleapis.com/css?family=Lato" rel="stylesheet">
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/font-awesome/4.5.0/css/font-awesome.min.css">
<!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
<!--[if lt IE 9]>
<script src="https://oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
<script src="https://oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script>
<![endif]-->
<script>
(function(i, s, o, g, r, a, m) {
i["GoogleAnalyticsObject"] = r;
(i[r] =
i[r] ||
function() {
(i[r].q = i[r].q || []).push(arguments);
}),
(i[r].l = 1 * new Date());
(a = s.createElement(o)), (m = s.getElementsByTagName(o)[0]);
a.async = 1;
a.src = g;
m.parentNode.insertBefore(a, m);
})(window, document, "script", "//www.google-analytics.com/analytics.js", "ga");
ga("create", "UA-72162311-1", "auto");
ga("send", "pageview");
</script>
</head>
<body class="BSP Porting">
<div class="container">
<div class="row v2-main-banner">
<a class="logo-cell" href="/">
<img class="logo" src="/img/logo.png">
</a>
<div class="tagline-cell">
<h4 class="tagline">An OS to build, deploy and securely manage billions of devices</h4>
</div>
<div class="news-cell">
<div class="well">
<h4>Latest News:</h4> <a href="/download">Apache Mynewt 1.11.0, Apache NimBLE 1.6.0 </a> released (September 7, 2023)
</div>
</div>
</div>
</div>
<nav id="navbar" class="navbar navbar-inverse affix-top" data-spy="affix" data-offset-top="150" role="navigation">
<div class="container">
<!-- Collapsed navigation -->
<div class="navbar-header">
<!-- Expander button -->
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
</div>
<!-- Expanded navigation -->
<div class="navbar-collapse collapse">
<!-- Main navigation -->
<ul class="nav navbar-nav navbar-right">
<li
class=""
>
<a href="/"><i class="fa fa-home" style="font-size: larger;"></i></a>
</li>
<li
class="important"
>
<a href="/quick-start/">Quick Start</a>
</li>
<li
class=""
>
<a href="/about/">About</a>
</li>
<li
class=""
>
<a href="/talks/">Talks</a>
</li>
<li
class="active"
>
<a href="/documentation/">Documentation</a>
</li>
<li
class=""
>
<a href="/download/">Download</a>
</li>
<li
class=""
>
<a href="/community/">Community</a>
</li>
<li
class=""
>
<a href="/events/">Events</a>
</li>
</ul>
</div>
</div>
</nav>
<div class="container">
<div class="row">
<div class="col-md-3 v2-sidebar sidebar-container"><div id="docSidebar" class="hidden-print" role="complementary">
<div class="top">
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../../../../search.html" method="get">
<div class="form-group">
<input type="text" name="q" class="form-control" placeholder="Search documentation" />
</div>
</form>
</div>
</div>
<ul class="toc-nav">
<li class="doc-version"><select class="form-control" onchange="if (this.value) window.location.href=this.value">
<option value="/latest">
Version: master
</option>
<option value="/v1_11_0/" >
Version: 1.11.0
</option>
<option value="/v1_10_0/" >
Version: 1.10.0
</option>
<option value="/v1_9_0/" >
Version: 1.9.0
</option>
<option value="/v1_8_0/" >
Version: 1.8.0
</option>
<option value="/v1_7_0/" >
Version: 1.7.0
</option>
<option value="/v1_6_0/" >
Version: 1.6.0
</option>
<option value="/v1_5_0/" >
Version: 1.5.0
</option>
<option value="/v1_4_0/" >
Version: 1.4.0
</option>
<option value="/v1_3_0/os/introduction" selected="selected" >
Version: 1.3.0
</option>
<option value="/v1_2_0/os/introduction" >
Version: 1.2.0
</option>
<option value="/v1_1_0/os/introduction" >
Version: 1.1.0
</option>
<option value="/v1_0_0/os/introduction" >
Version: 1.0.0
</option>
<option value="/v0_9_0/os/introduction" >
Version: 0.9.0
</option>
</select></li>
<li ><a href="../../../introduction/">Mynewt Documentation</a>
<ul>
<li ><a href="../../../get_started/get_started/">Basic Setup</a>
</li>
<li >
<a href="../../../get_started/vocabulary/">Concepts</a>
</li>
<li ><a href="../../../tutorials/tutorials/">Tutorials</a>
</li>
<li ><a href="../../../os_user_guide/">OS User Guide</a>
<ul>
<li ><a href="../../mynewt_os/">OS Core</a>
</li>
<li ><a href="../port_os/">Porting to your Platform</a>
<ul>
<li class="active">
<a href="./">BSP Porting</a>
</li>
<li >
<a href="../port_mcu/">MCU Porting</a>
</li>
<li >
<a href="../port_cpu/">CPU Porting</a>
</li>
</ul>
</li>
<li ><a href="../../../modules/console/console/">Console</a>
</li>
<li ><a href="../../../modules/shell/shell/">Shell</a>
</li>
<li ><a href="../../../modules/split/split/">Split Images</a>
</li>
<li ><a href="../../../modules/bootloader/bootloader/">Bootloader</a>
</li>
<li><a href="
../../../modules/fs/fs/fs/
">File System</a>
</li>
<li ><a href="../../../modules/hal/hal/">Hardware Abstraction Layer</a>
</li>
<li ><a href="../../../modules/sensor_framework/sensor_framework_overview/">Sensor Framework</a>
</li>
<li ><a href="../../../modules/drivers/driver/">Drivers</a>
</li>
<li ><a href="../../../modules/testutil/testutil/">Test Utilities</a>
</li>
<li ><a href="../../../modules/devmgmt/newtmgr/">Device Management with Newt Manager</a>
</li>
<li ><a href="../../../modules/imgmgr/imgmgr/">Image Manager</a>
</li>
<li >
<a href="../../../modules/baselibc/">Baselibc library</a>
</li>
<li ><a href="../../../modules/json/json/">JSON</a>
</li>
<li ><a href="../../../modules/fcb/fcb/">Flash Circular Buffer</a>
</li>
<li ><a href="../../../modules/stats/stats/">Stats</a>
</li>
<li ><a href="../../../modules/logs/logs/">Logs</a>
</li>
<li ><a href="../../../modules/sysinitconfig/sysinitconfig/">System Configuration And Initialization</a>
</li>
</ul>
</li>
<li><a href="
../../../../network/ble/ble_intro/
">BLE User Guide</a>
</li>
<li ><a href="../../../../newt/newt_intro/">Newt Tool Guide</a>
</li>
<li ><a href="../../../../newtmgr/overview/">Newt Manager Guide</a>
</li>
<li >
<a href="../../../../known_issues/">Known Issues</a>
</li>
</ul>
</li>
<li><a href="
../../../../newt/install/prev_releases/
">Appendix</a>
</li>
</ul>
</div></div>
<div class="col-md-9" role="main">
<div class="doc-header">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="/documentation/">Docs</a></li>
<li>&raquo; <a href="os/core_os/porting/port_os/">Porting to your Platform</a></li>
<li>&raquo; <a href="os/os_user_guide/">OS User Guide</a></li>
<li>&raquo; <a href="os/introduction/">Mynewt Documentation</a></li>
<li>&raquo; BSP Porting</li>
<li class="wy-breadcrumbs-aside">
<a href="https://github.com/apache/mynewt-site/blob/master/docs/os/core_os/porting/port_bsp.md"
class="icon icon-github"> Edit on GitHub</a>
</li>
</ul>
</div>
</div>
<div class="alert alert-warning">
<p>
Version 1.3.0 is not the most recent version of the Apache Mynewt
documentation. Click <a href="/latest">here</a> to read the latest
version.
</p>
</div>
<h1 id="bsp-porting">BSP Porting</h1>
<h3 id="introduction">Introduction</h3>
<p>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
<code>hw/bsp</code> 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.</p>
<p>While creating your BSP package, the following documents will probably come in handy:</p>
<ul>
<li>The datasheet for the MCU you have chosen.</li>
<li>The schematic of your board.</li>
<li>The information on the CPU core within your MCU if it is not included in your MCU documentation.</li>
</ul>
<p>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:</p>
<ul>
<li><strong>Name:</strong> <code>hw/bsp/myboard</code></li>
<li><strong>MCU:</strong> Nordic nRF52</li>
</ul>
<h3 id="download-the-bsp-package-template">Download the BSP package template</h3>
<p>We start by downloading a BSP package template. This template will serve as a good starting point for our new BSP.</p>
<p>Execute the <code>newt pkg new</code> command, as below:</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>$ 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.
</code></pre></div>
<p>Our new package has the following file structure:</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>$ 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
</code></pre></div>
<p>We will be adding to this package throughout the remainder of this document.
See <a href="#appendix-a-bsp-files">Appendix A</a> for a full list of files typically
found in a BSP package.</p>
<h3 id="create-a-set-of-mynewt-targets">Create a set of Mynewt targets</h3>
<p>We'll need two <a href="../../../../os/get_started/vocabulary/#target">targets</a> to test
our BSP as we go:</p>
<ol>
<li>Boot loader</li>
<li>Application</li>
</ol>
<p>A minimal application is best, since we are just interested in getting the BSP
up and running. A good app for our purposes is
<a href="../../tutorials/blinky">blinky</a>.</p>
<p>We create our targets with the following set of newt commands:</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>newt target create boot-myboard &amp;&amp;
newt target set boot-myboard app=@apache-mynewt-core/apps/boot \
bsp=hw/bsp/myboard \
build_profile=optimized
newt target create blinky-myboard &amp;&amp;
newt target set blinky-myboard app=apps/blinky \
bsp=hw/bsp/myboard \
build_profile=debug
</code></pre></div>
<p>Which generates the following output:</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>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 optimized
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
</code></pre></div>
<h3 id="fill-in-the-bspyml-file">Fill in the <code>bsp.yml</code> file</h3>
<p>The template <code>hw/bsp/myboard/bsp.yml</code> 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.</p>
<p>Missing fields are indicated by the presence of <code>XXX</code> markers. Here are the
first several lines of our <code>bsp.yml</code> file where all the incomplete fields are
located:</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>bsp.arch: # XXX &lt;MCU-architecture&gt;
bsp.compiler: # XXX &lt;compiler-package&gt;
bsp.linkerscript:
- &#39;hw/bsp/myboard/myboard.ld&#39;
# - XXX mcu-linker-script
bsp.linkerscript.BOOT_LOADER.OVERWRITE:
- &#39;hw/bsp/myboard/myboard/boot-myboard.ld&#39;
# - XXX mcu-linker-script
</code></pre></div>
<p>So we need to specify the following:</p>
<ul>
<li>MCU architecture</li>
<li>Compiler package</li>
<li>MCU linker script</li>
</ul>
<p>Our example BSP uses an nRF52 MCU, which implements the <code>cortex_m4</code>
architecture. We use this information to fill in the incomplete fields:</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code><span style="background-color: #ffffcc">bsp.arch: cortex_m4
</span><span style="background-color: #ffffcc">bsp.compiler: &#39;@apache-mynewt-core/compiler/arm-none-eabi-m4&#39;
</span>bsp.linkerscript:
- &#39;hw/bsp/myboard/myboard.ld&#39;
<span style="background-color: #ffffcc"> - &#39;@apache-mynewt-core/hw/mcu/nordic/nrf52xxx/nrf52.ld&#39;
</span>bsp.linkerscript.BOOT_LOADER.OVERWRITE:
- &#39;hw/bsp/myboard/boot-myboard.ld&#39;
<span style="background-color: #ffffcc"> - &#39;@apache-mynewt-core/hw/mcu/nordic/nrf52xxx/nrf52.ld&#39;
</span></code></pre></div>
<p>Naturally, these values must be adjusted accordingly for other MCU types.</p>
<h3 id="flash-map">Flash map</h3>
<p>At the bottom of the <code>bsp.yml</code> 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.</p>
<p><strong>System areas</strong></p>
<ul>
<li>Used by Mynewt core components.</li>
<li>BSP support is mandatory in most cases.</li>
<li>Use reserved names.</li>
</ul>
<p><strong>User areas</strong></p>
<ul>
<li>Used by application code and supplementary libraries.</li>
<li>Identified by user-assigned names.</li>
<li>Have unique user-assigned numeric identifiers for access by C code.</li>
</ul>
<p>The flash map in the template <code>bsp.yml</code> 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.</p>
<p>The system flash areas are briefly described below:</p>
<table>
<thead>
<tr>
<th>Flash area</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>FLASH_AREA_BOOTLOADER</code></td>
<td>Contains the Mynewt boot loader.</td>
</tr>
<tr>
<td><code>FLASH_AREA_IMAGE_0</code></td>
<td>Contains the active Mynewt application image.</td>
</tr>
<tr>
<td><code>FLASH_AREA_IMAGE_1</code></td>
<td>Contains the secondary image; used for image upgrade.</td>
</tr>
<tr>
<td><code>FLASH_AREA_IMAGE_SCRATCH</code></td>
<td>Used by the boot loader during image swap.</td>
</tr>
</tbody>
</table>
<h3 id="add-the-mcu-dependency-to-pkgyml">Add the MCU dependency to <code>pkg.yml</code></h3>
<p>A package's dependencies are listed in its <code>pkg.yml</code> file. A BSP package
always depends on its corresponding MCU package, so let's add that dependency
to our BSP now. The <code>pkg.deps</code> section of our <code>hw/bsp/myboard/pkg.yml</code> file
currently looks like this:</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>pkg.deps:
# - XXX &lt;MCU-package&gt;
- &#39;@apache-mynewt-core/kernel/os&#39;
- &#39;@apache-mynewt-core/libc/baselibc&#39;
</code></pre></div>
<p>Continuing with our example nRF52 BSP, we replace the marked line as follows:</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>pkg.deps:
<span style="background-color: #ffffcc"> - &#39;@apache-mynewt-core/hw/mcu/nordic/nrf52xxx&#39;
</span> - &#39;@apache-mynewt-core/kernel/os&#39;
- &#39;@apache-mynewt-core/libc/baselibc&#39;
</code></pre></div>
<p>Again, the particulars depend on the MCU that your BSP uses.</p>
<h3 id="check-the-bsp-linker-scripts">Check the BSP linker scripts</h3>
<p>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:</p>
<table>
<thead>
<tr>
<th><strong>Filename</strong></th>
<th><strong>Description</strong></th>
</tr>
</thead>
<tbody>
<tr>
<td><code>myboard.ld</code></td>
<td>Linker script for Mynewt application images.</td>
</tr>
<tr>
<td><code>boot-myboard.ld</code></td>
<td>Linker script for the Mynewt boot loader.</td>
</tr>
</tbody>
</table>
<p>First, we will deal with the application linker script. You may have noticed
that the <code>bsp.linkerscript</code> item in <code>bsp.yml</code> actually specifies two linker
scripts:</p>
<ul>
<li>BSP linker script (<code>hw/bsp/myboard.ld</code>)</li>
<li>MCU linker script (<code>@apache-mynewt-core/hw/mcu/nordic/nrf52xxx/nrf52.ld</code>)</li>
</ul>
<p>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 BSP package much simpler.</p>
<p>Our <code>myboard.ld</code> file has the following contents:</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>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;
</code></pre></div>
<p>Our task is to ensure the offset (<code>ORIGIN</code>) and size (<code>LENGTH</code>) values are
correct for the <code>FLASH</code> and <code>RAM</code> regions. Note that the <code>FLASH</code> 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
<code>FLASH</code> region should match those of the <code>FLASH_AREA_IMAGE_0</code> area in the BSP's
flash map.</p>
<p>The <code>_imghdr_size</code> is always <code>0x20</code>, so it can remain unchanged.</p>
<p>The second linker script, <code>boot-myboard.ld</code>, is quite similar to the first.
The important difference is the <code>FLASH</code> 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 <code>FLASH_AREA_BOOTLOADER</code> area in the BSP's flash map.
For more information about the Mynewt boot loader, see
<a href="../../modules/bootloader/bootloader/">this page</a>.</p>
<h3 id="copy-the-download-and-debug-scripts">Copy the download and debug scripts</h3>
<p>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.</p>
<p>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
<code>myboard_debug.sh</code> script indicates which BSP to copy from:</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>#!/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
</code></pre></div>
<p>Our example nRF52 BSP uses JLink, so we will copy the nRF52dk BSP's scripts:</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>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
</code></pre></div>
<h3 id="fill-in-bsp-functions-and-defines">Fill in BSP functions and defines</h3>
<p>There are a few particulars missing from the BSP's C code. These areas are marked with <code>XXX</code> comments to make them easier to spot. The missing pieces are summarized in the table below:</p>
<table>
<thead>
<tr>
<th>File</th>
<th>Description</th>
<th>Notes</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>src/hal_bsp.c</code></td>
<td><code>hal_bsp_flash_dev()</code> needs to return a pointer to the MCU's flash object when <code>id == 0</code>.</td>
<td>The flash object is defined in MCU's <code>hal_flash.c</code> file.</td>
</tr>
<tr>
<td><code>include/bsp/bsp.h</code></td>
<td>Define <code>LED_BLINK_PIN</code> to the pin number of the BSP's primary LED.</td>
<td>Required by the blinky application.</td>
</tr>
</tbody>
</table>
<p>For our nRF52 BSP, we modify these files as follows:</p>
<p><strong>src/hal_bsp.c:</strong></p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code><span style="background-color: #ffffcc">#include &quot;mcu/nrf52_hal.h&quot;
</span></code></pre></div>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>const struct hal_flash *
hal_bsp_flash_dev(uint8_t id)
{
switch (id) {
case 0:
/* MCU internal flash. */
<span style="background-color: #ffffcc"> return &amp;nrf52k_flash_dev;
</span>
default:
/* External flash. Assume not present in this BSP. */
return NULL;
}
}
</code></pre></div>
<p><strong>include/bsp/bsp.h:</strong></p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>#define RAM_SIZE 0x10000
/* Put additional BSP definitions here. */
<span style="background-color: #ffffcc">#define LED_BLINK_PIN 17
</span></code></pre></div>
<h3 id="add-startup-code">Add startup code</h3>
<p>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:</p>
<ul>
<li>Assign labels to memory region boundaries.</li>
<li>Define some interrupt request handlers.</li>
<li>Define the <code>Reset_Handler</code> function, which:<ul>
<li>Zeroes the <code>.bss</code> section.</li>
<li>Copies static data from the image to the <code>.data</code> section.</li>
<li>Starts the Mynewt OS.</li>
</ul>
</li>
</ul>
<p>This file is named according to the following pattern:
<code>hw/bsp/myboard/src/arch/&lt;ARCH&gt;/gcc_startup_&lt;MCU&gt;.s</code></p>
<p>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.</p>
<p>For our example BSP, we'll just copy the nRF52dk BSP's startup code:</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>$ 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/
</code></pre></div>
<h3 id="satisfy-mcu-requirements">Satisfy MCU requirements</h3>
<p>The MCU package probably requires some build-time configuration. Typically, it
is the BSP which provides this configuration. For example, many MCU packages
depend on the <code>cmsis-core</code> package, which expects the BSP to provide a header
file called <code>bsp/cmsis_nvic.h</code>. Completing this step will likely involve some
trial and error as each unmet requirement gets reported as a build error.</p>
<p>Our example nRF52 BSP requires the following changes:</p>
<p><em>1)</em> The nRF52 MCU package uses <code>cmsis-core</code>, so for our example we will copy
the nRF52dk BSP's <code>cmsis_nvic.h</code> file to our BSP:</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>$ cp repos/apache-mynewt-core/hw/bsp/nrf52dk/include/bsp/cmsis_nvic.h hw/bsp/myboard/include/bsp/
</code></pre></div>
<p><em>2)</em> Macro indicating MCU type. We add this to our BSP's <code>pkg.yml</code> file:</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>pkg.cflags:
<span style="background-color: #ffffcc"> - &#39;-DNRF52&#39;
</span></code></pre></div>
<p><em>3)</em> Enable exactly one low-frequency timer setting in our BSP's <code>syscfg.yml</code>
file. This is required by the nRF51 and nRF52 MCU packages:</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code># Settings this BSP overrides.
syscfg.vals:
<span style="background-color: #ffffcc"> XTAL_32768: 1
</span></code></pre></div>
<h3 id="test-it">Test it</h3>
<p>Now it's finally time to test the BSP package. Build and load your boot and blinky targets as follows:</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>$ newt build boot-myboard
$ newt load boot-myboard
$ newt run blinky-myboard 0
</code></pre></div>
<p>If everything is correct, the blinky app should successfully build, and you should be presented with a gdb prompt. Type <code>c &lt;enter&gt;</code> (continue) to see your board's LED blink.</p>
<h3 id="appendix-a-bsp-files">Appendix A: BSP files</h3>
<p>The table below lists the files required by all BSP packages. The naming scheme assumes a BSP called "myboard".</p>
<table>
<thead>
<tr>
<th><strong>File Path Name</strong></th>
<th><strong>Description</strong></th>
</tr>
</thead>
<tbody>
<tr>
<td><code>pkg.yml</code></td>
<td>Defines a Mynewt package for the BSP.</td>
</tr>
<tr>
<td><code>bsp.yml</code></td>
<td>Defines BSP-specific settings.</td>
</tr>
<tr>
<td><code>include/bsp/bsp.h</code></td>
<td>Contains additional BSP-specific settings.</td>
</tr>
<tr>
<td><code>src/hal_bsp.c</code></td>
<td>Contains code to initialize the BSP's peripherals.</td>
</tr>
<tr>
<td><code>src/sbrk.c</code></td>
<td>Low level heap management required by <code>malloc()</code>.</td>
</tr>
<tr>
<td><code>src/arch/&lt;ARCH&gt;/gcc_startup_myboard.s</code></td>
<td>Startup assembly code to bring up Mynewt</td>
</tr>
<tr>
<td><code>myboard.ld</code></td>
<td>A linker script providing the memory map for a Mynewt application.</td>
</tr>
<tr>
<td><code>boot-myboard.ld</code></td>
<td>A linker script providing the memory map for the Mynewt bootloader.</td>
</tr>
<tr>
<td><code>myboard_download.sh</code></td>
<td>A bash script to download code onto your platform.</td>
</tr>
<tr>
<td><code>myboard_debug.sh</code></td>
<td>A bash script to initiate a gdb session with your platform.</td>
</tr>
</tbody>
</table>
<p>A BSP can also contain the following optional files:</p>
<table>
<thead>
<tr>
<th><strong>File Path Name</strong></th>
<th><strong>Description</strong></th>
</tr>
</thead>
<tbody>
<tr>
<td><code>split-myboard.ld</code></td>
<td>A linker script providing the memory map for the "application" half of a <a href="../../modules/split/split/">split image</a>.</td>
</tr>
<tr>
<td><code>no-boot-myboard.ld</code></td>
<td>A linker script providing the memory map for your bootloader</td>
</tr>
<tr>
<td><code>src/arch/&lt;ARCH&gt;/gcc_startup_myboard_split.s</code></td>
<td>Startup assembly code to bring up the "application" half of a <a href="../../modules/split/split/">split image</a>.</td>
</tr>
<tr>
<td><code>myboard_download.cmd</code></td>
<td>An MSDOS batch file to download code onto your platform; required for Windows support.</td>
</tr>
<tr>
<td><code>myboard_debug.cmd</code></td>
<td>An MSDOS batch file to intiate a gdb session with your platform; required for Windows support.</td>
</tr>
</tbody>
</table>
<div class="row">
<ul class="nav nav-pills" style="margin-bottom: 10px">
<li>
</li>
<li class="pull-right">
</li>
</ul>
</div>
<footer class="row">
<div class="col-xs-12">
<p class="copyright">Apache Mynewt is available under Apache License, version 2.0.</p>
</div>
<div class="col-xs-12">
<div class="logos">
<a href="https://www.apache.org/">
<img src="/img/asf_logo_wide_small.png" alt="Apache" title="Apache">
</a>
<p>
Copyright © 2015-2021 The Apache Software Foundation.<br>
<small class="footnote">
Apache Mynewt, Mynewt, Apache, the Apache feather logo, and the Apache Mynewt
project logo are either registered trademarks or trademarks of the Apache
Software Foundation in the United States and other countries.
</small>
</p>
<a href="">
<img src="https://www.countit.com/images/add_to_slack.png" alt="Slack Icon" title="Join our Slack Community" />
</a>
</div>
</div>
<a href="https://www.apache.org/licenses/">
<button class="button-footer-asf">
License
</button>
</a>
<a href="https://www.apache.org/foundation/sponsorship.html">
<button class="button-footer-asf">
Sponsorship
</button>
</a>
<a href="https://www.apache.org/foundation/thanks.html">
<button class="button-footer-asf">
Thanks
</button>
</a>
<a href="https://www.apache.org/security/">
<button class="button-footer-asf">
Security
</button>
</a>
<a href="https://apache.org/events/current-event">
<button class="button-footer-asf">
ASF Events
</button>
</a>
</footer>
</div>
</div>
</div>
<script src="../../../../js/jquery-1.10.2.min.js"></script>
<script src="../../../../js/bootstrap-3.0.3.min.js"></script>
<script src="../../../../js/highlight.pack.js"></script>
<script src="../../../../js/base.js"></script>
<script src="../../../../js/custom.js"></script>
<script src="search/main.js"></script>
</body>
</html>