You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@nuttx.apache.org by pr...@apache.org on 2020/09/04 23:03:59 UTC
[incubator-nuttx] branch master updated: add quickstart docs from
NuttX Companion
This is an automated email from the ASF dual-hosted git repository.
protobits pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-nuttx.git
The following commit(s) were added to refs/heads/master by this push:
new b88038a add quickstart docs from NuttX Companion
b88038a is described below
commit b88038a1e1dc60f87c4768870f5de9a80201025a
Author: Adam Feuer <ad...@adamfeuer.com>
AuthorDate: Fri Sep 4 14:00:59 2020 -0700
add quickstart docs from NuttX Companion
- with suggested edits from PR feedback
---
Documentation/quickstart/build_and_make.rst | 60 +++++++++
Documentation/quickstart/compiling.rst | 59 +++++++++
Documentation/quickstart/config_build.rst | 131 -------------------
Documentation/quickstart/configuring.rst | 115 ++++++++++++++++
Documentation/quickstart/debugging.rst | 141 ++++++++++++++++++++
Documentation/quickstart/index.rst | 28 ++--
Documentation/quickstart/install.rst | 195 ++++++++++++++++++++++++++++
Documentation/quickstart/organization.rst | 24 +++-
Documentation/quickstart/quickstart.rst | 126 ++++++++++++++++++
Documentation/quickstart/running.rst | 105 +++++++++++++++
10 files changed, 839 insertions(+), 145 deletions(-)
diff --git a/Documentation/quickstart/build_and_make.rst b/Documentation/quickstart/build_and_make.rst
new file mode 100644
index 0000000..d1809af
--- /dev/null
+++ b/Documentation/quickstart/build_and_make.rst
@@ -0,0 +1,60 @@
+.. include:: /substitutions.rst
+.. _build_and_make:
+
+Build and Make Details
+======================
+
+This is included for reference, and it's not necessary to know all these details.
+
+As described in :ref:`compiling`, you use ``make`` at the root ``nuttx/`` directory to build NuttX. This is also
+referenced as ``$(TOPDIR)`` in the ``Makefile``.
+
+Root Directory
+--------------
+
+The ``$(TOPDIR)`` directory holds:
+
+- The top level ```Makefile`` <#topmakefile>`__ that controls the
+ NuttX build.
+
+That directory also holds:
+
+- The makefile fragment ```.config`` <#boardconfigsubdirs>`__
+ that describes the current configuration, and
+- The makefile fragment ```Make.defs`` <#boardconfigsubdirs>`__
+ that provides customized build targets.
+
+Environment Variables
+---------------------
+
+The specific environmental definitions
+are unique for each board but should include, as a minimum,
+updates to the ``PATH`` variable to include the full path to the
+architecture-specific toolchain identified in
+```Make.defs`` <#boardconfigsubdirs>`__.
+
+
+First Time Make
+---------------
+
+Additional configuration actions will be taken the first time that system is built. These additional steps
+include:
+
+- Auto-generating the file ``include/nuttx/config.h`` using the
+ ``$(TOPDIR)/.config`` file.
+- Auto-generating the file ``$(TOPDIR)/.version`` with version
+ 0.0 if one does not exist.
+- Auto-generating the file ``include/nuttx/version.h`` using the
+ ``$(TOPDIR)/.version`` file.
+- Creating a link to
+ ``$(TOPDIR)/arch/``\ *<arch-name>*\ ``/include`` at
+ ``$(TOPDIR)/include/arch``.
+- Creating a link to
+ ``$(TOPDIR)/boards/``\ *<arch-name>*\ ``/``\ *<chip-name>*\ ``/``\ *<board-name>*\ ``/include``
+ at ``$(TOPDIR)/include/arch/board``.
+- Creating a link to
+ ``$(TOPDIR)/boards/``\ *<arch-name>*\ ``/``\ *<chip-name>*\ ``/``\ *<board-name>*\ ``/src``
+ at ``$(TOPDIR)/arch/``\ *<arch-name>*\ ``/src/board``
+- Creating a link to ``${APPDIR}/include`` at
+ ``$(TOPDIR)/include/apps``
+- Creating make dependencies.
diff --git a/Documentation/quickstart/compiling.rst b/Documentation/quickstart/compiling.rst
new file mode 100644
index 0000000..b743936
--- /dev/null
+++ b/Documentation/quickstart/compiling.rst
@@ -0,0 +1,59 @@
+.. include:: /substitutions.rst
+.. _compiling:
+
+Compiling
+=========
+
+Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
+into an executable binary file that can be run on the embedded board.
+
+#. List Possible Apache NuttX Base Configurations
+
+ Find your hardware and a good starting application in the list of base configurations. In the application list,
+ ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+
+ .. code-block:: bash
+
+ $ cd nuttx
+ $ ./tools/configure.sh -L | less
+
+#. Initialize Configuration
+
+ Pick one of the board:application base configuration pairs from the list, and feed it to the
+ configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
+ possible, this guide doesn't cover them yet.
+
+ .. code-block:: bash
+
+ $ cd nuttx
+ $ # this is the basic layout of the command:
+ $ # ./tools/configure.sh -l <board-name>:<config-dir>
+ $ # for example:
+ $ ./tools/configure.sh -l sama5d2-xult:nsh
+
+#. Customize Your Configuration (Optional)
+
+ This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
+ any of the options now, but knowing how to do this will come in handy later.
+
+ There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+
+ .. code-block:: bash
+
+ $ make menuconfig
+
+#. Compile NuttX
+
+ .. code-block:: bash
+
+ $ make clean; make
+
+#. Install the Executable Program on Your Board
+
+ This step is a bit more complicated, depending on your board. It's covered in the section
+ :ref:`Running Apache NuttX <running>`.
+
+----
+
+Next up is :ref:`running`.
+
diff --git a/Documentation/quickstart/config_build.rst b/Documentation/quickstart/config_build.rst
deleted file mode 100644
index 6b5331d..0000000
--- a/Documentation/quickstart/config_build.rst
+++ /dev/null
@@ -1,131 +0,0 @@
-========================
-Configuring and Building
-========================
-
-Configuring NuttX
-=================
-
-**Manual Configuration**. Configuring NuttX requires only copying
-the `board-specific configuration files <#boardconfigsubdirs>`__
-into the top level directory which appears in the make files as
-the make variable, ``$(TOPDIR)``. This could be done manually as
-follows:
-
-- Copy
- ``boards/``\ *<arch-name>*\ ``/``\ *<chip-name>*\ ``/``\ *<board-name>*\ ``/configs/[``\ *<config-dir>*\ ``/]Make.defs``
- to ``$(TOPDIR)/Make.defs`` (see NOTE below),
-- Copy
- ``boards/``\ *<arch-name>*\ ``/``\ *<chip-name>*\ ``/``\ *<board-name>*\ ``/configs/[``\ *<config-dir>*\ ``/]defconfig``
- to ``$(TOPDIR)/.config``
-
-Where *<board-name>* is the name of one of the sub-directories of
-the NuttX ```boards/`` <#DirStructConfigs>`__ directory. This
-sub-directory name corresponds to one of the supported boards
-identified `above <#supportedboards>`__. <config-dir> is the
-optional, specific configuration directory for the board. And
-<app-dir> is the location of the optional application directory.
-
-NOTE: Recall that the ``Make.defs`` file may reside in either the
-``boards/``\ *<arch-name>*\ ``/``\ *<chip-name>*\ ``/``\ *<board-name>*/``configs/[``\ *<config-dir>*
-directory or in the
-``boards/``\ *<arch-name>*\ ``/``\ *<chip-name>*\ ``/``\ *<board-name>*/``scripts``.
-
-**Automated Configuration**. There is a script that automates
-these steps. The following steps will accomplish the same
-configuration:
-
-There is an alternative Windows batch file, ``configure.bat``,
-that can be used instead of ``configure.sh`` in the windows native
-environment like:
-
-And, to make sure that other platforms are supported, there is
-also a C program at ``tools/configure.c`` that can be compiled to
-establish the board configuration on all platforms.
-
- NOTE (2019-08-6): As of this writing, changes to the boards/
- directly have made ``configure.bat`` unusable. For the native
- Windows environment, ``configure.c`` is recommended until that
- batch file can be repaired.
-
-See ``tools/README.txt`` for more information about these scripts.
-Or use the -h option with ``configure.sh>``
-
-If your application directory is not in the standard location
-(``../apps`` or ``../apps-<version>``), then you should also
-specify the location of the application directory on the command
-line like:
-
-**Version Files**. The NuttX build expects to find a version file
-located in the top-level NuttX build directory. That version file
-is called ``.version``. The correct version file is installed in
-each versioned NuttX released. However, if you are working from an
-GIT snapshot, then there will be no version file. If there is no
-version file, the top-level ``Makefile`` will create a dummy
-``.version`` file on the first make. This dummy version file will
-contain all zeroes for version information. If that is not what
-you want, they you should run the ``version.sh`` script to create
-a better ``.version`` file.
-
-You can get help information from the ``version.sh`` script using
-the ``-h`` option. For example:
-
-As an example, the following command will generate a version file
-for version 6.1 using the current GIT revision number:
-
-The ``.version`` file is also used during the build process to
-create a C header file at ``include/nuttx/version.h`` that
-contains the same version information. That version file may be
-used by your C applications for, as an example, reporting version
-information.
-
-**Additional Configuration Steps**. The remainder of configuration
-steps will be performed by
-```$(TOPDIR)/Makefile`` <#topmakefile>`__ the first time the
-system is built as described below.
-
-Building NuttX
-==============
-
-**Building NuttX**. Once NuttX has been configured as described
-`above <#configuringnuttx>`__, it may be built as follows:
-
-The ``$(TOPDIR)`` directory holds:
-
-- The top level ```Makefile`` <#topmakefile>`__ that controls the
- NuttX build.
-
-That directory also holds:
-
-- The makefile fragment ```.config`` <#boardconfigsubdirs>`__
- that describes the current configuration, and
-- The makefile fragment ```Make.defs`` <#boardconfigsubdirs>`__
- that provides customized build targets.
-
-**Environment Variables**. The specific environmental definitions
-are unique for each board but should include, as a minimum,
-updates to the ``PATH`` variable to include the full path to the
-architecture-specific toolchain identified in
-```Make.defs`` <#boardconfigsubdirs>`__.
-
-**First Time Make.** Additional configuration actions will be
-taken the first time that system is built. These additional steps
-include:
-
-- Auto-generating the file ``include/nuttx/config.h`` using the
- ``$(TOPDIR)/.config`` file.
-- Auto-generating the file ``$(TOPDIR)/.version`` with version
- 0.0 if one does not exist.
-- Auto-generating the file ``include/nuttx/version.h`` using the
- ``$(TOPDIR)/.version`` file.
-- Creating a link to
- ``$(TOPDIR)/arch/``\ *<arch-name>*\ ``/include`` at
- ``$(TOPDIR)/include/arch``.
-- Creating a link to
- ``$(TOPDIR)/boards/``\ *<arch-name>*\ ``/``\ *<chip-name>*\ ``/``\ *<board-name>*\ ``/include``
- at ``$(TOPDIR)/include/arch/board``.
-- Creating a link to
- ``$(TOPDIR)/boards/``\ *<arch-name>*\ ``/``\ *<chip-name>*\ ``/``\ *<board-name>*\ ``/src``
- at ``$(TOPDIR)/arch/``\ *<arch-name>*\ ``/src/board``
-- Creating a link to ``${APPDIR}/include`` at
- ``$(TOPDIR)/include/apps``
-- Creating make dependencies.
diff --git a/Documentation/quickstart/configuring.rst b/Documentation/quickstart/configuring.rst
new file mode 100644
index 0000000..19fa3a7
--- /dev/null
+++ b/Documentation/quickstart/configuring.rst
@@ -0,0 +1,115 @@
+.. include:: /substitutions.rst
+.. _configuring:
+
+Configuring
+===========
+
+Apache NuttX is a very configurable operating system. Nearly all features can be configured in or
+out of the system. This makes it possible to compile a build tailored for your hardware and
+application. It also makes configuring the system complex at times.
+
+There is a configuration system that can be used on the commandline or in a GUI. I've found
+the easiest way to configured Apache NuttX is to use the ``menuconfig`` system. This is used
+via a terminal program and allows quick access to all of Apache NuttX's features via a system of
+menus.
+
+The Apache NuttX configuration system uses Linux's
+`kconfig system <https://www.kernel.org/doc/Documentation/kbuild/kconfig-language.txt>`_ adapted for use with Apache
+NuttX. Here's info on Linux's kconfig `menuconfig <https://en.wikipedia.org/wiki/Menuconfig>`_ system.
+
+After you've configured your board (see :ref:`compiling`), you can use the menuconfig system
+to change the configuration. Once you've configured, you can compile to make a build that
+has your configuration options selected.
+
+#. Initialize Board Configuration
+
+ Here we'll use the simulator since that's the simplest to explain. You can do this with
+ any board and base configuration. Note here you should be supplying `configure.sh` the correct flag
+ for your build environment:
+
+ .. code-block:: bash
+
+ -l selects the Linux (l) host environment.
+ -m selects the macOS (m) host environment.
+ -c selects the Windows host and Cygwin (c) environment.
+ -u selects the Windows host and Ubuntu under Windows 10 (u) environment.
+ -g selects the Windows host and MinGW/MSYS environment.
+ -n selects the Windows host and Windows native (n) environment.
+
+ Select the simulator configuration for a Linux host:
+
+ .. code-block:: bash
+
+ $ cd nuttx
+ $ make distclean # make a clean start, clearing out old configurations
+ $ ./tools/configure.sh -l sim:nsh
+ Copy files
+ Select CONFIG_HOST_LINUX=y
+ Refreshing...
+#. Make
+
+ .. code-block:: bash
+
+ $ make clean; make
+ $ ./nuttx
+ login:
+
+ From another terminal window, kill the simulator:
+
+ .. code-block:: bash
+
+ $ pkill nuttx
+
+#. Menu Configuration
+
+ Showing that ``login:`` is annyoing. Let's use the ``menuconfig`` system to turn it off.
+
+ .. code-block:: bash
+
+ $ make menuconfig
+
+ Here's what you should see:
+
+ .. image:: ../images/menuconfig.png
+ :width: 800px
+ :align: center
+ :alt: Screenshot of menuconfig system main screen
+
+ |br|
+
+#. Application Configuration
+
+ The NSH Login setting is under ``Application Configuration > NSH Library``. Use
+ the up and down arrows to navigate to ``Application Configuration``; hit ``<return>`` to
+ select it. Now you're in the ``Application Configuration`` menu. Use the arrows to go
+ down to ``NSH Library`` and select that. Now navigate down to ``Console Login`` and use
+ the spacebar to uncheck that setting (so that it has a blank space instead of a star in it).
+
+ Now let's save. Use the right and left arrow keys to select the ``Exit`` menu item at the
+ bottom of the screen. Hit ``<return>`` to select it, hit ``<return>`` again, and again, finally
+ hitting ``<return>`` in the ``Save Configuration`` dialog box.
+ |br|
+ |br|
+
+#. Make the New Configuration
+
+ .. code-block:: bash
+
+ $ make clean; make
+
+#. Run
+
+ .. code-block:: bash
+
+ $ ./nuttx
+ NuttShell (NSH) NuttX-8.2
+ MOTD: username=admin password=Administrator
+
+ Success!
+
+ If you find that message of the day (MOTD) annoying and want to turn that off, it's
+ configured in ``Application Configuration > NSH Library >> Message of the Day (MOTD)``.
+
+----
+
+Next up is :ref:`debugging`.
diff --git a/Documentation/quickstart/debugging.rst b/Documentation/quickstart/debugging.rst
new file mode 100644
index 0000000..94aa29e
--- /dev/null
+++ b/Documentation/quickstart/debugging.rst
@@ -0,0 +1,141 @@
+.. include:: /substitutions.rst
+.. _debugging:
+
+Debugging
+=========
+
+Finding and fixing bugs is an important part of the hardware and software development process. Sometimes you also need
+to use debugging techniques to understand how the system works. Two tools that are helpful are debug logging and
+debugging using the Gnu Debugger (gdb).
+
+Debug Logging
+-------------
+
+NuttX has a powerful logging facility with ``info``, ``warn``, and ``error`` levels. You can enable debugging for your
+build for the ``net`` feature (TCP/IP stack) by putting the following lines in your ``.config`` file:
+
+ ::
+
+ CONFIG_DEBUG_ALERT=y
+ CONFIG_DEBUG_FEATURES=y
+ CONFIG_DEBUG_ERROR=y
+ CONFIG_DEBUG_WARN=y
+ CONFIG_DEBUG_INFO=y
+ CONFIG_DEBUG_ASSERTIONS=y
+ CONFIG_DEBUG_NET=y
+ CONFIG_DEBUG_NET_ERROR=y
+ CONFIG_DEBUG_NET_WARN=y
+ CONFIG_DEBUG_NET_INFO=y
+ CONFIG_DEBUG_SYMBOLS=y
+ CONFIG_DEBUG_NOOPT=y
+ CONFIG_SYSLOG_TIMESTAMP=y
+
+Note that turning all these to ``y`` will produce an incredible amount of logging output. Set the level you want and
+the area you're interested in to ``y``, and the rest to ``n``, and then recompile. You can see the full list of
+debug feature areas in the file `debug.h <https://github.com/apache/incubator-nuttx/blob/master/include/debug.h>`__.
+
+Timestamps can be enabled by setting ``CONFIG_SYSLOG_TIMESTAMP=y``.
+
+You may need to do a little bit of experimenting to find the combination of logging settings that work for the problem
+you're trying to solve. See the file `debug.h <https://github.com/starcat-io/incubator-nuttx/blob/master/include/debug.h>`_
+for available debug settings that are available. This can also be configured via the ``menuconfig`` system.
+
+There are also subsystems that enable USB trace debugging, and you can log to memory too, if you need the logging to be
+faster than what the console can output.
+
+Changing Debug Settings Quickly
+-------------------------------
+
+You can use the ``kconfig-tweak`` script that comes with the ``kconfig-frontends`` tools to quickly change debug settings,
+for instance turning them on or off before doing a build:
+
+.. code-block:: bash
+
+ $ kconfig-tweak --disable CONFIG_DEBUG_NET
+ $ kconfig-tweak --enable CONFIG_DEBUG_NET
+
+You can put a bunch of these into a simple script to configure the logging the way you want:
+
+.. code-block:: bash
+
+ #!/bin/bash
+
+ $ kconfig-tweak --disable CONFIG_DEBUG_ALERT
+ $ kconfig-tweak --disable CONFIG_DEBUG_FEATURES
+ $ kconfig-tweak --disable CONFIG_DEBUG_ERROR
+ $ kconfig-tweak --disable CONFIG_DEBUG_WARN
+ $ kconfig-tweak --disable CONFIG_DEBUG_INFO
+ $ kconfig-tweak --disable CONFIG_DEBUG_ASSERTIONS
+ $ kconfig-tweak --disable CONFIG_DEBUG_NET
+ $ kconfig-tweak --disable CONFIG_DEBUG_NET_ERROR
+ $ kconfig-tweak --disable CONFIG_DEBUG_NET_WARN
+ $ kconfig-tweak --disable CONFIG_DEBUG_NET_INFO
+ $ kconfig-tweak --disable CONFIG_DEBUG_SYMBOLS
+ $ kconfig-tweak --disable CONFIG_DEBUG_NOOPT
+ $ kconfig-tweak --disable CONFIG_SYSLOG_TIMESTAMP
+
+Custom Debug Logging
+--------------------
+
+Sometimes you need to see debug logs specific to your feature, and you don't want the rest of the built-in logs
+because they're either not relevant or have too much information. Debugging using logs is surprisingly powerful.
+
+
+You can add your own custom debug logging by adding the following lines to
+`debug.h <https://github.com/apache/incubator-nuttx/blob/master/include/debug.h>`__:
+
+.. code-block:: c
+
+ /* after the CONFIG_DEBUG_WATCHDOG_INFO block near line 721 */
+ #ifdef CONFIG_DEBUG_CUSTOM_INFO
+ # define custinfo _info
+ #else
+ # define custinfo _none
+ #endif
+
+You need to add the following line to your ``.config`` file:
+
+.. code-block:: c
+
+ CONFIG_DEBUG_CUSTOM_INFO=y
+
+You would use it like this:
+
+.. code-block:: c
+
+ /* Custom debug logging */
+ custinfo("This is a custom log message.");
+ custinfo("Custom log data: %d", my-integer-variable);
+
+
+JTAG Debugging
+--------------
+
+`JTAG <https://en.wikipedia.org/wiki/JTAG>`_ is a set of standards that specify a way to attach a hardware device to
+your embedded board, and then remotely control the CPU. You can load code, start, stop, step through the program, and
+examine variables and memory.
+
+This guide assumes your board has a JTAG connector, and you have a JTAG hardware debugger like a
+`Segger J-Link <https://www.segger.com/products/debug-probes/j-link/>`_ or `OpenOCD <http://openocd.org/doc-release/html/index.html>`_.
+
+The NuttX operating system uses `threads <https://en.wikipedia.org/wiki/Thread_(computing)>`_, so you need a
+thread-aware debugger to do more than load code, start, and stop it. A thread-aware debugger will allow you to switch
+threads to the one that is running the code you're interested in, for instance your application, or an operating system
+network thread. So far, OpenOCD is the only supported NuttX thread-aware debugger.
+
+You will need an OpenOCD-compatible hardware adapter, ideally a fast one (USB 2.0 High Speed). This guide assumes you
+are using the `Olimex ARM USB TINY H <https://www.olimex.com/Products/ARM/JTAG/ARM-USB-TINY-H/>`_.
+(`Olimex ARM USB TINY H on Amazon <https://smile.amazon.com/Olimex-ARM-USB-TINY-H-Arm-Jtag/dp/B009UED630/>`_.) Other
+adapters may work, follow the OpenOCD instructions and the instructions that came with your adapter.
+
+You'll need to use the `Sony fork of OpenOCD <https://github.com/sony/openocd-nuttx>`_. Download and install it
+according to the OpenOCD instructions.
+
+See this article for more info:
+`Debugging a Apache NuttX target with GDB and OpenOCD <https://micro-ros.github.io/docs/tutorials/advanced/debugging_gdb_openocd/>`_.
+
+See the section :ref:`Running <running>` for a brief tutorial on how to use GDB.
+
+----
+
+Next up is :ref:`organization`.
diff --git a/Documentation/quickstart/index.rst b/Documentation/quickstart/index.rst
index 70423f9..aab8cf2 100644
--- a/Documentation/quickstart/index.rst
+++ b/Documentation/quickstart/index.rst
@@ -1,16 +1,28 @@
.. todo::
- This should be a brief introduction to how NuttX works and how to get it running. A widely used board could be targeted to create a brief demonstration on how to clone, configure, build, flash and run NuttX.
- For now, the content that is here presented is what remains of the old Porting Guide which is not already in another section of this documentation.
-==========
-Quickstart
-==========
+===============
+Getting Started
+===============
-The present Quickstart guide is a work in progress and only contains some basic information. In the meantime you can look at NuttX main `README <https://github.com/apache/incubator-nuttx/blob/master/README.md>`_ file which contains some information that will help you get started.
+This section describes how to get started with NuttX. :ref:`quickstart/quickstart:Quickstart` is for
+experienced embedded developers, and quickly outlines the basic of getting NuttX configured and
+compiled. Use this if you are experienced with FreeRTOS, Zephyr, or a similar RTOS.
+
+The remaining sections are detailed instructions aimed at beginners for getting the necessary
+compilers and other tools installed, then compiling NuttX and running on your hardware. There are sections
+on configuring NuttX with more features than just the minimum, and a section on debugging. For reference
+there is also a description of the code organization and some details about what happens when running ``make``
+to build NuttX.
.. toctree::
:maxdepth: 1
+ quickstart.rst
+ install.rst
+ compiling.rst
+ running.rst
+ configuring.rst
+ debugging.rst
organization.rst
- config_build.rst
-
+ build_and_make.rst
+
diff --git a/Documentation/quickstart/install.rst b/Documentation/quickstart/install.rst
new file mode 100644
index 0000000..a844a9e
--- /dev/null
+++ b/Documentation/quickstart/install.rst
@@ -0,0 +1,195 @@
+.. include:: /substitutions.rst
+.. _install:
+
+Installing
+==========
+
+To start developing on Apache NuttX, we need to get the source code, configure it, compile it, and get it uploaded onto an
+embedded computing board. These instructions are for `Ubuntu <https://ubuntu.com/>`_ Linux and macOS Catalina. If you're using a different
+version, you may need to change some of the commands.
+
+Prerequisites
+-------------
+
+Install prerequisites for building using Linux
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+#. Install system packages
+
+ .. code-block:: bash
+
+ $ sudo apt install \
+ bison flex gettext texinfo libncurses5-dev libncursesw5-dev \
+ gperf automake libtool pkg-config build-essential gperf \
+ libgmp-dev libmpc-dev libmpfr-dev libisl-dev binutils-dev libelf-dev \
+ libexpat-dev gcc-multilib g++-multilib picocom u-boot-tools util-linux
+
+
+#. Give yourself access to the serial console device
+
+ This is done by adding your Linux user to the ``dialout`` group:
+
+ .. code-block:: bash
+
+ $ sudo usermod -a -G dialout $USER
+ $ # now get a login shell that knows we're in the dialout group:
+ $ su - $USER
+
+Install prerequisites for building and using Apache NuttX (macOS)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ .. code-block:: bash
+
+ $ brew tap discoteq/discoteq
+ $ brew install flock
+ $ brew install x86_64-elf-gcc # Used by simulator
+ $ brew install u-boot-tools # Some platform integrate with u-boot
+
+Install prerequisites for building and using Apache NuttX (Windows -- WSL)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you are are building Apache NuttX on windows and using WSL follow
+that installation guide for Linux. This has been verified against the
+Ubunutu 18.04 version.
+
+There may be complications interacting with
+programming tools over USB. Recently support for USBIP was added to WSL 2
+which has been used with the STM32 platform, but it is not trivial to configure:
+https://github.com/rpasek/usbip-wsl2-instructions
+
+Install prerequisites for building and using Apache NuttX (Windows -- Cygwin)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Download and install `Cygwin <https://www.cygwin.com/>`_ using the minimal
+installation in addition to these packages::
+
+ make bison libmpc-devel
+ gcc-core byacc automake-1.15
+ gcc-g++ gperf libncurses-devel
+ flex gdb libmpfr-devel
+ git unzip zlib-devel
+
+Install Required Tools (All Platforms)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There are a collection of required tools that need to be built to build most Apache NuttX configurations:
+
+ .. code-block:: bash
+
+ $ mkdir buildtools
+ $ export NUTTXTOOLS=`pwd`/buildtools
+ $ export NUTTXTOOLS_PATH=$NUTTXTOOLS/bin:$NUTTXTOOLS/usr/bin
+ $ git clone https://bitbucket.org/nuttx/tools.git tools
+
+*NOTE:* You will need to add ``NUTTXTOOLS_PATH`` to your environment ``PATH``
+
+#. Install kconfig-frontends tool
+
+This is necessary to run the ``./nuttx/tools/configure.sh`` script as well as using the ncurses-based menuconfig system.
+
+ .. code-block:: bash
+
+ $ cd tools/
+ $ cd kconfig-frontends
+ $ # on MacOS do the following:
+ $ patch < ../kconfig-macos.diff -p 1
+ $ ./configure --prefix=$NUTTXTOOLS --enable-mconf --disable-shared --enable-static --disable-gconf --disable-qconf --disable-nconf
+ $ # on Linux do the following:
+ $ ./configure --prefix=$NUTTXTOOLS --enable-mconf --disable-gconf --disable-qconf
+ $ touch aclocal.m4 Makefile.in
+ $ make
+ $ make install
+
+#. Install gperf tool
+
+ This required to build ``kconfig-frontends``.
+
+ .. code-block:: bash
+
+ $ cd tools/
+ $ wget http://ftp.gnu.org/pub/gnu/gperf/gperf-3.1.tar.gz
+ $ tar zxf gperf-3.1.tar.gz
+ $ cd gperf-3.1
+ $ ./configure --prefix=$NUTTXTOOLS
+ $ make
+ $ make install
+
+#. Install gen-romfs (optional)
+
+
+ This is required if you want to build ROM-based file systems.
+
+ .. code-block:: bash
+
+ $ cd tools/
+ $ tar zxf genromfs-0.5.2.tar.gz
+ $ cd genromfs-0.5.2
+ $ make install PREFIX=$NUTTXTOOLS
+
+Get Source Code (Stable)
+------------------------
+Apache NuttX releases are published on the project `Downloads <https://nuttx.apache.org/download/>`_ page and distributed
+by the Apache mirrors. Be sure to download both the nuttx and apps tarballs.
+
+
+Get Source Code (Development)
+------------------------------
+Apache NuttX is `actively developed on GitHub <https://github.com/apache/incubator-nuttx/>`_. If you want
+to use it, modify it or help develop it, you'll need the source code.
+
+You can either clone the public repositories:
+
+ .. code-block:: bash
+
+ $ mkdir nuttx
+ $ cd nuttx
+ $ git clone https://github.com/apache/incubator-nuttx.git nuttx
+ $ git clone https://github.com/apache/incubator-nuttx-apps apps
+
+Or, download the `tarball <https://github.com/apache/incubator-nuttx/tarball/master>`_:
+
+ .. code-block:: bash
+
+ $ curl -OL https://github.com/apache/incubator-nuttx/tarball/master
+ $ curl -OL https://github.com/apache/incubator-nuttx-apps/tarball/master
+ # optionally, zipball is also available (for Windows users).
+
+Later if we want to make modifications (for instance, to improve NuttX and save them in our own branch,
+or submit them back to the project), we can do that easily using git to track our changes and submit them
+upstream to the NuttX project.
+
+Install a Cross-Compiler Toolchain
+----------------------------------
+
+With Apache NuttX, you compile the operating system and your application on your desktop or laptop computer, then install the
+binary file on your embedded computer. This guide assumes your computer is an
+`ARM <https://en.wikipedia.org/wiki/ARM_architecture>`_ CPU. If it isn't, you'll need a different tool chain.
+
+ There are hints on how to get the latest tool chains for most supported architectures in the Apache NuttX CI helper
+ `script <https://github.com/apache/incubator-nuttx-testing/blob/master/cibuild.sh>`_ and Docker `container <https://github.com/apache/incubator-nuttx-testing/blob/master/docker/linux/Dockerfile>`_
+
+Download the right flavor of the
+`ARM Embedded Gnu Toolchain <https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm>`_
+for your embedded processor's CPU.
+
+Unpack it into ``/opt/gcc`` and add the bin directory to your path. For instance:
+
+ .. code-block:: bash
+
+ $ usermod -a -G users $USER
+ $ # get a login shell that knows we're in this group:
+ $ su - $USER
+ $ sudo mkdir /opt/gcc
+ $ sudo chgrp -R users /opt/gcc
+ $ sudo chmod -R u+rw /opt/gcc
+ $ cd /opt/gcc
+ $ HOST_PLATFORM=x86_64-linux # use "mac" for macOS.
+ $ # For windows there is a zip instead (gcc-arm-none-eabi-9-2019-q4-major-win32.zip)
+ $ curl -L -o gcc-arm-none-eabi-9-2019-q4-major-${HOST_PLATFORM}.tar.bz2 https://developer.arm.com/-/media/Files/downloads/gnu-rm/9-2019q4/gcc-arm-none-eabi-9-2019-q4-major-${HOST_PLATFORM}.tar.bz2
+ $ tar xf gcc-arm-none-eabi-9-2019-q4-major-${HOST_PLATFORM}.tar.bz2
+ $ # add the toolchain bin/ dir to your path...
+ $ # you can edit your shell's rc files if you don't use bash
+ $ echo "export PATH=/opt/gcc/gcc-arm-none-eabi-9-2019-q4-major/bin:$PATH" >> ~/.bashrc
+
+----
+
+Next up is :ref:`compiling`.
diff --git a/Documentation/quickstart/organization.rst b/Documentation/quickstart/organization.rst
index 03af58c..82a5a15 100644
--- a/Documentation/quickstart/organization.rst
+++ b/Documentation/quickstart/organization.rst
@@ -1,8 +1,14 @@
+.. include:: /substitutions.rst
+.. _organization:
+
===================
Directory Structure
===================
-**Directory Structure**. The general directory layout for NuttX is
+This is included for reference, and it's not necessary to know
+all the details at first.
+
+The general directory layout for NuttX is
very similar to the directory structure of the Linux kernel -- at
least at the most superficial layers. At the top level is the main
makefile and a series of sub-directories identified below and
@@ -62,10 +68,12 @@ specified by several settings in the NuttX configuration file.
board and is selected via the
``CONFIG_ARCH_BOARD="stm32f4discovery"`` configuration setting.
-Documentation
-=============
+``nuttx/Documentation``
+=======================
-General documentation for the NuttX OS resides in this directory.
+This directory holds the NuttX documentation. It's made with
+the `Sphinx documentation system <https://www.sphinx-doc.org>`_. See the
+README.md file for information on how to build it.
``nuttx/arch``
==============
@@ -221,8 +229,8 @@ Current architecture/chip directories are summarized below:
At present, this includes the Zilog z80, ez80Acclaim! and
z8Encore! Microcontrollers.
-nuttx/binfmt
-============
+``nuttx/binfmt``
+================
The ``binfmt/`` subdirectory contains logic for loading binaries
in the file system into memory in a form that can be used to
@@ -499,3 +507,7 @@ The top-level ``Makefile`` in the ``$(TOPDIR)`` directory contains
all of the top-level control logic to build NuttX. Use of this
``Makefile`` to build NuttX is described
`below <#buildingnuttx>`__.
+
+----
+
+Next up is :ref:`build_and_make`.
diff --git a/Documentation/quickstart/quickstart.rst b/Documentation/quickstart/quickstart.rst
new file mode 100644
index 0000000..be38a07
--- /dev/null
+++ b/Documentation/quickstart/quickstart.rst
@@ -0,0 +1,126 @@
+.. include:: /substitutions.rst
+.. _quickstart:
+
+Quickstart
+==========
+
+Here's the quick version of getting started with NuttX. This is a bare-bones outline for experienced developers– if it's
+going too quickly, dive into the following sections. This Quickstart guide assumes you're on a Linux
+computer, you're using an ARM microcontroller on your embedded board, and you're familiar with using the command line.
+
+#. Install a Cross-Compiler Toolchain
+
+ With NuttX, you compile the operating system and your application on your desktop or laptop computer, then install the
+ binary file on your embedded computer. This guide assumes your computer is an
+ `ARM <https://en.wikipedia.org/wiki/ARM_architecture>`_ CPU. If it isn't, you'll need a different tool chain.
+
+ You can download a toolchain from
+ `ARM Embedded Gnu Toolchain <https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm>`_
+ for your embedded processor's CPU. You can also use a toolchain shipped with your OS for the `none-eabi` target, such as `gcc-arm-none-eabi` in Linux.
+
+
+In the following example, we download ``gcc-arm-none-eabi`` version 9.0 and unpack it into ``/opt/gcc`:
+
+ .. code-block:: console
+
+ $ sudo mkdir /opt/gcc
+ $ sudo chgrp -R users /opt/gcc
+ $ cd /opt/gcc
+ $ wget https://developer.arm.com/-/media/Files/downloads/gnu-rm/9-2019q4/gcc-arm-none-eabi-9-2019-q4-major-x86_64-linux.tar.bz2
+ $ tar xf gcc-arm-none-eabi-9-2019-q4-major-x86_64-linux.tar.bz2
+
+Then, add the toolchain ``bin/`` directory to your path:
+
+.. code-block:: console
+
+ $ echo "export PATH=/opt/gcc/gcc-arm-none-eabi-9-2019-q4-major/bin:$PATH" >> ~/.bashrc
+
+If you are using any other shell, the procedure is similar by editing the corresponding rc file.
+
+#. Download Apache NuttX
+The next step is to download NuttX main repository along the application repository. The latter is technically optional in a very minimal configurations but should be included in normal configuration since it includes the NuttX shell.
+ .. code-block:: console
+
+ $ mkdir nuttx
+ $ cd nuttx
+ $ git clone https://github.com/apache/incubator-nuttx.git nuttx
+ $ git clone https://github.com/apache/incubator-nuttx-apps apps
+ $ git clone https://bitbucket.org/nuttx/tools.git tools
+
+#. Install the ``kconfig-frontends`` package
+
+ NuttX is configured using ``kconfig`` system via an interactive menu system (``menuconfig``). It also includes the ``kconfig-tweak`` utility that can be used to quickly change debug settings without going into the menu system.
+
+
+ On Ubuntu 20.04 LTS and later, you can do:
+
+ .. code-block:: console
+
+ $ apt install kconfig-frontends
+
+ On MacOS, and Ubuntu 18.04 LTS and earlier, you need to install manually:
+
+ .. code-block:: console
+
+ $ cd tools/kconfig-frontends
+ $ # on MacOS do the following:
+ $ patch < ../kconfig-macos.diff -p 1
+ $ ./configure --enable-mconf --disable-shared --enable-static --disable-gconf --disable-qconf --disable-nconf
+ $ # on Linux do the following:
+ $ ./configure --enable-mconf --disable-nconf --disable-gconf --disable-qconf
+ $ make
+ $ make install
+
+#. List Possible Apache NuttX Base Configurations
+
+ Find your hardware and a good starting application in the list of base configurations. In the application list,
+ ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+
+ .. code-block:: bash
+
+ $ cd nuttx
+ $ ./tools/configure.sh -L | less
+
+#. Initialize Configuration
+
+ Pick one of the board:application base configuration pairs from the list, and feed it to
+ the configuration script. The ``-l`` tells us that we're on Linux. macOS and Windows builds
+ are possible, this guide doesn't cover them yet.
+
+ .. code-block:: bash
+
+ $ cd nuttx
+ $ ./tools/configure.sh -l <board-name>:<config-dir>
+ # for instance:
+ $ ./tools/configure.sh -l sama5d27-xult:nsh
+
+#. Customize Your Configuration (Optional)
+
+ This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
+ any of the options now, but knowing how to do this will come in handy later.
+
+ There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+
+ .. code-block:: bash
+
+ $ make menuconfig
+
+Use your arrows to navigate the menu and ``ENTER`` key to enable/disable options. To exit and save your configuration, go back to the main menu, choose ``<Exit>`` and select "yes" when asked if you want to save.
+
+#. Compile Apache NuttX
+
+ .. code-block:: bash
+
+ $ make
+
+#. Install the Executable Program on Your Board
+
+ This step is a bit more complicated, depending on your board. It's covered in the section
+ :ref:`Running Apache NuttX <running>`.
+
+----
+
+.. rubric:: More Details
+
+If you want more details, start at :ref:`install`.
+
diff --git a/Documentation/quickstart/running.rst b/Documentation/quickstart/running.rst
new file mode 100644
index 0000000..9bbbf1e
--- /dev/null
+++ b/Documentation/quickstart/running.rst
@@ -0,0 +1,105 @@
+.. include:: /substitutions.rst
+.. _running:
+
+Running
+=======
+
+Embedded boards have different ways to get your program onto them and get them running. This guide assumes your board
+has a JTAG connector, and you have a JTAG hardware debugger like a
+`Segger J-Link <https://www.segger.com/products/debug-probes/j-link/>`_. `JTAG <https://en.wikipedia.org/wiki/JTAG>`_
+is a set of standards that let you attach a hardware device to your embedded board, and then remotely control the CPU.
+You can load code, start, stop, step through the program, and examine variables and memory.
+
+#. Attach the Debugger Cables
+
+#. Start the Debugger
+
+ Refer to your JTAG debugger's documentation for information on how to start a GDB Server process that gdb can
+ communicate with to load code and start, stop, and step the embedded board's CPU. Your command line may be
+ different from this one.
+
+ .. code-block:: bash
+
+ $ JLinkGDBServer -device ATSAMA5D27 -if JTAG -speed 1000 -JTAGConf -1,-1
+
+#. Launch the Gnu Debugger
+
+ In another terminal window, launch the GDB for your platform. In the case of this guide, this came with the
+ ARM Embedded Gnu Toolchain we downloaded in the Install step.
+
+ .. code-block:: bash
+
+ $ arm-none-eabi-gdb
+
+#. Connect to the board's serial console
+
+ Usually you connect a USB-to-serial adapter to the board's serial console so you can see debug logging or
+ execute Apache NuttX Shell (nsh) commands. You can access the serial console from Linux with the ``picocom`` terminal
+ program. From another terminal, do this:
+
+ .. code-block:: bash
+
+ $ picocom -b 115200 /dev/ttyUSB0
+
+#. Set gdb to talk with the J-Link
+
+ ::
+
+ (gdb) target extended-remote :2331
+
+#. Reset the board
+
+ ::
+
+ (gdb) mon reset
+
+#. You may need to switch to the serial console to hit a key to stop the board from booting from its boot monitor
+ (U-Boot, in the case of the SAMA5 boards from Microchip).
+
+#. Halt the board
+
+ ::
+
+ (gdb) mon halt
+
+#. Load nuttx
+
+ ::
+
+ (gdb) file nuttx
+ (gdb) load nuttx
+ `/home/adamf/src/nuttx-sama5d36-xplained/nuttx/nuttx' has changed; re-reading symbols.
+ Loading section .text, size 0x9eae4 lma 0x20008000
+ Loading section .ARM.exidx, size 0x8 lma 0x200a6ae4
+ Loading section .data, size 0x125c lma 0x200a6aec
+ Start address 0x20008040, load size 654664
+ Transfer rate: 75 KB/sec, 15587 bytes/write.
+ (gdb)
+
+#. Set a breakpoint
+
+ ::
+
+ (gdb) breakpoint nsh_main
+
+#. Start nuttx
+
+ ::
+
+ (gdb) continue
+ Continuing.
+
+ Breakpoint 1, nsh_main (argc=1, argv=0x200ddfac) at nsh_main.c:208
+ 208 sched_getparam(0, ¶m);
+ (gdb) continue
+ Continuing.
+
+Debugging Shortcuts
+-------------------
+
+Note that you can abbreviate ``gdb`` commands, ``info b`` is a shortcut for
+``information breakpoints``; ``c`` works the same as ``continue``, etc.
+
+----
+
+Next up is :ref:`configuring`.