You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mynewt.apache.org by ad...@apache.org on 2016/03/04 19:42:36 UTC
[1/2] incubator-mynewt-site git commit: documentation for arduino
blinky tutorial
Repository: incubator-mynewt-site
Updated Branches:
refs/heads/master 901aafcbe -> d668d1bdf
documentation for arduino blinky tutorial
Project: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/commit/c2bd198b
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/c2bd198b
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/c2bd198b
Branch: refs/heads/master
Commit: c2bd198bffdab7b9f279622bc9ea230ff17d4910
Parents: 8b5b99d
Author: Paul Dietrich <pa...@yahoo.com>
Authored: Thu Mar 3 12:29:19 2016 -0800
Committer: Paul Dietrich <pa...@yahoo.com>
Committed: Thu Mar 3 17:02:28 2016 -0800
----------------------------------------------------------------------
docs/os/core_os/porting/port_bsp.md | 296 ++++++++++++++++++++++++++++++-
docs/os/core_os/porting/port_cpu.md | 47 ++++-
docs/os/core_os/porting/port_mcu.md | 32 ++--
docs/os/core_os/porting/port_os.md | 2 +-
docs/os/tutorials/arduino_zero.md | 213 ++++++++++++++++++++++
5 files changed, 561 insertions(+), 29 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/c2bd198b/docs/os/core_os/porting/port_bsp.md
----------------------------------------------------------------------
diff --git a/docs/os/core_os/porting/port_bsp.md b/docs/os/core_os/porting/port_bsp.md
index e4cd048..8048dbd 100644
--- a/docs/os/core_os/porting/port_bsp.md
+++ b/docs/os/core_os/porting/port_bsp.md
@@ -1,19 +1,297 @@
-# Mynewt OS
+#Create a BSP for Your Target
-Insert introduction here
+## Introduction
-## Real-Time Kernel <Modify as you Wish>
+If you are using a board or system not currently supported by Mynewt, you will
+need to create a BSP for the new target. If another similar BSP exists it
+is recommended to copy that BSP as a starting point. For example, is another
+BSP exists using the same MCU, start with a copy of that BSP.
- Description
+Either way, this document will describes the steps necessary to create a new
+BSP from scratch.
-## Real-Time OS <Modify as you Wish>
+##Get Your Reference Documents Handy
- Description
+To build a proper BSP, you will typically need the following:
+* The datasheet for the MCU you have chosen
+* The schematic of your board
+* The information on the CPU core within your MCU if its not included in your
+MCU documentation
+* This Mynewt documentation
-## Insert topic of your choice
+##Name Your BSP
- Description
+Select a name for your BSP. For the remainder of this document,
+well assume the bsp is named `myboard`. In general its best to select a
+name that describes the board/system you are creating.
-## Features
+##Create a BSP Directory
+
+Create a directory `hw/bsp/myboard` using the name chosen above.
+Within this BSP directory, create the following subdirectories:
+
+* `include`
+* `include/bsp`
+* `src`
+
+##Create a Target using Mynewt
+
+Create a newt target for your test project for the BSP. To learn how to
+create a target, see this [Tutorial](../../get_started/project1). Once you are
+familiar with creating targets, move on below to create a target to use to
+test your BSP.
+
+Its recommended to use a simple `project` like `blinky` to minimize time to get a
+working Mynewt system. For this document, we will assume the `target` is called
+`myboard_blinky` and uses project `blinky`.
+
+Set the `bsp` of the project to `/hw/bsp/myboard`.
+While creating your target, you will need to specify your `arch`and `compiler`.
+If your platform requires an architecture or compiler that are not defined
+in Mynewt, you will need to add them first. To add a CPU architecture see
+[CPU Porting](port_cpu.md).
+
+When you are complete, your `target` may look similar to this.
+
+```no-highlight
+ $newt target show
+ myboard_blinky
+ arch=cortex_m0
+ bsp=hw/bsp/myboard
+ compiler=arm-none-eabi-m0
+ compiler_def=debug
+ name=myboard_blinky
+ project=blinky
+```
+
+##Create Required Files For Compilation
+
+Create the following files within the BSP directory tree. For now they can
+be empty files. We will fill them out one at a time.
+
+| **File Path Name** | **Description** |
+|-----------|-------------|
+| LICENSE | A File to present the source license for your BSP |
+| README.md | A markdown file to write documentation for your BSP |
+| pkg.yml | A package file to describe your BSP contents |
+| include/bsp/bsp.h | A header file to include definitions required by system from the BSP |
+| src/os_bsp.c | A C source file to provide functions required by the OS from your BSP |
+| src/sbrk.c | A C source file to memory from your heap to the OS |
+| src/libc_stubs.c | A C source file to provide stubs/methods required by libc |
+| myboard.ld | A linker script to provide the memory map for you linked code |
+
+Optionally create these files that will be necessary to provide all functionality
+from Mynewt.
+
+| **File Path Name** | **Description** |
+|-----------|-------------|
+| myboard_boot.ld | A linker script to provide the memory map for your bootloader |
+| myboard_download.sh | A bash script to download code into your platform |
+| myboard_debug.sh | A bash script to intiate a gdb session with your platform |
+| src/hal_bsp.c | A C source file to provide functions required by the HAL from your BSP |
+
+## Fill Out your Package File
+
+Edit the package file to describe your BSP.
+
+The package file must contain:
+
+```no-highlight
+ pkg.name: "hw/bsp/myboard"
+ pkg.linkerscript: "myboard.ld"
+```
+
+| **Attribute** | **Description** |
+|-----------|-------------|
+| pkg.name | the name of your bsp package |
+| pkg.linkerscript | The linker script that controls the memory placement of the compiled code sections from the Mynewt OS and your applications. |
+
+The linker script is a key component of the BSP and specifies where each
+section of code and data are stored within your CPU, which can vary
+with the BSP depending on your chosen memory layout. For a tutorial on
+writing linker scripts, see
+
+The package file typically contains:
+
+```no-highlight
+ pkg.linkerscript.bootloader.OVERWRITE: "myboard_boot.ld"
+ pkg.downloadscript: "myboard_download.sh"
+ pkg.debugscript: "myboard_debug.sh"
+ pkg.deps:
+ - hw/mcu/mymcu/variant
+```
+where `mymcu/variant` should be replaced with the specific MCU and variant
+used in your design.
+
+The following table describes additional attributes relevant to the BSP `pkg.yml` file
+
+| **Attribute** | **Description** |
+|-----------|-------------|
+| pkg.linkerscript.bootloader.OVERWRITE | A special linker for creating a bootloader for Mynewt |
+| pkg.downloadscript | A script that can download a flash image into your target platform |
+| pkg.debugscript | A script that can run the GDB debugger on your board |
+| pkg.deps | Any dependencies on your BSP |
+
+The BSP will invariably depend upon an MCU ( in this sample its
+`hw/mcu/mymcu/variant`) since the Mynewt OS runs on an
+MCU within your target. If your MCU is not supported by Mynewt, see
+[MCU Porting](port_mcu.md) for details on how to create an MCU in Mynewt.
+
+The package file may also contain:
+
+```no-highlight
+ pkg.cflags: -D__MY_SPECIAL_BSP_OPTIONS_
+ pkg.deps:
+ - libs/cmsis-core
+
+```
+| **Attribute** | **Description** |
+|-----------|-------------|
+| pkg.cflags | Any specific compiler flags for your bsp |
+| pkg.deps | Any other libraries that may be required. Some architectures (like ARM) have special libraries to make BSP creation easier |
+
+##Create or Copy the Linker Script(s)
+
+Its probably best to start with a linker script from another BSP using the
+same MCU. If this is not available, consult your MCU documentation and
+library samples to find a linker script to start with.
+
+Typically a linker script has to specify the following sections for code
+
+* .text -- the location and alignment of the memory section to store your code
+* .data -- the location and alignment of the memory section to store initialized data
+* .bss -- the location and alignment of the memory section to store uninitialized data
+* .heap -- the location and alignment of the memory section to provide system memory
+
+The linker script should specify the location and size of the
+different memory regions in your BSP and map the code sections
+described above into these regions.
+
+The linker script should also include a ENTRY point. This is used by the
+debugger to know where to start the program counter when the target is
+debugged.
+
+There may be additional requirements from the MCU or OS that code
+that you are easiest to place in the linker script. Some specific variables
+that the OS and MCU depends on are :
+
+| **Variable** | **Description** |
+|-----------|-------------|
+|\__bss_start__ | a variable located at the start of the BSS section |
+|\__bss_end__ | a variable located at the end of the BSS section |
+|\__isr_vector | Some CPUs map their interrupt vectors. They may need to be specified in the linker |
+|\_user_heap_start | the start of the heap for unallocated memory |
+|\_user_heap_end | the end of the heap for unallocated memory |
+
+Create an alternate linker script for the bootloader since it is typically
+linked to use different addresses to boot the main image.
+
+##What is Missing Now
+
+At this point, it will be possible to run the `newt` tool to build your target.
+
+You may find a few Mynewt specific functions missing. We will describe
+these below
+
+| **Function** | **Description** |
+|-----------|-------------|
+| os_bsp_init() | code to initialize the bsp |
+| os_bsp_systick_init() | code to setup the system tick for the OS |
+
+You may also find several libc definitions that can be stubbed in your first
+BSP. But you must implement this function to provide memory to the OS and
+system.
+
+| **Function** | **Description** |
+|-----------|-------------|
+| _sbrk | Returns memory from heap (used by malloc) |
+
+### Implement `_sbrk()`
+
+`sbrk()` is required by libg to get memory from the heap for things like malloc.
+Although not strongly BSP dependent, this is currently in the BSP to allow
+flexibility in providing system memory. See other BSPs for providing `sbrk`
+functionality.
+
+### Implement `os_bsp_init()`
+
+os_bsp_init should initialize anything required by the OS by the BSP. Typically
+this is very few things.
+
+NOTE: currently we are making calls to `_sbrk()` and `close(0)` from os_bsp_init
+to get around a linker issue where some of libg is not getting included. Please
+include this in your `os_bsp_init`
+
+```no-highlight
+ /*
+ * XXX these references are here to keep the functions in for libc to find.
+ */
+ _sbrk(0);
+ _close(0);
+
+```
+
+### Other Unresolved Defines or Functions
+
+There may be other unresolved defines or functions that are required by
+the specific MCU within your BSP. Below lists some sample defines.
+
+| **Undefined Variable** | **Description** |
+|-----------|-------------|
+| CONSOLE_UART_PORT | Which communications port on your target runs the console |
+| LED_BLINK_PIN | which pin on your target runs the blinky LED |
+
+The set of missing functionality depends upon the libraries and dependencies
+you have included in the project. That's why its best to keep your first
+project pretty simple then add incrementally. For example, if you include
+Newtron, you will need to define a file system map for your BSP.
+
+Missing functionality may take the form of `#define` items required to
+compile, or they may take the form of missing functions.
+
+### `cmsis_nvic.h`
+
+If you are using an ARM cortex architecture, you need to define the number of
+interrupts supported by your system. If you are not using ARM Cortex
+architecture this may not be required (but something else might be)
+
+##Add Debug Script
+
+The debug script in the bsp directory allows the newt tool to automatically
+connect to the debugger, and create a debug session with the target. This
+requires knowledge of your target debug interface.
+
+Most of the Mynewt BSP targets use [openocd](http://openocd.org) to perform
+debugging. This script typically creates an openocd connection to the target
+and then connects a gdb instance to this openocd connection. There are
+several examples in existing BSPs to follow.
+
+The script must take a single argument which is the name of the image file
+minus the '.elf' suffix.
+
+The BSP is complete without this file, but newt will be unable to
+establish a debug session without it.
+
+##Add Download Script
+
+Similar to the debug script, the download script is a hook for newt to download
+the image to the target system. The download script also typically uses
+openocd interface to erase flash, and progam the code into the device.
+
+NOTE: The download script needs to command openocd to program the image into
+the appropriate location, which is typically called `FLASH_OFFSET` in
+these scripts. This location has to match the linker script location
+of the image link address. For example if your linker links the code to
+be run at `0xC000` your download script should download the image to the same
+address in the correct flash.
+
+#Add license and Documentation
+
+The `LICENSE` file is an ASCII text file that describes the source license for this
+package.
+
+The `README.md` is a [markdown](https://en.wikipedia.org/wiki/Markdown)
+ file that contains any documentation you
+want to provide for the BSP.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/c2bd198b/docs/os/core_os/porting/port_cpu.md
----------------------------------------------------------------------
diff --git a/docs/os/core_os/porting/port_cpu.md b/docs/os/core_os/porting/port_cpu.md
index 1bc66e4..183866d 100644
--- a/docs/os/core_os/porting/port_cpu.md
+++ b/docs/os/core_os/porting/port_cpu.md
@@ -1,19 +1,48 @@
-# Mynewt OS
+# Porting Mynewt to a new CPU Architecture
-Insert introduction here
+A new CPU architecture typically requires the following:
-## Real-Time Kernel <Modify as you Wish>
+* A new compiler
+* new architecture specific code for the OS
+* Helper libraries to help others porting to the same architecture
- Description
-## Real-Time OS <Modify as you Wish>
+These are discussed below:
- Description
+## 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 attributes 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 a several architectures 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.
+
+Please contact the Mynewt development list for help and advice porting
+to new MCU.
-## Insert topic of your choice
- Description
-## Features
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/c2bd198b/docs/os/core_os/porting/port_mcu.md
----------------------------------------------------------------------
diff --git a/docs/os/core_os/porting/port_mcu.md b/docs/os/core_os/porting/port_mcu.md
index 1bc66e4..b3f21b4 100644
--- a/docs/os/core_os/porting/port_mcu.md
+++ b/docs/os/core_os/porting/port_mcu.md
@@ -1,19 +1,31 @@
-# Mynewt OS
+# Porting Mynewt to a new MCU
-Insert introduction here
+Porting Mynew to a new MCU is not a difficult task if the
+core CPU architectures is already supported.
-## Real-Time Kernel <Modify as you Wish>
+The depth of work depends on the amount of hal support you need and
+provide in your port.
- Description
+To get started:
-## Real-Time OS <Modify as you Wish>
+* create a `hw/mcu/mymcu` directory where mymcu is the MCU you are porting to.
+Replace the name `mymcu` with a description of the MCU you are using.
+* create a `hw/mcu/mymcu/variant` director where the variant is the specific
+variant of the part you are usuing. Many MCU parts have variants with different
+capabilityes (RAM, FLASH etc) or different pinouts. Replace `variant` with
+a description of the variant of the part you are using.
+* 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`, and
+a `hw/mcu/mymcu/variant/src` directories to contain the code for your mcu.
- Description
+At this point there are two main tasks to complete.
-## Insert topic of your choice
+* Implement any os specific code required by the OS
+* Implement the hal functionality that you are looking for
- Description
-
-## Features
+Please contact the Mynewt development list for help and advice porting
+to new MCU.
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/c2bd198b/docs/os/core_os/porting/port_os.md
----------------------------------------------------------------------
diff --git a/docs/os/core_os/porting/port_os.md b/docs/os/core_os/porting/port_os.md
index fd5ceb2..5180e41 100644
--- a/docs/os/core_os/porting/port_os.md
+++ b/docs/os/core_os/porting/port_os.md
@@ -83,7 +83,7 @@ on or off-chip MCU peripherals, with examples including 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](hal.md)
+see the [Hal API](../../modules/hal/hal.md)
###CPU Core Dependency
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/c2bd198b/docs/os/tutorials/arduino_zero.md
----------------------------------------------------------------------
diff --git a/docs/os/tutorials/arduino_zero.md b/docs/os/tutorials/arduino_zero.md
index e69de29..e2f44ec 100644
--- a/docs/os/tutorials/arduino_zero.md
+++ b/docs/os/tutorials/arduino_zero.md
@@ -0,0 +1,213 @@
+# Running Mynewt on Arduino Zero
+
+This tutorial describes how to run Mynewt OS on Arduino Zero.
+
+## Prerequisites
+
+Before tackling this tutorial, its best to read about Mynewt in the
+[Introduction](../get_started/introduction) section of this documentation.
+
+## Equipment
+
+You will need the following equipment
+
+* An Arduino Zero board. NOTE: There are many flavors of Arduino. Ensure that
+you have an arduino Zero.
+* A computer that can connect to the Arduino Zero over USB
+* A USB cable (Type A to micro B) that can connect the computer to the Arduino
+* The Mynewt Release
+
+## Steps
+
+Follow these simple steps and you be blinking in no time.
+
+### Install Mynewt and Newt
+
+If you have not already done so, install Newt, Mynewt and other
+prerequisites as shown [here](ugh)
+
+### Fetch External Packages for Atmel SAMD21
+
+Mynewt uses source code provided directly from the chip manufacturer for
+low level operations. This code is licensed only for Atmel parts, and
+cannot live in the Apache Mynewt repository. Fetch the package from
+the runtime github repository
+
+```no-highlight
+newt app add-pkg-list mynewt_arduino https://github.com/runtimeinc/mynewt_arduino_zero.git
+```
+
+Once that completes install the arduino_zero bsp package
+
+```no-highlight
+newt pkg install hw/bsp/arduino_zero
+```
+
+### Create your bootloader Target
+
+You need to tell Newt what you want to build. This is done by setting up a
+target. You may have already seen this target definition in this
+[Example](/newt/tutorials/define_target/)
+
+```no-highlight
+newt target import arduino_zero_bootloader
+@target=arduino_zero_bootloader
+name=arduino_zero_bootloader
+project=boot
+bsp=hw/bsp/arduino_zero
+compiler=arm-none-eabi-m0
+vers=0.0.1
+arch=cortex_m0
+compiler_def=optimized
+@endtargets
+```
+
+If your console blocks, you may need to do a `ctrl-D` to complete
+the import.
+
+### Create Your Image Target
+
+You need to tell Newt what you want to build. This is done by setting up a
+target. You may have already seen this target definition in this
+[Example](/newt/tutorials/define_target/)
+
+For simplicity, you can just import this target. Just cut and paste
+this into your Linux or MAC terminal from the larva directory.
+
+```no-highlight
+newt target import arduino_zero_blinky
+@target=arduino_zero_blinky
+vers=0.0.1
+arch=cortex_m0
+compiler_def=debug
+name=arduino_zero_blinky
+bsp=hw/bsp/arduino_zero
+compiler=arm-none-eabi-m0
+project=blinky
+@endtargets
+```
+
+If your console blocks, you may need to do a `ctrl-D` to complete
+the import.
+
+### Verify Your Targets
+
+Depending on your shell you may need to do a `Ctrl-D` to terminate the import
+operation.
+
+You can do a `newt target show` to see your results.
+
+```no-highlight
+arduino_zero_blinky
+ arch=cortex_m0
+ bsp=hw/bsp/arduino_zero
+ compiler=arm-none-eabi-m0
+ compiler_def=debug
+ name=arduino_zero_blinky
+ project=blinky
+ vers=0.0.1
+arduino_zero_bootloader
+ arch=cortex_m0
+ bsp=hw/bsp/arduino_zero
+ compiler=arm-none-eabi-m0
+ compiler_def=optimized
+ name=arduino_zero_bootloader
+ project=boot
+ vers=0.0.1
+```
+
+### Build the Bootloader
+
+To Build the bootloader, use newt to do:
+
+```no-highlight
+newt target build arduino_zero_bootloader
+```
+
+You should see lots of console output while newt is resolving dependencies
+and compiling the source code. After a minute, it should complete with
+the following text.
+
+```no-highlight
+. . .
+Archiving libarduino_zero.a
+Compiling boot.c
+Building project boot
+Linking boot.elf
+Successfully run!
+```
+### Connect the Target
+
+Connect your computer to the Arduino Zero (from now on we'll call this the
+target) with the Micro-USB cable through the Programming Port. Mynewt will
+download and debug the target through this port.
+
+No external debugger is required. The Arduino Zero comes with an internal
+debugger that can be accessed by Mynewt.
+
+A image below shows the Arduino Zero Programming Port.
+
+<img src="https://www.arduino.cc/en/uploads/Main/Zero_Usb_Ports.jpg" alt="Drawing" style="width: 400px;"/>
+
+### Download the Bootloader
+
+Execute the command to download the bootloader.
+
+```no-highlight
+newt target download arduino_zero_bootloader
+```
+
+The newt tool should respond with. Then 10-15 seconds later it will return a
+prompt indicating success.
+
+```no-highlight
+Downloading with .../arduino_zero_download.sh
+```
+
+### Build the Target
+
+To Build the target, use newt to do:
+
+```no-highlight
+newt target build arduino_zero_blinky
+```
+
+You should see lots of console output while newt is resolving dependencies
+and compiling the source code. After a minute, it should complete with
+the following text.
+
+```no-highlight
+Archiving libarduino_zero.a
+Compiling main.c
+Building project blinky
+Linking blinky.elf
+Successfully run!
+```
+
+### Build the Downloadable Image
+
+This command attaches the image descriptor header with the specicifed version
+number and prepares the image for download.
+
+```no-highlight
+newt target create-image arduino_zero_blinky 1.2.3
+```
+
+### Download the Image
+
+Execute the command to download the image.
+
+```no-highlight
+newt target download arduino_zero_blinky
+```
+The newt tool should respond with. Then 10-15 seconds later it will return a
+prompt indicating success.
+
+```no-highlight
+Downloading with .../arduino_zero_download.sh
+```
+
+### Watch the LED blink
+
+Congratulations!. You have create a Mynewt operating system running on the
+Arduino Zero. The LED is toggled by one task running on the Mynewt OS.
[2/2] incubator-mynewt-site git commit: Cleaned up port mynewt docs.
Added arduino Zero port documentation. This closes #28.
Posted by ad...@apache.org.
Cleaned up port mynewt docs. Added arduino Zero port documentation. This closes #28.
Project: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/commit/d668d1bd
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/d668d1bd
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/d668d1bd
Branch: refs/heads/master
Commit: d668d1bdf0d9cebb16023ed9c675bbb572941bd0
Parents: 901aafc c2bd198
Author: aditihilbert <ad...@runtime.io>
Authored: Fri Mar 4 10:42:25 2016 -0800
Committer: aditihilbert <ad...@runtime.io>
Committed: Fri Mar 4 10:42:25 2016 -0800
----------------------------------------------------------------------
docs/newt/command_list/newt_pkg.md | 2 +-
docs/os/core_os/porting/port_bsp.md | 24 ++--
docs/os/core_os/porting/port_cpu.md | 4 -
docs/os/core_os/porting/port_mcu.md | 3 +-
docs/os/tutorials/arduino_zero.md | 213 +++++++++++++++++++++++++++++++
5 files changed, 226 insertions(+), 20 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/d668d1bd/docs/newt/command_list/newt_pkg.md
----------------------------------------------------------------------
diff --cc docs/newt/command_list/newt_pkg.md
index 9eccb74,9eccb74..38ecf33
--- a/docs/newt/command_list/newt_pkg.md
+++ b/docs/newt/command_list/newt_pkg.md
@@@ -35,7 -35,7 +35,7 @@@ list | List all the pkgs in th
checkdeps | Resolve all dependencies in the local app. This command goes through all pkgs currently installed, checks their dependencies, and prints any unresolved dependencies between pkgs.
search | Searches for a pkg, specified by `input1`. The local app, along with all remote apps (pkg-lists) are searched. All matched pkgs are shown along with the pkg-list informaton. Installed pkgs are called out as such. The command can be invoked from anywhere in the app.
show | Show the contents of the pkg named `input2` found in the pkg-list named `input1`. The pkg-list name is optional; if only the pkg name is given as the argument it is resolved using all the pkg-lists installed in the current app. If the pkg is present in multiple pkg-lists it will list all of them along with the pkg-list information for each.
--install | Install the pkg specified by `input2` from the pkg-list named `input1`. The command downloads the pkg from the github repository using the URL in the pkg-list description file (typically donwloaded as 'input1@<branch-name>.yml' in .app/pkg-lists). It also downloads all the dependencies (constituent pkgs) as decribed in the pkg's description file ('pkg.yml') and installs all of them. The pkg-list name is optional. If only the pkg name is given as the argument, the command looks for the pkg name in all the pkg-lists in the local app and installs accordingly. A pkg is installed by this command only if it has not already been installed.
++install | Install the pkg specified by `input2` from the pkg-list named `input1`. The command downloads the pkg from the github repository using the URL in the pkg-list description file (typically downloaded as 'input1@<branch-name>.yml' in .app/pkg-lists). It also downloads all the dependencies (constituent pkgs) as decribed in the pkg's description file ('pkg.yml') and installs all of them. The pkg-list name is optional. If only the pkg name is given as the argument, the command looks for the pkg name in all the pkg-lists in the local app and installs accordingly. A pkg is installed by this command only if it has not already been installed.
remove | Remove a pkg named `input2` from pkg-list `input1`, if pkg-list is specified. Otherwise only one input required - that of the name of the pkg to be removed from the local app.
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/d668d1bd/docs/os/core_os/porting/port_bsp.md
----------------------------------------------------------------------
diff --cc docs/os/core_os/porting/port_bsp.md
index a822470,8048dbd..6243ba1
--- a/docs/os/core_os/porting/port_bsp.md
+++ b/docs/os/core_os/porting/port_bsp.md
@@@ -13,33 -17,41 +13,32 @@@ To build a proper BSP, you will typical
* The datasheet for the MCU you have chosen
* The schematic of your board
-* The information on the CPU core within your MCU if its 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 Mynewt documentation
-##Name Your BSP
+##Name your BSP
+
+Select a name for your BSP. For the remainder of this document, we'll assume the bsp is named `myboard`. In general its best to select a name that describes the board/system you are creating.
+
+##Create a BSP directory
+
+Create a directory `hw/bsp/myboard` using the name chosen above. Within this BSP directory, create the following subdirectories:
+ Select a name for your BSP. For the remainder of this document,
+ well assume the bsp is named `myboard`. In general its best to select a
+ name that describes the board/system you are creating.
+
-##Create a BSP Directory
-
-Create a directory `hw/bsp/myboard` using the name chosen above.
-Within this BSP directory, create the following subdirectories:
-
* `include`
* `include/bsp`
* `src`
##Create a Target using Mynewt
- Create a newt target for your test project for the BSP. To learn how to create a target, see this **howto** [Tutorial](../../get_started/project1). Once you are
-Create a newt target for your test project for the BSP. To learn how to
-create a target, see this [Tutorial](../../get_started/project1). Once you are
--familiar with creating targets, move on below to create a target to use to
--test your BSP.
++Create a newt target for your test project for the BSP. To learn how to create a target, see this **howto** [Tutorial](../../get_started/project1). Once you are familiar with creating targets, move on below to create a target to use to test your BSP.
--Its recommended to use a simple `project` like `blinky` to minimize time to get a
--working Mynewt system. For this document, we will assume the `target` is called
--`myboard_blinky` and uses project `blinky`.
++It is recommended that you use a simple `project` like `blinky` to minimize time to get a working Mynewt system. For this document, we will assume the `target` is called `myboard_blinky` and uses project `blinky`.
--Set the `bsp` of the project to `/hw/bsp/myboard`.
- While creating your target, you will need to specify your `arch`and `compiler`. If your platform requires an architecture or compiler that are not defined in Mynewt, you will need to add them first. To add a CPU architecture see [CPU Porting](port_cpu.md).
-While creating your target, you will need to specify your `arch`and `compiler`.
-If your platform requires an architecture or compiler that are not defined
-in Mynewt, you will need to add them first. To add a CPU architecture see
-[CPU Porting](port_cpu.md).
++Set the `bsp` of the project to `/hw/bsp/myboard`. While creating your target, you will need to specify your `arch`and `compiler`. If your platform requires an architecture or compiler that are not defined in Mynewt, you will need to add them first. To add a CPU architecture see [CPU Porting](port_cpu.md).
When you are complete, your `target` may look similar to this.
@@@ -116,8 -134,10 +115,7 @@@ The following table describes additiona
| pkg.debugscript | A script that can run the GDB debugger on your board |
| pkg.deps | Any dependencies on your BSP |
- The BSP will invariably depend upon an MCU ( in this sample it's `hw/mcu/mymcu/variant`) since the Mynewt OS runs on an MCU within your target. If your MCU is not supported by Mynewt, see
-The BSP will invariably depend upon an MCU ( in this sample its
-`hw/mcu/mymcu/variant`) since the Mynewt OS runs on an
-MCU within your target. If your MCU is not supported by Mynewt, see
--[MCU Porting](port_mcu.md) for details on how to create an MCU in Mynewt.
++The BSP will invariably depend upon an MCU ( in this sample it's `hw/mcu/mymcu/variant`) since the Mynewt OS runs on an MCU within your target. If your MCU is not supported by Mynewt, see [MCU Porting](port_mcu.md) for details on how to create an MCU in Mynewt.
The package file may also contain:
@@@ -163,14 -192,17 +161,14 @@@ Create an alternate linker script for t
At this point, it will be possible to run the `newt` tool to build your target.
- You may find a few Mynewt specific functions missing. We will describe these below.
-You may find a few Mynewt specific functions missing. We will describe
-these below
++You may run into complaints from the linker script that a few Mynewt specific functions are missing. We will describe these below.
| **Function** | **Description** |
|-----------|-------------|
| os_bsp_init() | code to initialize the bsp |
| os_bsp_systick_init() | code to setup the system tick for the OS |
- You may also find several libc definitions that can be stubbed in your first BSP. But you must implement the following function to provide memory to the OS and system.
-You may also find several libc definitions that can be stubbed in your first
-BSP. But you must implement this function to provide memory to the OS and
-system.
++There are also several libc definitions that can be stubbed in your first BSP. Examples are `_write`, `_read`, etc. that can be found in `libc_stubs.c`. But you _must_ implement the following function to provide memory to the OS and system.
| **Function** | **Description** |
|-----------|-------------|
@@@ -234,4 -294,4 +232,4 @@@ package
The `README.md` is a [markdown](https://en.wikipedia.org/wiki/Markdown)
file that contains any documentation you
--want to provide for the BSP.
++want to provide for the BSP.
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/d668d1bd/docs/os/core_os/porting/port_cpu.md
----------------------------------------------------------------------
diff --cc docs/os/core_os/porting/port_cpu.md
index 13b9e06,183866d..d5e2c3f
--- a/docs/os/core_os/porting/port_cpu.md
+++ b/docs/os/core_os/porting/port_cpu.md
@@@ -3,10 -3,10 +3,9 @@@
A new CPU architecture typically requires the following:
* A new compiler
-* new architecture specific code for the OS
+* New architecture-specific code for the OS
* Helper libraries to help others porting to the same architecture
--
These are discussed below:
## Create A New Compiler
@@@ -24,14 -31,18 +23,11 @@@ Edit the `pkg.yml` file and change the
| 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 a several architectures 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.
-
-Please contact the Mynewt development list for help and advice porting
-to new MCU.
+##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.
+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.
-
-
-
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/d668d1bd/docs/os/core_os/porting/port_mcu.md
----------------------------------------------------------------------
diff --cc docs/os/core_os/porting/port_mcu.md
index 8316111,b3f21b4..8fe5fbf
--- a/docs/os/core_os/porting/port_mcu.md
+++ b/docs/os/core_os/porting/port_mcu.md
@@@ -1,22 -1,31 +1,21 @@@
# Porting Mynewt to a new MCU
- Porting Mynew to a new MCU is not a difficult task if the core CPU architectures is already supported.
-Porting Mynew to a new MCU is not a difficult task if the
-core CPU architectures is already supported.
++Porting Mynewt to a new MCU is not a difficult task if the core CPU architectures is already supported.
-The depth of work depends on the amount of hal support you need and
-provide in your port.
+The depth of work depends on the amount of HAL (Hardware Abstraction Layer) support you need and provide in your port.
To get started:
-* create a `hw/mcu/mymcu` directory where mymcu is the MCU you are porting to.
-Replace the name `mymcu` with a description of the MCU you are using.
-* create a `hw/mcu/mymcu/variant` director where the variant is the specific
-variant of the part you are usuing. Many MCU parts have variants with different
-capabilityes (RAM, FLASH etc) or different pinouts. Replace `variant` with
-a description of the variant of the part you are using.
-* 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`, and
-a `hw/mcu/mymcu/variant/src` directories to contain the code for your mcu.
-
+* Create a `hw/mcu/mymcu` directory where `mymcu` is the MCU you are porting to. Replace the name `mymcu` with a description of the MCU you are using.
+* Create a `hw/mcu/mymcu/variant` directory where the variant is the specific variant of the part you are usuing. Many MCU parts have variants with different capabilities (RAM, FLASH etc) or different pinouts. Replace `variant` with a description of the variant of the part you are using.
+* 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`, and
+`hw/mcu/mymcu/variant/src` directories to contain the code for your mcu.
-
At this point there are two main tasks to complete.
-* Implement any os specific code required by the OS
-* Implement the hal functionality that you are looking for
+* Implement any OS-specific code required by the OS
+* Implement the HAL functionality that you are looking for
-Please contact the Mynewt development list for help and advice porting
-to new MCU.
+Please contact the Mynewt development list for help and advice porting to new MCU.