diff --git a/Documentation/_static/images/menuconfig-debug.png b/Documentation/_static/images/menuconfig-debug.png new file mode 100644 index 00000000000..23828c26642 Binary files /dev/null and b/Documentation/_static/images/menuconfig-debug.png differ diff --git a/Documentation/_static/images/menuconfig.png b/Documentation/_static/images/menuconfig.png new file mode 100644 index 00000000000..c16c2343d3a Binary files /dev/null and b/Documentation/_static/images/menuconfig.png differ diff --git a/Documentation/guides/drivers.rst b/Documentation/guides/drivers.rst index d458ed8548f..983c701ef44 100644 --- a/Documentation/guides/drivers.rst +++ b/Documentation/guides/drivers.rst @@ -80,7 +80,7 @@ modification. * stack frame printf * thread printf - * `GDB — the Gnu Debugger `_ + * `GDB — the GNU Debugger `_ GDB is a great tool. In this guide we've already used it to load our program and run it. But it can do a lot more. You can single-step through code, examine variables and memory, set breakpoints, and more. I generally use diff --git a/Documentation/quickstart/build_and_make.rst b/Documentation/quickstart/build_and_make.rst index d1809af3cb8..e69bd09e21c 100644 --- a/Documentation/quickstart/build_and_make.rst +++ b/Documentation/quickstart/build_and_make.rst @@ -19,9 +19,9 @@ The ``$(TOPDIR)`` directory holds: That directory also holds: -- The makefile fragment ```.config`` <#boardconfigsubdirs>`__ +- The makefile fragment :ref:`.config ` that describes the current configuration, and -- The makefile fragment ```Make.defs`` <#boardconfigsubdirs>`__ +- The makefile fragment :ref:`Make.defs ` that provides customized build targets. Environment Variables @@ -31,8 +31,7 @@ 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>`__. - +:ref:`Make.defs `. First Time Make --------------- diff --git a/Documentation/quickstart/configuring.rst b/Documentation/quickstart/configuring.rst index 19fa3a7ddf0..c70c536d5fe 100644 --- a/Documentation/quickstart/configuring.rst +++ b/Documentation/quickstart/configuring.rst @@ -70,7 +70,7 @@ has your configuration options selected. Here's what you should see: - .. image:: ../images/menuconfig.png + .. image:: ../_static/images/menuconfig.png :width: 800px :align: center :alt: Screenshot of menuconfig system main screen @@ -88,8 +88,6 @@ has your configuration options selected. 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 diff --git a/Documentation/quickstart/debugging.rst b/Documentation/quickstart/debugging.rst index 94aa29e47bf..061c468119c 100644 --- a/Documentation/quickstart/debugging.rst +++ b/Documentation/quickstart/debugging.rst @@ -6,38 +6,49 @@ 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). +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: +NuttX has a powerful system logging facility (syslog) with ``info``, ``warn``, and ``error`` levels. You can enable +debugging for your build for the subsystem or feature by using the ``menuconfig`` system. - :: +.. code-block:: console - 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 + $ make menuconfig -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 `__. +The debug options are available under ``Build Setup`` > ``Debug Options``. You will most likely have to enable the +following options: -Timestamps can be enabled by setting ``CONFIG_SYSLOG_TIMESTAMP=y``. +* ``Enable Debug Features`` — selecting this will turn on subsystem-level debugging options, they will become visible + on the page below. You can then select the ones you want. +* ``Enable Error Output`` — this will only log errors. +* ``Enable Warnings Output`` — this will log warnings and errors. +* ``Enable Informational Debug Output`` — this will produce informational output, warnings, and errors. + +You can then select from the subsystems that are available, Network, Scheduler, USB, etc. Note that you will need to +separately enable the subsystem elsewhere in the ``menuconfig`` system. To see the ``CONFIG`` define that is set, +use the arrow keys to highlight the subsystem (for instance, ``Network Debug Features``) and type '?'. This will show +you that the C macro that is set is called ``CONFIG_DEBUG_NET``. ``debug.h`` defines the ``netinfo()`` logging +function that will log output if this macro is set. You can search the source code for ``netinfo`` to see how it is +used. + +.. image:: ../_static/images/menuconfig-debug.png + :width: 800px + :align: center + :alt: Screenshot of menuconfig system main screen + +Note that enabling all these will produce an incredible amount of logging output. Enable the level you want and +the area you're interested in, and leave the rest disabled, save the config, and then recompile. You can see the full +list of debug feature logging functions in the file +`debug.h `__. + +Syslog timestamps can be enabled in the ``menuconfig`` system using ``Device Drivers`` > ``System Logging`` > ``Prepend +timestamp to syslog message`` (``CONFIG_SYSLOG_TIMESTAMP``). 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 `_ +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 @@ -49,63 +60,33 @@ 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 +.. code-block:: console $ kconfig-tweak --disable CONFIG_DEBUG_NET + $ make olddefconfig # needed to have the kconfig system check the config $ kconfig-tweak --enable CONFIG_DEBUG_NET + $ make olddefconfig You can put a bunch of these into a simple script to configure the logging the way you want: -.. code-block:: bash +.. code-block:: console #!/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); + 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 + make oldconfig JTAG Debugging diff --git a/Documentation/quickstart/index.rst b/Documentation/quickstart/index.rst index aab8cf27f1f..a6c6a268706 100644 --- a/Documentation/quickstart/index.rst +++ b/Documentation/quickstart/index.rst @@ -1,5 +1,3 @@ -.. todo:: - =============== Getting Started =============== diff --git a/Documentation/quickstart/install.rst b/Documentation/quickstart/install.rst index a844a9e5a87..1fded37db55 100644 --- a/Documentation/quickstart/install.rst +++ b/Documentation/quickstart/install.rst @@ -16,24 +16,23 @@ Install prerequisites for building using Linux #. Install system packages - .. code-block:: bash + .. code-block:: bash - $ sudo apt install \ + $ 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 + .. code-block:: console - $ sudo usermod -a -G dialout $USER - $ # now get a login shell that knows we're in the dialout group: - $ su - $USER + $ 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) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -82,48 +81,48 @@ There are a collection of required tools that need to be built to build most Apa *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 + .. code-block:: console - $ 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 + $ 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 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:: console + + $ 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 gen-romfs (optional) This is required if you want to build ROM-based file systems. - .. code-block:: bash + .. code-block:: console - $ cd tools/ - $ tar zxf genromfs-0.5.2.tar.gz - $ cd genromfs-0.5.2 - $ make install PREFIX=$NUTTXTOOLS + $ cd tools/ + $ tar zxf genromfs-0.5.2.tar.gz + $ cd genromfs-0.5.2 + $ make install PREFIX=$NUTTXTOOLS Get Source Code (Stable) ------------------------ @@ -138,20 +137,20 @@ 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 +.. 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 + $ 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 +.. code-block:: console - $ 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). + $ 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 @@ -168,27 +167,27 @@ binary file on your embedded computer. This guide assumes your computer is an `script `_ and Docker `container `_ Download the right flavor of the -`ARM Embedded Gnu Toolchain `_ +`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 +.. code-block:: console - $ 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 + $ 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 ---- diff --git a/Documentation/quickstart/organization.rst b/Documentation/quickstart/organization.rst index 82a5a15d462..d084693b220 100644 --- a/Documentation/quickstart/organization.rst +++ b/Documentation/quickstart/organization.rst @@ -241,6 +241,8 @@ execute them. The ``audio/`` subdirectory contains the NuttX audio sub-system. +.. _nuttx_boards: + ``nuttx/boards`` ================ diff --git a/Documentation/quickstart/quickstart.rst b/Documentation/quickstart/quickstart.rst index be38a0775a5..5f84221dd6b 100644 --- a/Documentation/quickstart/quickstart.rst +++ b/Documentation/quickstart/quickstart.rst @@ -15,11 +15,10 @@ computer, you're using an ARM microcontroller on your embedded board, and you're `ARM `_ CPU. If it isn't, you'll need a different tool chain. You can download a toolchain from - `ARM Embedded Gnu Toolchain `_ + `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`: + In the following example, we download ``gcc-arm-none-eabi`` version 9.0 and unpack it into ``/opt/gcc``: .. code-block:: console @@ -28,17 +27,19 @@ In the following example, we download ``gcc-arm-none-eabi`` version 9.0 and unpa $ 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 + 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. + 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. + + 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 @@ -105,7 +106,7 @@ The next step is to download NuttX main repository along the application reposit $ 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. + 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 diff --git a/Documentation/quickstart/running.rst b/Documentation/quickstart/running.rst index 9bbbf1eb3db..d04a383367b 100644 --- a/Documentation/quickstart/running.rst +++ b/Documentation/quickstart/running.rst @@ -22,10 +22,10 @@ You can load code, start, stop, step through the program, and examine variables $ JLinkGDBServer -device ATSAMA5D27 -if JTAG -speed 1000 -JTAGConf -1,-1 -#. Launch the Gnu Debugger +#. 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. + ARM Embedded GNU Toolchain we downloaded in the Install step. .. code-block:: bash