You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mynewt.apache.org by GitBox <gi...@apache.org> on 2018/01/27 05:52:54 UTC
[GitHub] aditihilbert closed pull request #775: docs: convert OS porting guide
aditihilbert closed pull request #775: docs: convert OS porting guide
URL: https://github.com/apache/mynewt-core/pull/775
This is a PR merged from a forked repository.
As GitHub hides the original diff on merge, it is displayed below for
the sake of provenance:
As this is a foreign pull request (from a fork), the diff is supplied
below (as it won't show otherwise due to GitHub magic):
diff --git a/docs/os/core_os/porting/port_bsp.rst b/docs/os/core_os/porting/port_bsp.rst
index 6e6ccdd05..10dbd630d 100644
--- a/docs/os/core_os/porting/port_bsp.rst
+++ b/docs/os/core_os/porting/port_bsp.rst
@@ -1,26 +1,25 @@
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.
+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:
+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.
+- 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:
+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
@@ -28,12 +27,11 @@ following properties:
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.
+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.
@@ -41,7 +39,7 @@ Execute the ``newt pkg new`` command, as below:
Our new package has the following file structure:
-::
+.. code-block:: console
$ tree hw/bsp/myboard
hw/bsp/myboard
@@ -62,23 +60,19 @@ Our new package has the following file structure:
3 directories, 11 files
-We will be adding to this package throughout the remainder of this
-document. See `Appendix A <#appendix-a-bsp-files>`__ for a full list of
-files typically found in a BSP package.
+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
-`targets <../../../../os/get_started/vocabulary/#target>`__ to test our
-BSP as we go:
+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
-`blinky <../../tutorials/blinky>`__.
+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:
@@ -110,13 +104,11 @@ Which generates the following output:
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.
+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:
+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:
::
@@ -135,21 +127,29 @@ So we need to specify the following:
- 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:
+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
-``hl_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'``
+ 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.
+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.
+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**
@@ -163,9 +163,8 @@ user areas. These two area types are defined below.
- 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 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:
@@ -184,22 +183,21 @@ The system flash areas are briefly described below:
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:
+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:
+Continuing with our example nRF52 BSP, we replace the marked line as follows:
-.. code:: hl_lines="2"
+.. code-block:: yaml
+ :emphasize-lines: 2
pkg.deps:
- '@apache-mynewt-core/hw/mcu/nordic/nrf52xxx'
@@ -211,9 +209,8 @@ 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:
+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** |
@@ -223,23 +220,19 @@ two linker scripts:
| ``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:
+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``)
+- 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 BSP package much
-simpler.
+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
{
@@ -250,36 +243,29 @@ Our ``myboard.ld`` file has the following contents:
/* 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
+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 `this
-page <../../modules/bootloader/bootloader/>`__.
+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.
+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:
+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
@@ -291,8 +277,7 @@ copy from:
# 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:
+Our example nRF52 BSP uses JLink, so we will copy the nRF52dk BSP's scripts:
::
@@ -302,41 +287,28 @@ scripts:
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/h | ``hal_bsp_flas | The |
-| al_bsp. | h_dev()`` | flash |
-| c`` | needs to | object |
-| | return a | is |
-| | pointer to the | defined |
-| | MCU's flash | in MCU's |
-| | object when | ``hal_fl |
-| | ``id == 0``. | ash.c`` |
-| | | file. |
-+---------+----------------+----------+
-| ``inclu | Define | Required |
-| de/bsp/ | ``LED_BLINK_PI | by the |
-| bsp.h`` | N`` | blinky |
-| | to the pin | applicat |
-| | number of the | ion. |
-| | BSP's primary | |
-| | LED. | |
-+---------+----------------+----------+
+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:: hl_lines="1"
+.. code-block:: c
+ :emphasize-lines: 1
#include "mcu/nrf52_hal.h"
-.. code:: hl_lines="7"
+.. code-block:: c
+ :emphasize-lines: 7
const struct hal_flash *
hal_bsp_flash_dev(uint8_t id)
@@ -354,7 +326,8 @@ For our nRF52 BSP, we modify these files as follows:
**include/bsp/bsp.h:**
-.. code:: hl_lines="5"
+.. code-block:: c
+ :emphasize-lines: 5
#define RAM_SIZE 0x10000
@@ -365,9 +338,8 @@ For our nRF52 BSP, we modify these files as follows:
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:
+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.
@@ -377,16 +349,14 @@ Mynewt OS is running. This code must perform a few basic tasks:
- 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``
+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.
+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/
@@ -394,171 +364,91 @@ For our example BSP, we'll just copy the nRF52dk BSP's startup code:
Satisfy MCU requirements
~~~~~~~~~~~~~~~~~~~~~~~~
-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 ``cmsis-core`` package, which expects
-the BSP to provide a header file called ``bsp/cmsis_nvic.h``. Completing
-this step will likely involve some trial and error as each unmet
-requirement gets reported as a build error.
+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 ``cmsis-core`` package, which expects the BSP to provide a header file called
+``bsp/cmsis_nvic.h``. 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)* The nRF52 MCU package uses ``cmsis-core``, so for our example we
-will copy the nRF52dk BSP's ``cmsis_nvic.h`` file to our BSP:
+1. The nRF52 MCU package uses ``cmsis-core``, so for our example we will copy the nRF52dk BSP's ``cmsis_nvic.h`` file to our BSP:
-::
+ .. code-block:: console
- $ cp repos/apache-mynewt-core/hw/bsp/nrf52dk/include/bsp/cmsis_nvic.h hw/bsp/myboard/include/bsp/
+ $ cp repos/apache-mynewt-core/hw/bsp/nrf52dk/include/bsp/cmsis_nvic.h hw/bsp/myboard/include/bsp/
-*2)* Macro indicating MCU type. We add this to our BSP's ``pkg.yml``
-file:
+2. Macro indicating MCU type. We add this to our BSP's ``pkg.yml`` file:
-.. code:: hl_lines="2"
+ .. code-block:: yaml
+ :emphasize-lines: 2
- pkg.cflags:
- - '-DNRF52'
+ pkg.cflags:
+ - '-DNRF52'
-*3)* Enable exactly one low-frequency timer setting in our BSP's
-``syscfg.yml`` file. This is required by the nRF51 and nRF52 MCU
-packages:
+3. 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:: hl_lines="3"
+ .. code-block:: yaml
+ :emphasize-lines: 3
- # Settings this BSP overrides.
- syscfg.vals:
- XTAL_32768: 1
+ # 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:
+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.
+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 | **Description* |
-| Name** | * |
-+==============+================+
-| ``pkg.yml`` | Defines a |
-| | Mynewt package |
-| | for the BSP. |
-+--------------+----------------+
-| ``bsp.yml`` | Defines |
-| | BSP-specific |
-| | settings. |
-+--------------+----------------+
-| ``include/bs | Contains |
-| p/bsp.h`` | additional |
-| | BSP-specific |
-| | settings. |
-+--------------+----------------+
-| ``src/hal_bs | Contains code |
-| p.c`` | to initialize |
-| | the BSP's |
-| | peripherals. |
-+--------------+----------------+
-| ``src/sbrk.c | Low level heap |
-| `` | management |
-| | required by |
-| | ``malloc()``. |
-+--------------+----------------+
-| ``src/arch/< | Startup |
-| ARCH>/gcc_st | assembly code |
-| artup_myboar | to bring up |
-| d.s`` | Mynewt |
-+--------------+----------------+
-| ``myboard.ld | A linker |
-| `` | script |
-| | providing the |
-| | memory map for |
-| | a Mynewt |
-| | application. |
-+--------------+----------------+
-| ``boot-myboa | A linker |
-| rd.ld`` | script |
-| | providing the |
-| | memory map for |
-| | the Mynewt |
-| | bootloader. |
-+--------------+----------------+
-| ``myboard_do | A bash script |
-| wnload.sh`` | to download |
-| | code onto your |
-| | platform. |
-+--------------+----------------+
-| ``myboard_de | A bash script |
-| bug.sh`` | to initiate a |
-| | gdb session |
-| | with your |
-| | platform. |
-+--------------+----------------+
+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 | **Description* |
-| Name** | * |
-+==============+================+
-| ``split-mybo | A linker |
-| ard.ld`` | script |
-| | providing the |
-| | memory map for |
-| | the |
-| | "application" |
-| | half of a |
-| | `split |
-| | image <../../m |
-| | odules/split/s |
-| | plit/>`__. |
-+--------------+----------------+
-| ``no-boot-my | A linker |
-| board.ld`` | script |
-| | providing the |
-| | memory map for |
-| | your |
-| | bootloader |
-+--------------+----------------+
-| ``src/arch/< | Startup |
-| ARCH>/gcc_st | assembly code |
-| artup_myboar | to bring up |
-| d_split.s`` | the |
-| | "application" |
-| | half of a |
-| | `split |
-| | image <../../m |
-| | odules/split/s |
-| | plit/>`__. |
-+--------------+----------------+
-| ``myboard_do | An MSDOS batch |
-| wnload.cmd`` | file to |
-| | download code |
-| | onto your |
-| | platform; |
-| | required for |
-| | Windows |
-| | support. |
-+--------------+----------------+
-| ``myboard_de | An MSDOS batch |
-| bug.cmd`` | file to |
-| | intiate a gdb |
-| | session with |
-| | your platform; |
-| | required for |
-| | Windows |
-| | support. |
-+--------------+----------------+
++---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+
+| **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. |
++---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+
diff --git a/docs/os/core_os/porting/port_cpu.rst b/docs/os/core_os/porting/port_cpu.rst
index 2ab8e415b..0a6aa01a7 100644
--- a/docs/os/core_os/porting/port_cpu.rst
+++ b/docs/os/core_os/porting/port_cpu.rst
@@ -12,59 +12,32 @@ These are discussed below:
Create A New Compiler
~~~~~~~~~~~~~~~~~~~~~
-NOTE: Newt does not automatically install the compilers require to build
-all platforms. Its up to the user using their local machines package
-manager to install the compilers. The step described here just registers
-the compiler with newt.
-
-Create a new directory (named after the compiler you are adding). Copy
-the ``pkg.yml`` file from another compiler.
-
-Edit the ``pkg.yml`` file and change the configuration attributes to
-match your compiler. Most are self-explanatory paths to different
-compiler and linker tools. There are a few configuration attributes
-worth noting.
-
-+--------------+----------------+
-| **Configurat | **Description* |
-| ion | * |
-| Attributes** | |
-+==============+================+
-| pkg.keywords | Specific |
-| | keywords to |
-| | help others |
-| | search for |
-| | this using |
-| | newt |
-+--------------+----------------+
-| compiler.fla | default |
-| gs.default | compiler flags |
-| | for this |
-| | architecture |
-+--------------+----------------+
-| compiler.fla | additional |
-| gs.optimized | flags when the |
-| | newt tool |
-| | builds an |
-| | optimized |
-| | image |
-+--------------+----------------+
-| compiler.fla | additional |
-| gs.debug | flags when the |
-| | newt tool |
-| | builds a debug |
-| | image |
-+--------------+----------------+
+NOTE: Newt does not automatically install the compilers require to build all platforms. Its up to the user using their
+local machines package manager to install the compilers. The step described here just registers the compiler with newt.
+
+Create a new directory (named after the compiler you are adding). Copy the ``pkg.yml`` file from another compiler.
+
+Edit the ``pkg.yml`` file and change the configuration attributes to match your compiler. Most are self-explanatory
+paths to different compiler and linker tools. There are a few configuration attributes worth noting.
+
++--------------------------------+-----------------------------------------------------------------+
+| **Configuration Attributes** | **Description** |
++================================+=================================================================+
+| pkg.keywords | Specific keywords to help others search for this using newt |
++--------------------------------+-----------------------------------------------------------------+
+| compiler.flags.default | default compiler flags for this architecture |
++--------------------------------+-----------------------------------------------------------------+
+| compiler.flags.optimized | additional flags when the newt tool builds an optimized image |
++--------------------------------+-----------------------------------------------------------------+
+| compiler.flags.debug | additional flags when the newt tool builds a debug image |
++--------------------------------+-----------------------------------------------------------------+
Implement Architecture-specific OS code
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-There are several architecture-specific code functions that are required
-when implementing a new architecture. You can find examples in the
-``sim`` architecture within Mynewt.
+There are several architecture-specific code functions that are required when implementing a new architecture. You can
+find examples in the ``sim`` architecture within Mynewt.
-When porting to a new CPU architecture, use the existing architectures
-as samples when writing your implementation.
+When porting to a new CPU architecture, use the existing architectures as samples when writing your implementation.
-Please contact the Mynewt development list for help and advice portingto
-new MCU.
+Please contact the Mynewt development list for help and advice portingto new MCU.
diff --git a/docs/os/core_os/porting/port_mcu.rst b/docs/os/core_os/porting/port_mcu.rst
index eb7d4d19c..aac0962ca 100644
--- a/docs/os/core_os/porting/port_mcu.rst
+++ b/docs/os/core_os/porting/port_mcu.rst
@@ -20,7 +20,7 @@ To get started:
- Create a ``hw/mcu/mymcu/variant/pkg.yml`` file. Copy from another mcu
and fill out the relevant information
- Create
- ``hw/mcu/mymcu/variant/include``,\ ``hw/mcu/mymcu/variant/include/mcu``,
+ ``hw/mcu/mymcu/variant/include``, ``hw/mcu/mymcu/variant/include/mcu``,
and ``hw/mcu/mymcu/variant/src`` directories to contain the code for
your mcu.
diff --git a/docs/os/core_os/porting/port_os.rst b/docs/os/core_os/porting/port_os.rst
index 4a3da7561..406dd41fb 100644
--- a/docs/os/core_os/porting/port_os.rst
+++ b/docs/os/core_os/porting/port_os.rst
@@ -1,9 +1,20 @@
Porting Mynewt OS
=================
+.. toctree::
+ :hidden:
+
+ port_bsp
+ port_mcu
+ port_cpu
+
This chapter describes how to adapt the Mynewt OS to different
platforms.
+.. contents::
+ :local:
+ :depth: 2
+
Description
~~~~~~~~~~~
@@ -62,11 +73,10 @@ hardware layout of your system.
- If your BSP is already supported my Mynewt, there is no additional
BSP work involved in porting to your platform. You need only to set
- the ``bsp`` attribute in your Mynewt target using the `newt command
- tool <../../../../newt/newt_intro>`__.
+ the ``bsp`` attribute in your Mynewt target using the :doc:`newt command
+ tool <../../../newt/index>`.
- If your BSP is not yet supported by Mynewt, you can add support
- following the instructions on `how to add BSP support to
- Mynewt <port_bsp.html>`__
+ following the instructions on :doc:`port_bsp`.
MCU Dependency
~~~~~~~~~~~~~~
@@ -77,11 +87,10 @@ where code and data can reside.
- If your MCU is already supported my Mynewt, there is no additional
MCU work involved in porting to your platform. You need only to set
- the ``arch`` attribute in your Mynewt target using the `newt command
- tool <../../../../newt/newt_intro>`__.
+ the ``arch`` attribute in your Mynewt target using the :doc:`newt command
+ tool <../../../newt/index>`.
- If your MCU is not yet supported by Mynewt, you can add support
- following the instructions on\ `how to add MCU support to
- Mynewt <port_mcu.html>`__
+ following the instructions in :doc:`port_mcu`.
MCU HAL
~~~~~~~
@@ -91,7 +100,7 @@ common on or off-chip MCU peripherals such as GPIO, UARTs, flash memory
etc. Even if your MCU is supported for the core OS, you may find that
you need to implement the HAL functionality for a new peripheral. For a
description of the HAL abstraction and implementation information, see
-the `HAL API <../../modules/hal/hal.html>`__
+the :doc:`HAL API <../../modules/hal/hal>`
CPU Core Dependency
~~~~~~~~~~~~~~~~~~~
@@ -104,7 +113,6 @@ the appropriate instruction set.
- If your CPU architecture is already supported my Mynewt, there is no
CPU core work involved in porting to your platform. You need only to
set the ``arch`` and ``compiler`` attributes in your Mynewt target
- using the `newt command tool <../../../../newt/newt_intro>`__.
+ using the :doc:`newt command tool <../../../newt/index>`.
- If your CPU architecture is not supported by Mynewt, you can add
- support following the instructions on `how to add CPU architecture
- support to Mynewt <port_cpu.html>`__
+ support following the instructions on :doc:`port_cpu`.
diff --git a/docs/os/modules/hal/hal.rst b/docs/os/modules/hal/hal.rst
index f3974df97..a1cb41940 100644
--- a/docs/os/modules/hal/hal.rst
+++ b/docs/os/modules/hal/hal.rst
@@ -11,8 +11,7 @@ typically the software libraries that initialize the hardware and manage
access to the hardware by higher layers of software. In the Mynewt OS,
the layers can be depicted in the following manner.
-.. code-block:: console
-
+::
+???????????????????????????+
| app |
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
With regards,
Apache Git Services