From b88038a1e1dc60f87c4768870f5de9a80201025a Mon Sep 17 00:00:00 2001 From: Adam Feuer Date: Fri, 4 Sep 2020 14:00:59 -0700 Subject: [PATCH] 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(-) create mode 100644 Documentation/quickstart/build_and_make.rst create mode 100644 Documentation/quickstart/compiling.rst delete mode 100644 Documentation/quickstart/config_build.rst create mode 100644 Documentation/quickstart/configuring.rst create mode 100644 Documentation/quickstart/debugging.rst create mode 100644 Documentation/quickstart/install.rst create mode 100644 Documentation/quickstart/quickstart.rst create mode 100644 Documentation/quickstart/running.rst diff --git a/Documentation/quickstart/build_and_make.rst b/Documentation/quickstart/build_and_make.rst new file mode 100644 index 0000000000..d1809af3cb --- /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/``\ **\ ``/include`` at + ``$(TOPDIR)/include/arch``. +- Creating a link to + ``$(TOPDIR)/boards/``\ **\ ``/``\ **\ ``/``\ **\ ``/include`` + at ``$(TOPDIR)/include/arch/board``. +- Creating a link to + ``$(TOPDIR)/boards/``\ **\ ``/``\ **\ ``/``\ **\ ``/src`` + at ``$(TOPDIR)/arch/``\ **\ ``/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 0000000000..b7439367f3 --- /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 : + $ # 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 `. + +---- + +Next up is :ref:`running`. + diff --git a/Documentation/quickstart/config_build.rst b/Documentation/quickstart/config_build.rst deleted file mode 100644 index 6b5331d2a8..0000000000 --- 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/``\ **\ ``/``\ **\ ``/``\ **\ ``/configs/[``\ **\ ``/]Make.defs`` - to ``$(TOPDIR)/Make.defs`` (see NOTE below), -- Copy - ``boards/``\ **\ ``/``\ **\ ``/``\ **\ ``/configs/[``\ **\ ``/]defconfig`` - to ``$(TOPDIR)/.config`` - -Where ** 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>`__. is the -optional, specific configuration directory for the board. And - is the location of the optional application directory. - -NOTE: Recall that the ``Make.defs`` file may reside in either the -``boards/``\ **\ ``/``\ **\ ``/``\ **/``configs/[``\ ** -directory or in the -``boards/``\ **\ ``/``\ **\ ``/``\ **/``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-``), 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/``\ **\ ``/include`` at - ``$(TOPDIR)/include/arch``. -- Creating a link to - ``$(TOPDIR)/boards/``\ **\ ``/``\ **\ ``/``\ **\ ``/include`` - at ``$(TOPDIR)/include/arch/board``. -- Creating a link to - ``$(TOPDIR)/boards/``\ **\ ``/``\ **\ ``/``\ **\ ``/src`` - at ``$(TOPDIR)/arch/``\ **\ ``/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 0000000000..19fa3a7ddf --- /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 `_ adapted for use with Apache +NuttX. Here's info on Linux's kconfig `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 ```` 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 ```` to select it, hit ```` again, and again, finally + hitting ```` 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 0000000000..94aa29e47b --- /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 `__. + +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 `_ +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 `__: + +.. 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 `_ 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 `_ or `OpenOCD `_. + +The NuttX operating system uses `threads `_, 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 `_. +(`Olimex ARM USB TINY H on Amazon `_.) 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 `_. Download and install it +according to the OpenOCD instructions. + +See this article for more info: +`Debugging a Apache NuttX target with GDB and OpenOCD `_. + +See the section :ref:`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 70423f95e9..aab8cf27f1 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 `_ 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 0000000000..a844a9e5a8 --- /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 `_ 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 `_ 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 `_ 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 `_. 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 `_: + + .. 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 `_ 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 `_ and Docker `container `_ + +Download the right flavor of the +`ARM Embedded Gnu Toolchain `_ +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 03af58cd6b..82a5a15d46 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 `_. 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 0000000000..be38a0775a --- /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 `_ CPU. If it isn't, you'll need a different tool chain. + + You can download a toolchain from + `ARM Embedded Gnu Toolchain `_ + 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 : + # 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 ```` 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 `. + +---- + +.. 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 0000000000..9bbbf1eb3d --- /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 `_. `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`.