sergiotarxz/nuttx
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

add quickstart docs from NuttX Companion

Browse Source 
- with suggested edits from PR feedback
This commit is contained in:
Adam Feuer 2020-09-04 14:00:59 -07:00 committed by Matias N
parent ce604692db
commit b88038a1e1
10 changed files with 839 additions and 145 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

60
Documentation/quickstart/build_and_make.rst Normal file
View File

@ -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.

59
Documentation/quickstart/compiling.rst Normal file
View File

@ -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`.

131
Documentation/quickstart/config_build.rst
View File

@ -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.

115
Documentation/quickstart/configuring.rst Normal file
View File

@ -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`.

141
Documentation/quickstart/debugging.rst Normal file
View File

@ -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`.

26
Documentation/quickstart/index.rst
View File

@ -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

195
Documentation/quickstart/install.rst Normal file
View File

@ -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`.

24
Documentation/quickstart/organization.rst
View File

@ -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`.

126
Documentation/quickstart/quickstart.rst Normal file
View File

@ -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`.

105
Documentation/quickstart/running.rst Normal file
View File

@ -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, &param);
(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`.