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/17 20:23:07 UTC
[GitHub] aditihilbert closed pull request #743: docs: convert console .md to .rst & link
aditihilbert closed pull request #743: docs: convert console .md to .rst & link
URL: https://github.com/apache/mynewt-core/pull/743
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/doxygen.xml b/docs/doxygen.xml
index 72ab529cc..4ae2f5c48 100644
--- a/docs/doxygen.xml
+++ b/docs/doxygen.xml
@@ -789,7 +789,8 @@ WARN_LOGFILE =
# spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
# Note: If this tag is empty the current directory is searched.
-INPUT = kernel/os
+INPUT = kernel/os \
+ sys/console/full
# This tag can be used to specify the character encoding of the source files
# that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -2042,7 +2043,8 @@ INCLUDE_FILE_PATTERNS =
# recursively expanded use the := operator instead of the = operator.
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
-PREDEFINED =
+PREDEFINED = min max \
+ "MYNEWT_VAL(CONSOLE_COMPAT)=1"
# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
# tag can be used to specify a list of macro names that should be expanded. The
diff --git a/docs/os/core_os/API.rst b/docs/os/core_os/API.rst
index 7cf7bac58..c663c482a 100644
--- a/docs/os/core_os/API.rst
+++ b/docs/os/core_os/API.rst
@@ -5,6 +5,13 @@ Core OS API
:local:
:depth: 2
+
+Core
+~~~~
+
+.. doxygenfile:: os.h
+
+
Scheduler
~~~~~~~~~
diff --git a/docs/os/get_started/cross_tools.rst b/docs/os/get_started/cross_tools.rst
deleted file mode 100644
index 62ae26f76..000000000
--- a/docs/os/get_started/cross_tools.rst
+++ /dev/null
@@ -1,239 +0,0 @@
-Installing the Cross Tools for ARM
-==================================
-
-This page shows you how to install the tools to build, run, and debug
-Mynewt OS applications that run on supported ARM target boards. It shows
-you how to install the following tools on Mac OS, Linux and Windows:
-
-- ARM cross toolchain to compile and build Mynewt applications for the
- target boards.
-- Debuggers to load and debug applications on the target boards.
-
-Installing the ARM Cross Toolchain
-----------------------------------
-
-ARM maintains a pre-built GNU toolchain with gcc and gdb targeted at
-Embedded ARM Processors, namely Cortex-R/Cortex-M processor families.
-Mynewt OS has been tested with version 4.9 of the toolchain and we
-recommend you install this version to get started. Mynewt OS will
-eventually work with multiple versions available, including the latest
-releases.
-
-Installing the ARM Toolchain For Mac OS X
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Add the **PX4/homebrew-px4** homebrew tap and install version 4.9 of the
-toolchain. After installing, check that the symbolic link that homebrew
-created points to the correct version of the debugger.
-
-.. code-block:: console
-
- $ brew tap PX4/homebrew-px4
- $ brew update
- $ brew install gcc-arm-none-eabi-49
- $ arm-none-eabi-gcc --version
- arm-none-eabi-gcc (GNU Tools for ARM Embedded Processors) 4.9.3 20150529 (release) [ARM/embedded-4_9-branch revision 224288]
- Copyright (C) 2014 Free Software Foundation, Inc.
- This is free software; see the source for copying conditions. There is NO
- warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
- $ ls -al /usr/local/bin/arm-none-eabi-gdb
- lrwxr-xr-x 1 aditihilbert admin 69 Sep 22 17:16 /usr/local/bin/arm-none-eabi-gdb -> /usr/local/Cellar/gcc-arm-none-eabi-49/20150609/bin/arm-none-eabi-gdb
-
-**Note:** If no version is specified, brew will install the latest
-version available.
-
-Installing the ARM Toolchain For Linux
-~~~~~~~~~~~~~~~
-
-
-On a Debian-based Linux distribution, gcc 4.9.3 for ARM can be installed
-with apt-get as documented below. The steps are explained in depth at
-https://launchpad.net/~team-gcc-arm-embedded/+archive/ubuntu/ppa.
-
-.. code-block:: console
-
- $ sudo apt-get remove binutils-arm-none-eabi gcc-arm-none-eabi
- $ sudo add-apt-repository ppa:team-gcc-arm-embedded/ppa
- $ sudo apt-get update
- $ sudo apt-get install gcc-arm-none-eabi
- $ sudo apt-get install gdb-arm-none-eabi
-
-Installing the ARM Toolchain for Windows
-~~~~~~~~~~~~~~~
-
-Step 1: Download and run the
-`installer <https://launchpad.net/gcc-arm-embedded/4.9/4.9-2015-q2-update/+download/gcc-arm-none-eabi-4_9-2015q2-20150609-win32.exe>`__
-to install arm-none-eabi-gcc and arm-none-eabi-gdb. Select the default
-destination folder: **C::raw-latex:`\Program `Files
-(x86):raw-latex:`\GNU `Tools ARM Embedded:raw-latex:`\4`.9 2015q2**.
-
-**Note:** You may select a different folder but the installation
-instructions use the default values.
-
-Step 2: Add the path:\*\* C::raw-latex:`\Program `Files
-(x86):raw-latex:`\GNU `Tools ARM Embedded:raw-latex:`\4`.9
-2015q2:raw-latex:`\bin*`\* to your Windows **Path** environment
-variable. Note: You must add **bin** to the path.
-
-Step 3: Check that you are using the installed versions
-arm-none-eabi-gcc and arm-none-eabi-gdb. Open a MinGW terminal and run
-the ``which`` commands.
-
-**Note:** You must start a new MinGW terminal to inherit the new
-**Path** values.
-
-.. code-block:: console
-
- $ which arm-none-eabi-gcc
- /c/Program Files (x86)/GNU Tools ARM Embedded/4.9 2015q2/bin/arm-none-eabi-gcc
- $which arm-none-eabi-gdb
- /c/Program Files (x86)/GNU Tools ARM Embedded/4.9 2015q2/bin/arm-none-eabi-gdb
-
-Installing the Debuggers
-------------------------
-
-Mynewt uses, depending on the board, either the OpenOCD or SEGGER J-Link
-debuggers. ### Installing the OpenOCD Debugger OpenOCD (Open On-Chip
-Debugger) is open-source software that allows your computer to interface
-with the JTAG debug connector on a variety of boards. A JTAG connection
-lets you debug and test embedded target devices. For more on OpenOCD go
-to http://openocd.org.
-
-OpenOCD version 0.10.0 with nrf52 support is required. A binary for this
-version is available to download for Mac OS, Linux, and Windows.
-
-Installing OpenOCD on Mac OS
-^^^^^^^^^^^^^^^^^^^
-
-Step 1: Download the `binary tarball for Mac
-OS <https://github.com/runtimeco/openocd-binaries/raw/master/openocd-bin-0.10.0-MacOS.tgz>`__.
-
-Step 2: Change to the root directory:
-
-.. code-block:: console
-
- $cd /
-
-Step 3: Untar the tarball and install into \*\* /usr/local/bin**. You
-will need to replace ** ~/Downloads \*\* with the directory that the
-tarball is downloaded to.
-
-.. code-block:: console
-
- sudo tar -xf ~/Downloads/openocd-bin-0.10.0-MacOS.tgz `
-
-Step 4: Check the OpenOCD version you are using.
-
-.. code-block:: console
-
- $which openocd
- /usr/local/bin/openocd
- $openocd -v
- Open On-Chip Debugger 0.10.0
- Licensed under GNU GPL v2
- For bug reports, read
- http://openocd.org/doc/doxygen/bugs.html
-
-You should see version: **0.10.0**.
-
-If you see one of these errors:
-
-- Library not loaded: /usr/local/lib/libusb-0.1.4.dylib - Run
- ``brew install libusb-compat``.
-- Library not loaded: /usr/local/opt/libftdi/lib/libftdi1.2.dylib - Run
- ``brew install libftdi``.
-- Library not loaded: /usr/local/lib/libhidapi.0.dylib - Run
- ``brew install hidapi``.
-
-Installing OpenOCD on Linux
-^^^^^^^^^^^^^^^^^^^
-
-Step 1: Download the `binary tarball for
-Linux <https://github.com/runtimeco/openocd-binaries/raw/master/openocd-bin-0.10.0-Linux.tgz>`__
-
-Step 2: Change to the root directory:
-
-::
-
- $cd /
-
-Step 3: Untar the tarball and install into \*\* /usr/local/bin**. You
-will need to replace ** ~/Downloads \*\* with the directory that the
-tarball is downloaded to.
-
-\*\* Note:\*\* You must specify the -p option for the tar command.
-
-.. code-block:: console
-
- $sudo tar -xpf ~/Downloads/openocd-bin-0.10.0-Linux.tgz
-
-Step 4: Check the OpenOCD version you are using:
-
-.. code-block:: console
-
- $which openocd
- /usr/local/bin/openocd
- $openocd -v
- Open On-Chip Debugger 0.10.0
- Licensed under GNU GPL v2
- For bug reports, read
- http://openocd.org/doc/doxygen/bugs.html
-
-You should see version: **0.10.0**.
-
-If you see any of these error messages:
-
-- openocd: error while loading shared libraries: libhidapi-hidraw.so.0:
- cannot open shared object file: No such file or directory
-
-- openocd: error while loading shared libraries: libusb-1.0.so.0:
- cannot open shared object file: No such file or directory
-
-run the following command to install the libraries:
-
-.. code-block:: console
-
- $sudo apt-get install libhidapi-dev:i386
-
-Installing OpenOCD on Windows
-^^^^^^^^^^^^^^^^^^^
-
-Step 1: Download the `binary zip file for
-Windows <https://github.com/runtimeco/openocd-binaries/raw/master/openocd-0.10.0.zip>`__.
-
-Step 2: Extract into the **C::raw-latex:`\openocd`-0.10.0** folder.
-
-Step 3: Add the path: \*\*
-C::raw-latex:`\openocd`-0.10.0:raw-latex:`\bin*`\* to your Windows User
-**Path** environment variable. Note: You must add **bin** to the path.
-
-Step 4: Check the OpenOCD version you are using. Open a new MinGW
-terminal and run the following commands:
-
-**Note:** You must start a new MinGW terminal to inherit the new
-**Path** values.
-
-.. code-block:: console
-
- $which openocd
- /c/openocd-0.10.0/bin/openocd
- $openocd -v
- Open On-Chip Debugger 0.10.0
- Licensed under GNU GPL v2
- For bug reports, read
- http://openocd.org/doc/doxygen/bugs.html
-
-You should see version: **0.10.0**.
-
-Installing SEGGER J-Link You can download and install Segger J-LINK
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Software and documentation pack from
-`SEGGER <https://www.segger.com/jlink-software.html>`__.
-
-**Note:** On Windows, perform the following after the installation:
-
-- Add the installation destination folder path to your Windows user
- **Path** environment variable. You do not need to add **bin** to the
- path.
-- Open a new MinGW terminal to inherit the new **Path** values.
diff --git a/docs/os/get_started/docker.rst b/docs/os/get_started/docker.rst
deleted file mode 100644
index d79f91be1..000000000
--- a/docs/os/get_started/docker.rst
+++ /dev/null
@@ -1,123 +0,0 @@
-Everything You Need in a Docker Container
------------------------------------------
-
-Docker provides a quick and easy way to get up and running with Mynewt.
-The newt command line tool and the entire build toolchain is available
-in a single docker container. The container is all that's needed to run
-your Mynewt based application in the simulator. Enabling USB2 with your
-docker installation will allow you to load your application on a
-supported device.
-
-Docker is the only supported option if you are working on a Windows
-machine. If you are using Mac OS X or Linux, you have the choice of
-installing a Docker container of tools and toolchains or installing them
-natively. This chapter describes how to set up the Docker image for all
-three platforms.
-
-Install Docker
-~~~~~~~~~~~~~~
-
-Install docker for your platform. `Mac OS
-X <https://www.docker.com/products/docker-toolbox>`__ /
-`Windows <https://www.docker.com/products/docker-toolbox>`__ /
-`Linux <https://docs.docker.com/engine/installation/linux/>`__
-
-Mac and Windows
-^^^^^^^^^^^^^^^
-
-Mac and Windows require Docker Toolbox to interact with USB devices.
-Docker for Mac and Docker for Windows do not support USB. Docker Toolbox
-uses VirtualBox and allows you to map USB devices into docker containers
-as described below.
-
-Make sure to double click the Docker Quickstart Terminal application if
-you're on Mac or Windows.
-
-Linux
-^^^^^
-
-The docker daemon listens on a Unix domain socket on Linux. That socket
-is owned by root, which means by default you must be root to start a
-container. Make sure to follow the optional step of adding yourself to
-the docker group so you can start the newt container as yourself.
-
-Use the newt wrapper script
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Use the newt wrapper script to invoke newt. Create the following file,
-name it ``newt``, make it executable, and put it in your path. This will
-allow you to run newt as if it was natively installed. You can now
-follow the normal tutorials using the newt wrapper script.
-
-.. code:: bash
-
- #!/bin/bash
-
- if [ "$1" = "debug" ] || [ "$1" = "run" ]
- then
- ti="-ti"
- fi
-
- docker run -e NEWT_USER=$(id -u) -e NEWT_GROUP=$(id -g) -e NEWT_HOST=$(uname) $ti --rm --device=/dev/bus/usb --privileged -v $(pwd):/workspace -w /workspace mynewt/newt:latest /newt "$@"
-
-**Note 1:** Remember to point to the correct subdirectory level when
-invoking ``newt``. For example, invoke it using ``../newt`` in the
-example below.
-
-.. code:: console
-
- user@~/dockertest$ ls
- myproj newt
- user@~/dockertest$ cd myproj
- user@~/dockertest/myproj$ ../newt version
- Apache Newt version: 1.1.0
-
-**Note 2:** You can upgrade your container by running
-``docker pull mynewt/newt:latest`` when updates are made available.
-
-Enable USB2 Support for Mac or Windows
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If you plan on loading your application on an actual device, do the
-steps below.
-
-Install VirtualBox extension pack
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Docker uses a VirtualBox Linux VM to run containers. A free VirtualBox
-extension pack is required to enable USB2 support. Download the
-`VirtualBox Extension
-Pack <https://www.virtualbox.org/wiki/Downloads>`__ version that matches
-your VirtualBox installation and double click to install
-
-Enable USB2 and select your device
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-- The "default" VM created by docker-machine must first be stopped
- before you can enable USB2. You have two options:
-
- - Run the command ``docker-machine stop default`` in the terminal
- window or
- - Use the VirtualBox UI. Right click on ``default`` -> Close ->
- Power Off
-
-- Enable USB2 using the VirtualBox UI. Select the "default"
- VM->Settings->Ports->USB2 to enable USB2. Add your device to the USB
- Device Filters to make the device visible in the docker container.
- See the image below.
-
-- Restart the "default" VM. You have two options:
-- Run ``docker-machine start default`` in the terminal window or
-- Use the VirtualBox UI. Make sure the "default" machine is
- highlighted. Click the green "Start" button. Select "Headless Start".
-
-**Note 3**: When working with actual hardware, remember that each board
-has an ID. If you swap boards and do not refresh the USB Device Filter
-on the VirtualBox UI, the ID might be stale and the Docker instance may
-not be able to see the board correctly. For example, you may see an
-error message like ``Error: unable to find CMSIS-DAP device`` when you
-try to load or run an image on the board. In that case, you need to
-click on the USB link in VirtualBox UI, remove the existing USB Device
-Filter (e.g. "Atmel Corp. EDBG CMSIS-DAP[0101]") by clicking on the
-"Removes selected USB filter" button, and add a new filter by clicking
-on the "Adds new USB filter" button.
diff --git a/docs/os/get_started/get_started.rst b/docs/os/get_started/get_started.rst
deleted file mode 100644
index 44091811d..000000000
--- a/docs/os/get_started/get_started.rst
+++ /dev/null
@@ -1,44 +0,0 @@
-Basic Setup
-===========
-
-.. toctree::
- :hidden:
-
- native_install_intro
- Docker Container <docker>
- Create Your First Project <project_create>
- Serial Port Setup <serial_access>
-
-If you are curious about Mynewt and want to get a quick feel for the
-project, you've come to the right place. We have two options for you:
-
-**Option 1 (Recommended)** allows you to install the Newt tool,
-instances of the Mynewt OS (for simulated targets), and toolchains for
-developing embedded software (e.g. GNU toolchain) natively on your
-laptop or computer. We have tried to make the process easy. For example,
-for the Mac OS we created brew formulas.
-
-We recommend this option if you are familiar with such environments or
-are concerned about performance on your machine. Follow the instructions
-in the `Native Install Option <native_install_option>`__ if you prefer
-this option.
-
-**Option 2** is an easy, self-contained way to get up and running with
-Mynewt - but has limitations! The Newt tool and build toolchains are all
-available in a single `All-in-one Docker Container <docker_container_option.html>`__ that
-you can install on your laptop or computer.
-
-However, this is not a long-term option since support is not likely for
-all features useful or critical to embedded systems development. For
-example, USB device mapping available in the Docker toolkit is no longer
-available in the new Docker releases. The Docker option is also
-typically slower than the native install option.
-
-You can then proceed with the instructions on how to `Create Your First
-Project <project_create.html>`__ - on simulated hardware.
-
-Upon successful start, several tutorials await your eager attention!
-
-**Send us an email on the dev@ mailing list if you have comments or
-suggestions!** If you haven't joined the mailing list, you will find the
-links `here <../../community.html>`__.
diff --git a/docs/os/get_started/native_install_intro.rst b/docs/os/get_started/native_install_intro.rst
deleted file mode 100644
index 5f5dae4cf..000000000
--- a/docs/os/get_started/native_install_intro.rst
+++ /dev/null
@@ -1,50 +0,0 @@
-Native Installation
-===================
-
-.. toctree::
- :hidden:
-
- /newt/install/newt_mac
- /newt/install/newt_linux
- /newt/install/newt_windows
- native_tools
- cross_tools
-
-This section shows you how to install the tools to develop and build
-Mynewt OS applications on Mac OS, Linux, and Windows, and run and debug
-the applications on target boards. For Mac OS and Linux, you can also
-build Mynewt OS applications that run on Mynewt's simulated hardware.
-These applications run natively on Mac OS and Linux.
-
-The tools you need are:
-
-- Newt tool: Tool to create, build, load, and debug Mynewt OS
- applications.
-
- - See `Installing the Newt Tool on Mac
- OS <install_newt_on_mac.html>`__ to install on Mac OS.
- - See `Installing the Newt Tool on
- Linux <install_newt_on_linux.html>`__ to install on Linux.
- - See `Installing the Newt Tool on
- Windows <install_newt_on_windows.html>`__ to install on Windows.
-
-- Native toolchain: Native toolchain to compile and build Mynewt OS
- applications that run on Mynewt's simulated hardware on Mac OS and
- Linux.
-
- (See `Installing Native
- Toolchain <native_tools.html>`__).
-
-- Cross tools for ARM:
-
- - Cross toolchain for ARM to compile and build Mynewt OS
- applications for target boards.
- - Debuggers to load and debug applications on target boards.
-
- (See `Installing Cross Tools for
- ARMs <cross_tools.html>`__).
-
-If you would like to use an IDE to develop and debug Mynewt
-applications, see `using an IDE to develop Mynewt
-Applications </faq/ide.html>`__. You must still perform the native
-installation outlined on this page.
diff --git a/docs/os/get_started/native_tools.rst b/docs/os/get_started/native_tools.rst
deleted file mode 100644
index a7c3f53f7..000000000
--- a/docs/os/get_started/native_tools.rst
+++ /dev/null
@@ -1,142 +0,0 @@
-Installing Native Toolchain
-===========================
-
-This page shows you how to install the toolchain to build Mynewt OS
-applications that run native on Mac OS and Linux. The applications run
-on Mynewt's simulated hardware. It also allows you to run the test
-suites for all packages that do not require HW support.
-
-**Note:** This is not supported on Windows.
-
-Setting Up the Toolchain for Mac
---------------------------------
-
-Installing Brew
-~~~~~~~~~~~~~~~
-
-If you have not already installed Homebrew from the ```newt`` tutorials
-pages <../../newt/install/newt_mac.html>`__, install it.
-
-Installing gcc/libc
-~~~~~~~~~~~~~~~~~~~
-
-OS X ships with a C compiler called Clang. To build applications for the
-Mynewt simulator with, a different compiler is used as default: gcc.
-
-.. code-block:: console
-
- $ brew install gcc
- ...
- ...
- ==> Summary
- ? /usr/local/Cellar/gcc/5.2.0: 1353 files, 248M
-
-Check the gcc version you have installed (either using brew or
-previously installed). The brew-installed version can be checked using
-``brew list gcc``. The default compiler.yml configuration file in Mynewt
-expects version 5.x for Mac users, so if the installed version is 6.x
-and you wish to continue with this newer version, modify the
-``<mynewt-src-directory>/repos/apache-mynewt-core/compiler/sim/compiler.yml``
-file to change the default ``gcc-5`` defined there to ``gcc-6``. In
-other words, replace the lines shown highlighted below:
-
-``hl_lines="2 3" # OS X. compiler.path.cc.DARWIN.OVERWRITE: "gcc-5" compiler.path.as.DARWIN.OVERWRITE: "gcc-5" compiler.path.objdump.DARWIN.OVERWRITE: "gobjdump" compiler.path.objsize.DARWIN.OVERWRITE: "objsize" compiler.path.objcopy.DARWIN.OVERWRITE: "gobjcopy"``
-with the following:
-
-.. code-block:: console
-
- compiler.path.cc.DARWIN.OVERWRITE: "gcc-6"
- compiler.path.as.DARWIN.OVERWRITE: "gcc-6?
-
-In case you wish to use Clang, you can change your
-``<mynewt-src-directory>/repos/apache-mynewt-core/compiler/sim/compiler.yml``
-to use Clang. Delete the gcc-5 DARWIN.OVERWRITE lines highlighted below.
-
-``hl_lines="2 3" # OS X. compiler.path.cc.DARWIN.OVERWRITE: "gcc-5" compiler.path.as.DARWIN.OVERWRITE: "gcc-5" compiler.path.objdump.DARWIN.OVERWRITE: "gobjdump" compiler.path.objsize.DARWIN.OVERWRITE: "objsize" compiler.path.objcopy.DARWIN.OVERWRITE: "gobjcopy"``
-
-**NOTE:** Both the newer gcc 6.x and Clang report a few warnings but
-they can be ignored.
-
-**FURTHER NOTE:** Mynewt developers mostly use gcc 5.x for sim builds;
-so it may take a little while to fix issues reported by the newer
-compiler. One option is to **disable warnings**. To do that, remove the
-``-Werror`` flag as an option for the compiler in the
-``<mynewt-src-directory>/repos/apache-mynewt-core/compiler/sim/compiler.yml``
-file as shown below.
-
-.. code:: hl_lines="2"
-
- compiler.flags.base: >
- -m32 -Wall -ggdb
-
-You may alternatively choose to **specify the precise warnings to
-ignore** depending on the error thrown by the compiler. For example, if
-you see a ``[-Werror=misleading-indentation]`` error while building the
-sim image, add ``-Wno-misleading-indentation]`` as a compiler flag in
-the same line from the
-``<mynewt-src-directory>/repos/apache-mynewt-core/compiler/sim/compiler.yml``
-file.
-
-.. code:: hl_lines="2"
-
- compiler.flags.base: >
- -m32 -Wall -Werror -ggdb -Wno-misleading-indentation
-
-A third option is to simply **downgrade to gcc 5.x**.
-
-Installing gdb
-~~~~~~~~~~~~~~
-
-.. code-block:: console
-
- $ brew install gdb
- ...
- ...
- ==> Summary
- ? /usr/local/Cellar/gdb/7.10.1: XXX files,YYM
-
-**NOTE:** When running a program with gdb, you may need to sign your gdb
-executable. `This
-page <https://gcc.gnu.org/onlinedocs/gnat_ugn/Codesigning-the-Debugger.html>`__
-shows a recipe for gdb signing. Alternately you can skip this step and
-continue without the ability to debug your mynewt application on your
-PC.\*
-
-Setting Up the Toolchain for Linux
-----------------------------------
-
-The below procedure can be used to set up a Debian-based Linux system
-(e.g., Ubuntu). If you are running a different Linux distribution, you
-will need to substitute invocations of *apt-get* in the below steps with
-the package manager that your distro uses.
-
-Install gcc/libc that will produce 32-bit executables:
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. code-block:: console
-
- $ sudo apt-get install gcc-multilib libc6-i386
-
-Install gdb
-~~~~~~~~~~~
-
-.. code-block:: console
-
- $ sudo apt-get install gdb
-
- Reading package lists... Done
- Building dependency tree
- Reading state information... Done
- Suggested packages:
- gdb-doc gdbserver
- The following NEW packages will be installed:
- gdb
- ...
- Processing triggers for man-db (2.6.7.1-1ubuntu1) ...
- Setting up gdb (7.7.1-0ubuntu5~14.04.2) ...
-
-At this point you have installed all the necessary software to build and
-run your first project on a simluator on your Mac OS or Linux computer.
-You may proceed to the `Create Your First Project <project_create.html>`__
-section or continue to the next section and install the cross tools for
-ARM.
diff --git a/docs/os/get_started/project_create.rst b/docs/os/get_started/project_create.rst
deleted file mode 100644
index d664e3352..000000000
--- a/docs/os/get_started/project_create.rst
+++ /dev/null
@@ -1,452 +0,0 @@
-Creating Your First Mynewt Project
-----------------------------------
-
-This page shows you how to create a Mynewt project using the ``newt``
-command-line tool. The project is a blinky application that toggles a
-pin. The application uses the Mynewt's simulated hardware and runs as a
-native application on Mac OS and Linux.
-
-**Note:** The Mynewt simulator is not yet supported on Windows. If you
-are using the native install option (not the Docker option), you will
-need to create the blinky application for a target board. We recommend
-that you read the section on creating a new project and fetching the
-source repository to understand the Mynewt repository structure, create
-a new project, and fetch the source dependencies before proceeding to
-one of the `Blinky Tutorials </os/tutorials/blinky.html>`__.
-
-This guide shows you how to:
-
-1. Create a new project and fetch the source repository and
- dependencies.
-2. Test the project packages. (Not supported on Windows.)
-3. Build and run the simulated blinky application. (Not supported on
- Windows.)
-
-Prerequisites
-~~~~~~~~~~~~~
-
-- Have Internet connectivity to fetch remote Mynewt components.
-- Install the newt tool:
-
- - If you have taken the native install option, see the installation
- instructions for `Mac OS <../../newt/install/newt_mac.html>`__,
- `Linux <../../newt/install/newt_linux.html>`__, or
- `Windows <../../newt/install/newt_windows.html>`__.
- - If you have taken the Docker option, you have already installed
- Newt.
-
-- Install the `native toolchain <native_tools.html>`__ to compile and
- build a Mynewt native application.
-
-Creating a New Project and Fetching the Source Repository
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-This section describes how to use the newt tool to create a new project
-and fetch the core mynewt source repository.
-
-Creating a New Project
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Choose a name for your project. We name the project ``myproj``.
-
-Run the ``newt new myproj`` command, from your **dev** directory, to
-create a new project:
-
-**Note:** This tutorial assumes you created a **dev** directory under
-your home directory.
-
-.. code-block:: console
-
- $cd ~/dev
- $ newt new myproj
- Downloading project skeleton from apache/mynewt-blinky...
- Installing skeleton in myproj...
- Project myproj successfully created.
-
-The newt tool creates a project base directory name **myproj**. All newt
-tool commands are run from the project base directory. The newt tool
-populates this new project with a base skeleton of a new Apache Mynewt
-project in the project base directory. It has the following structure:
-
-**Note**: If you do not have ``tree``, run ``brew install tree`` to
-install on Mac OS, ``sudo apt-get install tree`` to install on Linux,
-and ``pacman -Su tree`` from a MinGW terminal to install on Windows.
-
-.. code-block:: console
-
- $ cd myproj
- $ tree
- .
- ??? DISCLAIMER
- ??? LICENSE
- ??? NOTICE
- ??? README.md
- ??? apps
- ??? ??? blinky
- ??? ??? pkg.yml
- ??? ??? src
- ??? ??? main.c
- ??? project.yml
- ??? targets
- ??? my_blinky_sim
- ??? ??? pkg.yml
- ??? ??? target.yml
- ??? unittest
- ??? pkg.yml
- ??? target.yml
-
- 6 directories, 11 files
-
-The newt tool installs the following files for a project in the project
-base directory:
-
-1. The file ``project.yml`` contains the repository list that the
- project uses to fetch its packages. Your project is a collection of
- repositories. In this case, the project only comprises the core
- mynewt repository. Later, you will add more repositories to include
- other mynewt components.
-2. The file ``apps/blinky/pkg.yml`` contains the description of your
- application and its package dependencies.
-3. A ``target`` directory that contains the ``my_blinky_sim`` directory.
- The ``my_blinky_sim`` directory a target information to build a
- version of myproj. Use ``newt target show`` to see available build
- targets.
-4. A non-buildable target called ``unittest``. This is used internally
- by ``newt`` and is not a formal build target.
-
-**Note:** The actual code and package files are not installed (except
-the template for ``main.c``). See the next step to install the packages.
-
-Fetching the Mynewt Source Repository and Dependencies
-^^^^^^^^^^^^^^^^^^^
-
-By default, Mynewt projects rely on a single repository:
-**apache-mynewt-core** and uses the source in the master branch. If you
-need to use a different branch, you need to change the ``vers`` value in
-the project.yml file:
-
-.. code-block:: console
-
- repository.apache-mynewt-core:
- type: github
- vers: 1-latest
- user: apache
- repo: mynewt-core
-
-Changing vers to 0-dev will put you on the latest master branch. **This
-branch may not be stable and you may encounter bugs or other problems.**
-
-**Note:** On Windows platforms, you will need to change vers to 0-dev
-and use the latest master branch. Release 1.0.0 is not supported on
-Windows.
-
-Run the ``newt install`` command, from your project base directory
-(myproj), to fetch the source repository and dependencies.
-
-**Note:** It may take a while to download the apache-mynewt-core
-reposistory. Use the *-v* (verbose) option to see the installation
-progress.
-
-.. code-block:: console
-
- $ newt install
- apache-mynewt-core
-
- **Note:** If you get the following error:
-
-::
-
- ReadDesc: No matching branch for apache-mynewt-core repo
- Error: No matching branch for apache-mynewt-core repop
-
-You must edit the ``project.yml`` file and change the line
-``repo: incubator-mynewt-core`` as shown in the following example to
-``repo: mynewt-core``:
-
-.. code:: hl_lines="5"
-
- repository.apache-mynewt-core:
- type: github
- vers: 1-latest
- user: apache
- repo: incubator-mynewt-core
-
-View the core of the Apache Mynewt OS that is downloaded into your local
-directory.
-
-(The actual output will depend on what is in the latest 'master' branch)
-
-.. code-block:: console
-
- $ tree -L 2 repos/apache-mynewt-core/
-
- repos/apache-mynewt-core/
- ??? CODING_STANDARDS.md
- ??? DISCLAIMER
- ??? LICENSE
- ??? NOTICE
- ??? README.md
- ??? RELEASE_NOTES.md
- ??? apps
- ??? ??? blecent
- ??? ??? blehci
- ??? ??? bleprph
- ??? ??? bleprph_oic
- ??? ??? blesplit
- ??? ??? bletest
- ??? ??? bletiny
- ??? ??? bleuart
- ??? ??? boot
- ??? ??? fat2native
- ??? ??? ffs2native
- ??? ??? ocf_sample
- ??? ??? slinky
- ??? ??? slinky_oic
- ??? ??? spitest
- ??? ??? splitty
- ??? ??? test
- ??? ??? testbench
- ??? ??? timtest
- ??? boot
- ??? ??? boot_serial
- ??? ??? bootutil
- ??? ??? split
- ??? ??? split_app
- ??? compiler
- ??? ??? arm-none-eabi-m0
- ??? ??? arm-none-eabi-m4
- ??? ??? gdbmacros
- ??? ??? mips
- ??? ??? sim
- ??? ??? sim-mips
- ??? crypto
- ??? ??? mbedtls
- ??? ??? tinycrypt
- ??? docs
- ??? ??? doxygen.xml
- ??? encoding
- ??? ??? base64
- ??? ??? cborattr
- ??? ??? json
- ??? ??? tinycbor
- ??? fs
- ??? ??? disk
- ??? ??? fatfs
- ??? ??? fcb
- ??? ??? fs
- ??? ??? nffs
- ??? hw
- ??? ??? bsp
- ??? ??? cmsis-core
- ??? ??? drivers
- ??? ??? hal
- ??? ??? mcu
- ??? ??? scripts
- ??? kernel
- ??? ??? os
- ??? libc
- ??? ??? baselibc
- ??? mgmt
- ??? ??? imgmgr
- ??? ??? mgmt
- ??? ??? newtmgr
- ??? ??? oicmgr
- ??? net
- ??? ??? ip
- ??? ??? nimble
- ??? ??? oic
- ??? ??? wifi
- ??? project.yml
- ??? repository.yml
- ??? sys
- ??? ??? config
- ??? ??? console
- ??? ??? coredump
- ??? ??? defs
- ??? ??? flash_map
- ??? ??? id
- ??? ??? log
- ??? ??? mfg
- ??? ??? reboot
- ??? ??? shell
- ??? ??? stats
- ??? ??? sysinit
- ??? targets
- ??? ??? unittest
- ??? test
- ??? ??? crash_test
- ??? ??? flash_test
- ??? ??? runtest
- ??? ??? testutil
- ??? time
- ??? ??? datetime
- ??? util
- ??? cbmem
- ??? crc
- ??? mem
-
- 94 directories, 9 files
-
-Testing the Project Packages
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Note**: This is not yet supported on Windows.
-
-You can use the newt tool to execute the unit tests in a package. For
-example, run the following command to test the ``sys/config`` package in
-the ``apache-mynewt-core`` repo:
-
-.. code-block:: console
-
- $ newt test @apache-mynewt-core/sys/config
- Testing package @apache-mynewt-core/sys/config/test-fcb
- Compiling bootutil_misc.c
- Compiling image_ec.c
- Compiling image_rsa.c
- Compiling image_validate.c
-
- ...
-
- Linking ~/dev/myproj/bin/targets/unittest/sys_config_test-fcb/app/sys/config/test-fcb/sys_config_test-fcb.elf
- Executing test: ~/dev/myproj/bin/targets/unittest/sys_config_test-fcb/app/sys/config/test-fcb/sys_config_test-fcb.elf
- Testing package @apache-mynewt-core/sys/config/test-nffs
- Compiling repos/apache-mynewt-core/encoding/base64/src/hex.c
- Compiling repos/apache-mynewt-core/fs/fs/src/fs_cli.c
- Compiling repos/apache-mynewt-core/fs/fs/src/fs_dirent.c
- Compiling repos/apache-mynewt-core/fs/fs/src/fs_mkdir.c
- Compiling repos/apache-mynewt-core/fs/fs/src/fs_mount.c
- Compiling repos/apache-mynewt-core/encoding/base64/src/base64.c
- Compiling repos/apache-mynewt-core/fs/fs/src/fs_file.c
- Compiling repos/apache-mynewt-core/fs/disk/src/disk.c
- Compiling repos/apache-mynewt-core/fs/fs/src/fs_nmgr.c
- Compiling repos/apache-mynewt-core/fs/fs/src/fsutil.c
- Compiling repos/apache-mynewt-core/fs/nffs/src/nffs.c
-
- ...
-
- Linking ~/dev/myproj/bin/targets/unittest/sys_config_test-nffs/app/sys/config/test-nffs/sys_config_test-nffs.elf
- Executing test: ~/dev/myproj/bin/targets/unittest/sys_config_test-nffs/app/sys/config/test-nffs/sys_config_test-nffs.elf
- Passed tests: [sys/config/test-fcb sys/config/test-nffs]
- All tests passed
-
-**Note:** If you installed the latest gcc using homebrew on your Mac,
-you are probably running gcc-6. Make sure you change the compiler.yml
-configuration to specify that you are using gcc-6 (See `Native Install
-Option <native_tools.html>`__). You can also downgrade your installation
-to gcc-5 and use the default gcc compiler configuration for MyNewt:
-
-.. code-block:: console
-
- $ brew uninstall gcc-6
- $ brew link gcc-5
-
-**Note:** If you are running the standard gcc for 64-bit machines, it
-does not support 32-bit. In that case you will see compilation errors.
-You need to install multilib gcc (e.g. gcc-multilib if you running on a
-64-bit Ubuntu).
-
-To test all the packages in a project, specify ``all`` instead of the
-package name.
-
-.. code-block:: console
-
- $ newt test all
- Testing package @apache-mynewt-core/boot/boot_serial/test
- Compiling repos/apache-mynewt-core/boot/boot_serial/test/src/boot_test.c
- Compiling repos/apache-mynewt-core/boot/boot_serial/test/src/testcases/boot_serial_setup.c
-
- ...
-
- Linking ~/dev/myproj/bin/targets/unittest/boot_boot_serial_test/app/boot/boot_serial/test/boot_boot_serial_test.elf
-
- ...lots of compiling and testing...
-
- Linking ~/dev/myproj/bin/targets/unittest/util_cbmem_test/app/util/cbmem/test/util_cbmem_test.elf
- Executing test: ~/dev/myproj/bin/targets/unittest/util_cbmem_test/app/util/cbmem/test/util_cbmem_test.elf
- Passed tests: [boot/boot_serial/test boot/bootutil/test crypto/mbedtls/test encoding/base64/test encoding/cborattr/test encoding/json/test fs/fcb/test fs/nffs/test kernel/os/test net/ip/mn_socket/test net/nimble/host/test net/oic/test sys/config/test-fcb sys/config/test-nffs sys/flash_map/test sys/log/full/test util/cbmem/test]
- All tests passed
-
-Building and Running the Simulated Blinky Application
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The section shows you how to build and run the blinky application to run
-on Mynewt's simulated hardware.
-
-**Note**: This is not yet supported on Windows. Refer to the `Blinky
-Tutorials </os/tutorials/blinky.html>`__ to create a blinky application
-for a target board.
-
-Building the Application
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-To build the simulated blinky application, run ``newt build my_blinky_sim``:
-
-.. code-block:: console
-
- $ newt build my_blinky_sim
- Building target targets/my_blinky_sim
- Compiling repos/apache-mynewt-core/hw/hal/src/hal_common.c
- Compiling repos/apache-mynewt-core/hw/drivers/uart/src/uart.c
- Compiling repos/apache-mynewt-core/hw/hal/src/hal_flash.c
- Compiling repos/apache-mynewt-core/hw/bsp/native/src/hal_bsp.c
- Compiling repos/apache-mynewt-core/hw/drivers/uart/uart_hal/src/uart_hal.c
- Compiling apps/blinky/src/main.c
-
- ...
-
-
- Archiving sys_mfg.a
- Archiving sys_sysinit.a
- Archiving util_mem.a
- Linking ~/dev/myproj/bin/targets/my_blinky_sim/app/apps/blinky/blinky.elf
- Target successfully built: targets/my_blinky_sim
-
-Running the Blinky Application
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-You can run the simulated version of your project and see the simulated
-LED blink.
-
-If you natively install the toolchain execute the binary directly:
-
-.. code-block:: console
-
- $ ./bin/targets/my_blinky_sim/app/apps/blinky/blinky.elf
- hal_gpio set pin 1 to 0
-
-If you are using newt docker, use ``newt run`` to run the simulated
-binary.
-
-.. code-block:: console
-
- $ newt run my_blinky_sim
- Loading app image into slot 1
- ...
- Debugging ~/dev/myproj/bin/targets/my_blinky_sim/app/apps/blinky/blinky.elf
- ...
- Reading symbols from /bin/targets/my_blinky_sim/app/apps/blinky/blinky.elf...done.
- (gdb)
-
-Type ``r`` at the ``(gdb)`` prompt to run the project. You will see an
-output indicating that the hal\_gpio pin is toggling between 1 and 0 in
-a simulated blink.
-
-Type ``r`` at the ``(gdb)`` prompt to run the project. You will see an
-output indicating that the ``hal_gpio`` pin is toggling between 1 and 0
-in a simulated blink.
-
-Exploring other Mynewt OS Features
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Congratulations, you have created your first project! The blinky
-application is not terribly exciting when it is run in the simulator, as
-there is no LED to blink. Apache Mynewt has a lot more functionality
-than just running simulated applications. It provides all the features
-you'll need to cross-compile your application, run it on real hardware
-and develop a full featured application.
-
-If you're interested in learning more, a good next step is to dig in to
-one of the `tutorials <../tutorials/tutorials>`__ and get a Mynewt
-project running on real hardware.
-
-Happy Hacking!
diff --git a/docs/os/get_started/serial_access.rst b/docs/os/get_started/serial_access.rst
deleted file mode 100644
index 391e12440..000000000
--- a/docs/os/get_started/serial_access.rst
+++ /dev/null
@@ -1,203 +0,0 @@
-Using the Serial Port with Mynewt OS
-====================================
-
-Some of the projects and tutorials here will allow you to use a serial
-port to interact with your Mynewt project. While most modern PCs and
-laptops no longer have a true serial port, almost all can use their USB
-ports as serial ports.
-
-This will show you how to connect to some of the development boards we
-use via a serial port.
-
-The development boards covered here are:
-
-- Nordic Semiconductor NRF52dk
-- Arduino M0 Pro
-
-In order to communicate with these boards you will also need a
-USB<-->Serial converted. We'll be using the `AdaFruit FT232H Breakout
-Board <https://www.adafruit.com/products/2264>`__ for this, but almost
-any similar board should work just as well. You will also need Minicom
-or a similar Serial communications application. We'll show you how to
-use the ``screen`` command built in to Mac OS X, but later tutorials
-will also show Minicom setup.
-
-So let's get started!
-
-Setup FT232H
-------------
-
-This is a great board because it's so easy to set up, and it can do
-Serial UART, SPI, I2C and GPIO as well. There's full documentation on
-the board
-`here <https://learn.adafruit.com/adafruit-ft232h-breakout/overview>`__
-but we're only covering the wiring for the Serial UART.
-
-Start by connecting a jumper wire to Pin D0. This will be the UART Tx
-pin, which we'll then connect to the Rx pin on the Development Board.
-
-Next connect a jumper wire to pin D1. This will be the UART Rx pin,
-which we'll connect to the Tx pin on the development board.
-
-Finally connect a jumper wire to the GND pin.
-
-It should look like this:
-
-.. figure:: pics/ft232h.png
- :alt: FT232H Wiring
-
- FT232H Wiring
-
-Setup Nordic Semiconductor NRF52DK
-----------------------------------
-
-On the NRF52DK developer kit board, the Rx pin is P0.08, so you'll
-attach your jumper wire from the Tx pin (D0) of the FT232H board here.
-
-The TX Pin is pin P0.06, so you'll attache the jumper wire from the Rx
-Pin (D1) on the FT232H board here.
-
-Finally, the GND wire should go to the GND Pin on the NRF52DK. When
-you're done, your wiring should look like this:
-
-.. figure:: pics/nrf52dk.png
- :alt: NRF52DK Wiring
-
- NRF52DK Wiring
-
-Setup Arduino M0 Pro
---------------------
-
-On the Arduino M0 Pro, the Tx and Rx pins are clearly labeled as such,
-as is the GND pin. Just make sure you wire Rx from the FT232H to TX on
-the M0 Pro, and vice-versa.
-
-Your Arduino M0 Pro should look like this:
-
-.. figure:: pics/m0pro.png
- :alt: Arduino M0 Pro Wiring
-
- Arduino M0 Pro Wiring
-
-Setup Serial Communications
----------------------------
-
-You will need to know the serial port to connect to and use a terminal
-program to connect to the board.
-
-Example for Mac OS and Linux Platforms
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-First check what USB devices are already connected before connecting the
-FT232H board to your computer. The ports are listed in the **/dev**
-directory and the format of the port name is platform dependent:
-
-- Mac OS uses the format ``tty.usbserial-<some identifier>``.
-- Linux uses the format ``TTYUSB<N>``, where ``N`` is a number. For
- example, TTYUSB2.
-
-This example is run on a Mac OS system.
-
-Check what USB devices are already connected:
-
-.. code-block:: console
-
- $ ls -la /dev/*usb*
- 0 crw-rw-rw- 1 root wheel 20, 63 Nov 23 11:13 /dev/cu.usbmodem401322
- 0 crw-rw-rw- 1 root wheel 20, 62 Nov 23 11:13 /dev/tty.usbmodem401322
- $
-
-Plug in the FT232H board and check the ports again:
-
-.. code-block:: console
-
- $ ls -la /dev/*usb*
- 0 crw-rw-rw- 1 root wheel 20, 63 Nov 23 11:13 /dev/cu.usbmodem401322
- 0 crw-rw-rw- 1 root wheel 20, 65 Nov 23 11:26 /dev/cu.usbserial-0020124
- 0 crw-rw-rw- 1 root wheel 20, 62 Nov 23 11:13 /dev/tty.usbmodem401322
- 0 crw-rw-rw- 1 root wheel 20, 64 Nov 23 11:26 /dev/tty.usbserial-0020124
- $
-
-The FT232H is connected to ``/dev/tty.usbserial-0020124`` (The number
-after tty.usbserial will be different on your machine.) Use the screen
-command to connect to the board:
-
-.. code-block:: console
-
- $ screen /dev/tty.usbserial-0020124 115200
-
-To exit out of ``screen`` you'll type ``control-A`` followed by
-``control-\`` and you'll be back to a terminal prompt.
-
-You can also use minicom:
-
-.. code-block:: console
-
- $ minicom -D /dev/tty.usbserial-0020124
-
- Welcome to minicom 2.7
-
- OPTIONS:
- Compiled on Nov 24 2015, 16:14:21.
- Port /dev/tty.usbserial-0020124, 09:57:17
-
- Press Meta-Z for help on special keys
-
-If there's no Mynewt app running, or the Mynewt app doesn't have the
-Shell and Console enabled, you won't see anything there, but you can
-always refer back to this page from later tutorials if you need to.
-
-Example for Windows Platforms
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-First check what USB devices are already connected before connecting the
-FT232H board to your computer. You can locate the ports from a MinGW
-terminal or use the Windows Device Manager.
-
-On a MinGW terminal, the ports are listed in the /dev directory and the
-format of the port name is ``ttyS<N>`` where N is a number. You must map
-the port name to a Windows COM port: ``/dev/ttyS<N>`` maps to
-``COM<N+1>``. For example, ``/dev/ttyS2`` maps to ``COM3``.
-
-Check what USB devices are already connected:
-
-.. code-block:: console
-
- $ ls -l /dev/ttyS*
- crw-rw-rw- 1 <user> None 117, 5 May 9 04:24 /dev/ttyS5
- $
-
-/dev/ttyS5 maps to the Windows COM6 port. You can run Windows Device
-Manager to confirm:
-
-|Device Manager - USB Devices|
-
-Plug in the FT232H board and check the ports again:
-
-.. code-block:: console
-
- $ ls -l /dev/ttyS*
- ls -l /dev/ttyS*
- crw-rw-rw- 1 <user> None 117, 10 May 9 04:55 /dev/ttyS10
- crw-rw-rw- 1 <user> None 117, 5 May 9 04:55 /dev/ttyS5
- $
-
-The FT232H board is connected to port /dev/ttyS10 (or COM11):
-
-|Device Manager - FT232H|
-
-We use the PuTTY terminal application to connect to the board on the
-COM11 port: |PuTTY|
-
-Press Open and you should get a terminal screen titled "COM11 - PuTTY"
-
-If there's no Mynewt app running, or the Mynewt app doesn't have the
-Shell and Console enabled, you won't see anything there, but you can
-always refer back to this page from later tutorials if you need to.
-
-Now that you know how to communicate with your mynewt application, let's
-move on to creating one!
-
-.. |Device Manager - USB Devices| image:: /os/tutorials/pics/device_manager_no_ft232H.png
-.. |Device Manager - FT232H| image:: /os/tutorials/pics/device_manager_ft232H.png
-.. |PuTTY| image:: /os/tutorials/pics/putty.png
diff --git a/docs/os/get_started/vocabulary.rst b/docs/os/get_started/vocabulary.rst
deleted file mode 100644
index ab6bc9a02..000000000
--- a/docs/os/get_started/vocabulary.rst
+++ /dev/null
@@ -1,186 +0,0 @@
-Concepts
---------
-
-This page is meant to introduce you to some of the concepts inherent to
-the Apache Mynewt Operating System, and *Newt* the tool that stitches a
-project built on Apache Mynewt together.
-
-Project
-~~~~~~~
-
-The project is the base directory of your embedded software tree. It is
-a workspace that contains a logical collection of source code, for one
-or more of your applications. A project consists of the following items:
-
-- Project Definition: defines project level dependencies, and
- parameters (located in ``project.yml``)
-- Packages
-
-`Packages <#package>`__ are described in detail in the section below.
-
-Here is an example project definition file from the default Apache
-Mynewt project:
-
-.. code-block:: console
-
- $ more project.yml
- <snip>
- project.name: "my_project"
-
- project.repositories:
- - apache-mynewt-core
-
- # Use github's distribution mechanism for core ASF libraries.
- # This provides mirroring automatically for us.
- #
- repository.apache-mynewt-core:
- type: github
- vers: 1-latest
- user: apache
- repo: mynewt-core
- $
-
-A couple of things to note in the project definition:
-
-- ``project.repositories``: Defines the remote repositories that this
- project relies upon.
-
-- ``repository.apache-mynewt-core``: Defines the repository information
- for the ``apache-mynewt-core`` repository.
-
-- ``vers=1-latest``: Defines the repository version. This string will
- use the latest stable version in the 'Master' github branch. To use
- the latest version in the master branch, just change it to
- ``vers=0-dev``. Note that this branch might not be stable.
-
-Repositories are versioned collections of packages.
-
-Projects can rely on remote repositories for functionality, and the newt
-tool will resolve those remote repositories, and download the correct
-version into your local source tree. Newly fetched repositories are put
-in the ``repos`` directory of your project, and can be referenced
-throughout the system by using the ``@`` specifier.
-
-By default, the ``@apache-mynewt-core`` repository is included in every
-project. Apache Mynewt Core contains all the base functionality of the
-Apache Mynewt Operating System, including the Real Time Kernel,
-Bluetooth Networking Stack, Flash File System, Console, Shell and
-Bootloader.
-
-*NOTE:* Any project can be converted into a repository by providing it
-with a ``repository.yml`` file and putting it up onto Github. More
-information about repositories can be found in the Newt documentation.
-
-Package
-~~~~~~~
-
-A package is a collection items that form a fundamental unit in the
-Mynewt Operating System. Packages can be:
-
-- Applications
-- Libraries
-- Compiler definitions
-- Targets
-
-A package is identified by having a ``pkg.yml`` file in it's base
-directory. Here is a sample ``pkg.yml`` file for the blinky applicaton:
-
-.. code-block:: console
-
- $ more pkg.yml
- <snip>
- pkg.name: apps/blinky
- pkg.type: app
- pkg.description: Basic example application which blinks an LED.
- pkg.author: "Apache Mynewt <de...@mynewt.apache.org>"
- pkg.homepage: "http://mynewt.apache.org/"
- pkg.keywords:
-
- pkg.deps:
- - "@apache-mynewt-core/libs/os"
- - "@apache-mynewt-core/hw/hal"
- - "@apache-mynewt-core/libs/console/full"
-
-Packages have a few features worth noting:
-
-- Dependencies: Packages can rely upon other packages, and when they do
- they will inherit their functionality (header files, library
- definitions, etc.)
-- APIs: Packages can export named APIs, and they can require that
- certain APIs be present, in order to compile.
-
-Everything that newt knows about within a project's directory is a
-package. This makes it very clean and easy to write re-usable
-components, which can describe their Dependencies and APIs to the rest
-of the system.
-
-Target
-~~~~~~
-
-A target in Apache Mynewt is very similar to a target in *make*. It is
-the collection of parameters that must be passed to Newt in order to
-generate a reproducible build. A target represents the top of the build
-tree, and any packages or parameters specified at the target level,
-cascade down to all dependencies.
-
-Targets are also packages, and are stored in the ``targets/`` directory
-at the base of your project. Most targets consist of:
-
-- ``app``: The application to build.
-- ``bsp``: The board support package to combine with that application
-- ``build_profile``: Either ``debug`` or ``optimized``.
-
-Targets can also have additional items specified, including:
-
-- ``aflags``: Any additional assembler flags you might want to specify
- to the build.
-- ``cflags``: Any additional compiler flags you might want to specify
- to the build.
-- ``lflags``: Any additional linker flags you might want to specify to
- the build.
-
-In order to create and manipulate targets, the *newt* tool offers a set
-of helper commands, you can find more information about these by
-issuing:
-
-``no-highlight $ newt target``\ no-highlight newt target Usage: newt
-target [flags] newt target [command]
-
-Available Commands: config View or populate a target's system
-configuration copy Copy target create Create a target delete Delete
-target dep View target's dependency graph revdep View target's
-reverse-dependency graph set Set target configuration variable show View
-target configuration variables
-
-Global Flags: -h, --help Help for newt commands -j, --jobs int Number of
-concurrent build jobs (default 8) -l, --loglevel string Log level
-(default "WARN") -o, --outfile string Filename to tee output to -q,
---quiet Be quiet; only display error output -s, --silent Be silent;
-don't output anything -v, --verbose Enable verbose output when executing
-commands
-
-Use "newt target [command] --help" for more information about a command.
-
-$ \`\`\`
-
-Configuration
-~~~~~~~~~~~~~
-
-Additional help topics:
-
-.. code-block:: console
-
- $ newt target config show <target-name>
- ...
- * PACKAGE: sys/stats
- * Setting: STATS_CLI
- * Description: Expose the "stat" shell command.
- * Value: 0
- * Setting: STATS_NAMES
- * Description: Include and report the textual name of each statistic.
- * Value: 0
- * Setting: STATS_NEWTMGR
- * Description: Expose the "stat" newtmgr command.
- * Value: 0
- ...
- $
diff --git a/docs/os/modules/console/console.rst b/docs/os/modules/console/console.rst
index 60a9f032d..731a96308 100644
--- a/docs/os/modules/console/console.rst
+++ b/docs/os/modules/console/console.rst
@@ -6,6 +6,10 @@ OS subsystems or a console application. A user typically inputs text
from a keyboard and reads the OS output text on a computer monitor. The
text is sent as a sequence of characters between the user and the OS.
+.. contents::
+ :local:
+ :depth: 2
+
You can configure the console to communicate via a UART or the SEGGER
Real Time Terminal (RTT) . The ``CONSOLE_UART`` syscfg setting enables
the communication via a UART and is enabled by default. The
@@ -32,7 +36,7 @@ OS ticks in each output line.
- The console package is initialized during system initialization
(sysinit) so you do not need to initialize the console. However, if
you use the Mynewt 1.0 console API to read from the console, you will
- need to call the ``console_init()`` function to enable backward
+ need to call the :c:func:`console_init()` function to enable backward
compatibility support.
Description
@@ -45,15 +49,14 @@ In the Mynewt OS, the console library comes in three versions:
- The ``sys/console/stub`` package implements stubs for the API.
- The ``sys/console/minimal`` package implements minimal console
functionality of reading from and writing to console. It implements
- the ``console_read()`` and ``console_write()`` functions and stubs
+ the :c:func:`console_read()` and :c:func:`console_write()` functions and stubs
for all the other console functions.
All the packages export the ``console`` API, and any package that uses
the console API must list ``console`` as a requirement its ``pkg.yml``
file:
-.. code-block:: console
-
+.. code-block:: yaml
pkg.name: sys/shell
pkg.deps:
@@ -68,7 +71,7 @@ The project ``pkg.yml`` file also specifies the version of the console
package to use.
Using the Full Console Package
-^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
A project that requires the full console capability must list the ``sys/console/full`` package as a
dependency in its ``pkg.yml`` file.
@@ -76,7 +79,7 @@ dependency in its ``pkg.yml`` file.
An example is the ``slinky`` application. It requires the full console
capability and has the following ``pkg.yml`` file:
-.. code-block:: console
+.. code-block:: yaml
pkg.name: apps/slinky
pkg.deps:
@@ -92,8 +95,7 @@ capability and has the following ``pkg.yml`` file:
- sys/id
Using the Stub Console Package
-^^^^^^^^^^^^^^^^^^^
-
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
A project that uses console stub API must list the ``sys/console/stub``
package as a dependency in its ``pkg.yml`` file.
@@ -121,7 +123,7 @@ capability in this particular bootloader project to keep the size small.
We simply use the console stub instead, and the pkg.yml file for the
project boot pkg looks like the following:
-.. code-block:: console
+.. code-block:: yaml
pkg.name: apps/boot
pkg.deps:
@@ -138,7 +140,7 @@ be a project that supports serial image upgrade but does not need full
newtmgr capability. The project would use the console minimal API and
has the following ``pkg.yml`` file:
-.. code-block:: console
+.. code-block:: yaml
pkg.name: apps/boot
pkg.type: app
@@ -158,16 +160,14 @@ has the following ``pkg.yml`` file:
- boot/boot_serial
Output to the Console
-^^^^^^^^^^^^^^^^^^^
-
+^^^^^^^^^^^^^^^^^^^^^
-You use the ``console_write()`` function to write raw output and the
-``console_printf()`` function to write a C-style formatted string to the
+You use the :c:func:`console_write()` function to write raw output and the
+:c:func:`console_printf()` function to write a C-style formatted string to the
console.
Input from the Console
-^^^^^^^^^^^^^^^^^^^
-
+^^^^^^^^^^^^^^^^^^^^^^
The following syscfg settings control input from the console:
@@ -176,7 +176,7 @@ The following syscfg settings control input from the console:
- ``CONSOLE_ECHO``: Enables echoing of the received data back to the
console. Echoing is enabled by default. Terminal programs expect
this, and is a way for the user to know that the console is connected
- and responsive. You can also use the ``console_echo()`` function to
+ and responsive. You can also use the :c:func:`console_echo()` function to
set echo on or off programatically.
- ``CONSOLE_MAX_INPUT_LEN``: Specifies the maximum input line length.
@@ -185,85 +185,82 @@ from the console. The package supports backward compatibility for the
Mynewt 1.0 console API. The steps you use to receive data from the
console for each API version are provided below.
-# Mynewt 1.0 Console API
+Mynewt 1.0 Console API
^^^^^^^^^^^^^^^^^^^^^^^^^
-
To use the Mynewt 1.0 console API for reading input from the console,
you perform the follow steps:
-1. Call the ``console_init()`` function and pass either a pointer to a
+1. Call the :c:func:`console_init()` function and pass either a pointer to a
callback function or NULL for the argument. The console calls this
callback function, if specified, when it receives a full line of
data.
-2. Call the ``console_read()`` function to read the input data.
+2. Call the :c:func:`console_read()` function to read the input data.
**Note:** The ``CONSOLE_COMPAT`` syscfg setting must be set to 1 to
enable backward compatibility support. The setting is enabled by
default.
-# Mynewt 1.1 Console API
+Mynewt 1.1 Console API
^^^^^^^^^^^^^^^^^^^^^^^^^
-
Mynewt 1.1 console API adds the
-``console_set_queues(struct os_eventq *avail_queue, struct os_eventq *lines_queue)``
+:c:func:`console_set_queues()`
function. An application or the package, such as the shell, calls this
function to specify two event queues that the console uses to manage
input data buffering and to send notification when a full line of data
is received. The two event queues are used as follows:
-- **avail\_queue**: Each event in this queue indicates that a buffer is
+- **avail_queue**: Each event in this queue indicates that a buffer is
available for the console to use for buffering input data.
- The caller must initialize the avail\_queue and initialize and add an
- `os\_event </os/core_os/event_queue/event_queue.html>`__ to the
- avail\_queue before calling the ``console_set_queues()`` function.
+ The caller must initialize the avail_queue and initialize and add an
+ :doc:`../../os/core_os/event_queue/event_queue` to the
+ avail_queue before calling the :c:func:`console_set_queues()` function.
The fields for the event should be set as follows:
- - **``ev_cb``**: Pointer to the callback function to call when a
+ - ``ev_cb``: Pointer to the callback function to call when a
full line of data is received.
- - **``ev_arg``**: Pointer to a ``console_input`` structure. This
+ - ``ev_arg``: Pointer to a :c:data:`console_input` structure. This
structure contains a data buffer to store the current input.
The console removes an event from this queue and uses the
- ``console_input`` buffer from this event to buffer the received
+ :c:data:`console_input` buffer from this event to buffer the received
characters until it receives a new line, '/n', character. When the
console receives a full line of data, it adds this event to the
- **lines\_queue**.
+ **lines_queue**.
-- **lines\_queue**: Each event in this queue indicates a full line of
+- **lines_queue**: Each event in this queue indicates a full line of
data is received and ready for processing. The console adds an event
to this queue when it receives a full line of data. This event is the
- same event that the console removes from the avail\_queue.
+ same event that the console removes from the avail_queue.
- The task that manages the lines\_queue removes an event from the
+ The task that manages the lines_queue removes an event from the
queue and calls the event callback function to process the input
line. The event callback function must add the event back to the
- avail\_queue when it completes processing the current input data, and
- allows the console to use the ``console_input`` buffer set for this
+ avail_queue when it completes processing the current input data, and
+ allows the console to use the :c:data:`console_input` buffer set for this
event to buffer input data.
- We recommend that you use the OS default queue for the lines\_queue
+ We recommend that you use the OS default queue for the lines_queue
so that the callback is processed in the context of the OS main task.
If you do not use the OS default event queue, you must initialize an
event queue and create a task to process events from the queue.
**Note**: If the callback function needs to read another line of
input from the console while processing the current line, it may use
- the ``console_read()`` function to read the next line of input from
- the console. The console will need another ``console_input`` buffer
+ the :c:func:`console_read()` function to read the next line of input from
+ the console. The console will need another :c:data:`console_input` buffer
to store the next input line, so two events, initialized with the
- pointers to the callback and the ``console_input`` buffer, must be
- added to the avail\_queue.
+ pointers to the callback and the :c:data:`console_input` buffer, must be
+ added to the avail_queue.
Here is a code excerpt that shows how to use the
-``console_set_queues()`` function. The example adds one event to the
-avail\_queue and uses the OS default event queue for the lines\_queue.
-
-.. code:: c
+:c:func:`console_set_queues()` function. The example adds one event to the
+avail_queue and uses the OS default event queue for the lines_queue.
+.. code-block:: c
static void myapp_process_input(struct os_event *ev);
@@ -303,89 +300,7 @@ avail\_queue and uses the OS default event queue for the lines\_queue.
console_set_queues(&avail_queue, os_eventq_dflt_get());
}
-Data structures
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-
-The ``struct console_input`` data structure represents a console input
-buffer. Each event added to the console avail\_queue must have the
-``ev_arg`` field point to a ``console_input`` structure.
-
-.. code:: c
-
-
- struct console_input {
- char line[MYNEWT_VAL(CONSOLE_MAX_INPUT_LEN)];
- };
+API
+~~~
-+------------+----------------+
-| Element | Description |
-+============+================+
-| ``line`` | Data buffer |
-| | that the |
-| | console uses |
-| | to save |
-| | received |
-| | characters |
-| | until a new |
-| | line is |
-| | received. |
-+------------+----------------+
-
-List of Functions
-~~~~~~~~~~~~~~~~~
-
-The functions available in console are:
-
-+------------+----------------+
-| Function | Description |
-+============+================+
-| `console\_ | Controls |
-| echo <cons | whether |
-| ole_echo.m | echoing is on |
-| d>`__ | or off for the |
-| | console. |
-+------------+----------------+
-| `console\_ | Initializes |
-| init | the console. |
-| (Mynewt | |
-| 1.0 | |
-| API) <cons | |
-| ole_init.m | |
-| d>`__ | |
-+------------+----------------+
-| `console\_ | Returns a |
-| is\_init < | value |
-| console_is | indicating |
-| _init.html>` | whether the |
-| __ | console has |
-| | been |
-| | initialized or |
-| | not. |
-+------------+----------------+
-| `console\_ | Writes a |
-| printf <co | formatted |
-| nsole_prin | message |
-| tf.html>`__ | instead of raw |
-| | output to the |
-| | console. |
-+------------+----------------+
-| `console\_ | Copies up the |
-| read <cons | to given |
-| ole_read.m | number of |
-| d>`__ | bytes to the |
-| | input string. |
-+------------+----------------+
-| `console\_ | Specifies the |
-| set\_queue | event queues |
-| s <console | for the |
-| _set_queue | console to use |
-| s.html>`__ | to manage |
-| | input data. |
-+------------+----------------+
-| `console\_ | Queues |
-| write <con | characters to |
-| sole_write | console |
-| .html>`__ | display over |
-| | serial port. |
-+------------+----------------+
+.. doxygenfile:: full/include/console/console.h
diff --git a/docs/os/modules/console/console_echo.rst b/docs/os/modules/console/console_echo.rst
deleted file mode 100644
index ae2a3ed2c..000000000
--- a/docs/os/modules/console/console_echo.rst
+++ /dev/null
@@ -1,65 +0,0 @@
-console\_echo
----------------
-
-.. code-block:: console
-
- void console_echo(int on)
-
-Controls whether echoing is on or off for the console. When echoing is
-on, all characters received are transmitted back.
-
-Arguments
-^^^^^^^^^
-
-+-------------+--------------------------------------+
-| Arguments | Description |
-+=============+======================================+
-| on | 1 turns on echoing, 0 turns it off |
-+-------------+--------------------------------------+
-
-Returned values
-^^^^^^^^^^^^^^^
-
-None
-
-Notes
-^^^^^
-
-Example
-^^^^^^^
-
-Here is an example where newtmgr protocol handler is controlling whether
-echoing is on or off. Newtmgr, the tool, turns echoing off when it's
-transmitting large chunks of data to target board.
-
-.. code-block:: console
-
- static int
- nmgr_def_console_echo(struct nmgr_jbuf *njb)
- {
- int echo_on = 1;
- int rc;
- struct json_attr_t attrs[3] = {
- [0] = {
- .attribute = "echo",
- .type = t_integer,
- .addr.integer = &echo_on,
- .nodefault = 1
- },
- [1] = {
- .attribute = NULL
- }
- };
-
- rc = json_read_object(&njb->njb_buf, attrs);
- if (rc) {
- return OS_EINVAL;
- }
-
- if (echo_on) {
- console_echo(1);
- } else {
- console_echo(0);
- }
- return (0);
- }
diff --git a/docs/os/modules/console/console_init.rst b/docs/os/modules/console/console_init.rst
deleted file mode 100644
index bfe6f558b..000000000
--- a/docs/os/modules/console/console_init.rst
+++ /dev/null
@@ -1,47 +0,0 @@
-console\_init
----------------
-
-.. code-block:: console
-
- int
- console_init(console_rx_cb rx_cb)
-
-This function is a Mynewt 1.0 Console API. This function only needs to
-be called if the Mynewt 1.0 console API is used to read input from the
-console input.
-
-If a callback function pointer of ``type void (*console_rx_cb)(void)``
-is specfied, the callback is called when the console receives a full
-line of data.
-
-Note that this function is most likely getting called from an interrupt
-context.
-
-Arguments
-^^^^^^^^^
-
-+-------------+----------------------------------------------------------+
-| Arguments | Description |
-+=============+==========================================================+
-| rx\_cb | Function pointer, which gets called input is received. |
-+-------------+----------------------------------------------------------+
-
-Returned values
-^^^^^^^^^^^^^^^
-
-Returns 0 on success.
-
-Non-zero on failure.
-
-Example
-^^^^^^^
-
-.. code-block:: console
-
- int
- main(int argc, char **argv)
- {
- ....
-
- console_init(NULL);
- }
diff --git a/docs/os/modules/console/console_is_init.rst b/docs/os/modules/console/console_is_init.rst
deleted file mode 100644
index 7a5a31530..000000000
--- a/docs/os/modules/console/console_is_init.rst
+++ /dev/null
@@ -1,38 +0,0 @@
-console\_is\_init
--------------------
-
-.. code-block:: console
-
- int console_is_init(void)
-
-Returns whether console has been initialized or not.
-
-Arguments
-^^^^^^^^^
-
-None
-
-Returned values
-^^^^^^^^^^^^^^^
-
-1 if console has been initialized.
-
-0 if console has not been initialized.
-
-Example
-^^^^^^^
-
-.. code-block:: console
-
- static int
- log_console_append(struct log *log, void *buf, int len)
- {
- ....
-
- if (!console_is_init()) {
- return (0);
- }
-
- /* print log entry to console */
- ....
- }
diff --git a/docs/os/modules/console/console_printf.rst b/docs/os/modules/console/console_printf.rst
deleted file mode 100644
index 684600da8..000000000
--- a/docs/os/modules/console/console_printf.rst
+++ /dev/null
@@ -1,106 +0,0 @@
-console\_printf
-----------------
-
-.. code-block:: console
-
- void
- console_printf(const char *fmt, ...)
-
-Writes a formatted message instead of raw output to the console. It
-first composes a C string containing text specified as arguments to the
-function or containing the elements in the variable argument list passed
-to it using snprintf or vsnprintf, respectively. It then uses function
-``console_write`` to output the formatted data (messages) on the
-console.
-
-Arguments
-^^^^^^^^^
-
-+--------------+----------------+
-| Arguments | Description |
-+==============+================+
-| fmt | Pointer to C |
-| | string that |
-| | contains a |
-| | format string |
-| | that follows |
-| | the same |
-| | specifications |
-| | as format in |
-| | printf. The |
-| | string is |
-| | printed to |
-| | console. |
-+--------------+----------------+
-| ... | Depending on |
-| | the format |
-| | string, the |
-| | function may |
-| | expect either |
-| | a sequence of |
-| | additional |
-| | arguments to |
-| | be used to |
-| | replace a |
-| | format |
-| | specifier in |
-| | the format |
-| | string or a |
-| | variable |
-| | arguments |
-| | list. va\_list |
-| | is a special |
-| | type defined |
-| | in in |
-| | stdarg.h. |
-+--------------+----------------+
-
-Returned values
-^^^^^^^^^^^^^^^
-
-None
-
-Notes
-^^^^^
-
-While ``console_printf``, with its well understood formatting options in
-C, is more convenient and easy on the eyes than the raw output of
-``console_write``, the associated code size is considerably larger.
-
-Example
-^^^^^^^
-
-Example #1:
-
-.. code-block:: console
-
- char adv_data_buf[32];
-
- void
- task()
- {
- char adv_data_buf[32];
-
- console_printf("%s", adv_data_buf);
- }
-
-Example #2:
-
-.. code-block:: console
-
- struct exception_frame {
- uint32_t r0;
- uint32_t r1;
-
- struct trap_frame {
- struct exception_frame *ef;
- uint32_t r2;
- uint32_t r3;
- };
-
- void
- task(struct trap_frame *tf)
- {
- console_printf(" r0:%8.8x r1:%8.8x", tf->ef->r0, tf->ef->r1);
- console_printf(" r8:%8.8x r9:%8.8x", tf->r2, tf->r3);
- }
diff --git a/docs/os/modules/console/console_read.rst b/docs/os/modules/console/console_read.rst
deleted file mode 100644
index 679af4bfe..000000000
--- a/docs/os/modules/console/console_read.rst
+++ /dev/null
@@ -1,84 +0,0 @@
-console\_read
----------------
-
-.. code:: c
-
- int console_read(char *str, int cnt, int *newline)
-
-Copies up to *cnt* bytes of received data to buffer pointed by *str*.
-Function tries to break the input into separate lines; once it
-encounters a newline character, it replaces that with end-of-string and
-returns.
-
-Arguments
-^^^^^^^^^
-
-+--------------+----------------+
-| Arguments | Description |
-+==============+================+
-| ``str`` | Buffer where |
-| | data is copied |
-| | to. |
-+--------------+----------------+
-| ``cnt`` | Maximum number |
-| | of characters |
-| | to copy. |
-+--------------+----------------+
-| ``newline`` | Pointer to an |
-| | integer |
-| | variable that |
-| | is set to 1 |
-| | when an |
-| | newline |
-| | character is |
-| | received and |
-| | set to 0 |
-| | otherwise. |
-+--------------+----------------+
-
-Returned values
-^^^^^^^^^^^^^^^
-
-Returns the number of characters copied. 0 if there was no data
-available, or if the first received character was ':raw-latex:`\n`'.
-
-Example
-^^^^^^^
-
-.. code:: c
-
- #define MAX_INPUT 128
-
- static void
- read_function(void *arg)
- {
- char buf[MAX_INPUT];
- int rc;
- int full_line;
- int off;
-
- off = 0;
- while (1) {
- rc = console_read(buf + off, MAX_INPUT - off, &full_line);
- if (rc <= 0 && !full_line) {
- continue;
- }
- off += rc;
- if (!full_line) {
- if (off == MAX_INPUT) {
- /*
- * Full line, no newline yet. Reset the input buffer.
- */
- off = 0;
- }
- continue;
- }
- /* Got full line - break out of the loop and process the input data */
- break;
- }
-
- /* Process the input line here */
- ....
-
- return;
- }
diff --git a/docs/os/modules/console/console_set_queues.rst b/docs/os/modules/console/console_set_queues.rst
deleted file mode 100644
index d150bf299..000000000
--- a/docs/os/modules/console/console_set_queues.rst
+++ /dev/null
@@ -1,99 +0,0 @@
-console\_set\_queues
-----------------------
-
-.. code:: c
-
- void console_set_queues(struct os_eventq *avail, struct os_eventq *lines)
-
-Sets the event queues that the console uses to manage input data
-buffering and to send notification when a full line of data is received.
-
-The caller must initialize the ``avail`` queue and add at least one
-event to the queue. The event ``ev_cb`` field should point to the
-callback function to call when a full line of data is received, and the
-event ``ev_arg`` should point to a ``console_input`` structure.
-
-The lines queue can be the OS default event queue or an event queue that
-the caller has initialized. If the OS default event queue is specified,
-events from this queue are processed in the context of the OS main task.
-If a different event queue is specified, the call must initialize the
-event queue and a task to process events from the queue.
-
-Arguments
-^^^^^^^^^
-
-+--------------+----------------+
-| Arguments | Description |
-+==============+================+
-| ``avail`` | Event queue to |
-| | queue |
-| | available |
-| | buffer events. |
-| | An event |
-| | indicates that |
-| | the console |
-| | can use the |
-| | buffer from |
-| | event data to |
-| | buffer input |
-| | data until a |
-| | new line is |
-| | received. |
-+--------------+----------------+
-| ``lines`` | Event queue to |
-| | queue full |
-| | line events. |
-| | An event |
-| | indicates that |
-| | a full line of |
-| | input is |
-| | received and |
-| | the event |
-| | callback |
-| | function can |
-| | be called to |
-| | process the |
-| | input line. |
-+--------------+----------------+
-
-Returned values
-^^^^^^^^^^^^^^^
-
-None
-
-Example
-^^^^^^^
-
-.. code:: c
-
-
- #define MAX_CONSOLE_LINES 2
-
- static void myapp_process_input(struct os_event *ev);
-
- static struct os_eventq avail_queue;
-
- static void myapp_process_input(struct os_event *ev);
-
- static struct console_input myapp_console_buf;
-
- static struct console_input myapp_console_buf[MAX_CONSOLE_LINES];
- static struct os_event myapp_console_event[MAX_CONSOLE_LINES];
-
-
- int
- main(int argc, char **argv)
- {
- int i;
-
- os_eventq_init(&avail_queue);
-
- for (i = 0; i < MAX_CONSOLE_LINES; i++) {
- myapp_console_event[i].ev_cb = myapp_process_input;
- myapp_console_event[i].ev_arg = &myapp_console_buf[i];
- os_eventq_put(&avail_queue, &myapp_console_event[i]);
- }
-
- console_set_queues(&avail_queue, os_eventq_dflt_get());
- }
-
diff --git a/docs/os/modules/console/console_write.rst b/docs/os/modules/console/console_write.rst
deleted file mode 100644
index 6b8cfdc43..000000000
--- a/docs/os/modules/console/console_write.rst
+++ /dev/null
@@ -1,47 +0,0 @@
-console\_write
-----------------
-
-.. code-block:: console
-
- void
- console_write(char *str, int cnt)
-
-Queues characters to console display over serial port.
-
-Arguments
-^^^^^^^^^
-
-+-------------+--------------------------------------------------------+
-| Arguments | Description |
-+=============+========================================================+
-| \*str | pointer to the character or packet to be transmitted |
-+-------------+--------------------------------------------------------+
-| cnt | number of characters in *str* |
-+-------------+--------------------------------------------------------+
-
-Returned values
-^^^^^^^^^^^^^^^
-
-N/A
-
-Example
-^^^^^^^
-
-Here is an example of the function being used in an echo command with a
-newline at the end.
-
-.. code-block:: console
-
- static int
- shell_echo_cmd(int argc, char **argv)
- {
- int i;
-
- for (i = 1; i < argc; i++) {
- console_write(argv[i], strlen(argv[i]));
- console_write(" ", sizeof(" ")-1);
- }
- console_write("\n", sizeof("\n")-1);
-
- return (0);
- }
diff --git a/docs/os/os_user_guide.rst b/docs/os/os_user_guide.rst
index 3360f441c..57556fe51 100644
--- a/docs/os/os_user_guide.rst
+++ b/docs/os/os_user_guide.rst
@@ -6,6 +6,7 @@ OS User Guide
OS Core <core_os/mynewt_os>
core_os/porting/port_os
+ modules/console/console
modules/sysinitconfig/sysinitconfig
This guide provides comprehensive information about Mynewt OS, the
diff --git a/sys/console/full/include/console/console.h b/sys/console/full/include/console/console.h
index 7514f227f..533a7f6a4 100644
--- a/sys/console/full/include/console/console.h
+++ b/sys/console/full/include/console/console.h
@@ -6,7 +6,7 @@
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
- *
+ *
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
@@ -29,7 +29,15 @@ extern "C" {
struct os_eventq;
+/** @struct console_input
+ * The console_input data structure represents a console input buffer.
+ *
+ * Each event added to the console avail_queue must have the
+ * ev_arg field point to a console_input structure.
+ */
struct console_input {
+ /** Data buffer that the console uses to save received
+ * characters until a new line is received. */
char line[MYNEWT_VAL(CONSOLE_MAX_INPUT_LEN)];
};
----------------------------------------------------------------
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