From 3aacc506dc9847e4e253c56616d8b699a46a1dca Mon Sep 17 00:00:00 2001 From: Matias N Date: Sat, 21 Nov 2020 19:55:16 -0300 Subject: [PATCH] Documentation: various improvements to quickstart section --- Documentation/quickstart/build_and_make.rst | 59 ------- Documentation/quickstart/compiling.rst | 27 +--- Documentation/quickstart/configuring.rst | 111 +++++++------ Documentation/quickstart/debugging.rst | 164 +++++++++++++------- Documentation/quickstart/index.rst | 1 - Documentation/quickstart/organization.rst | 12 +- Documentation/quickstart/running.rst | 118 +------------- 7 files changed, 186 insertions(+), 306 deletions(-) delete mode 100644 Documentation/quickstart/build_and_make.rst diff --git a/Documentation/quickstart/build_and_make.rst b/Documentation/quickstart/build_and_make.rst deleted file mode 100644 index e69bd09e21..0000000000 --- a/Documentation/quickstart/build_and_make.rst +++ /dev/null @@ -1,59 +0,0 @@ -.. 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 :ref:`.config ` - that describes the current configuration, and -- The makefile fragment :ref:`Make.defs ` - 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 -:ref:`Make.defs `. - -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 index 55f81d1350..b2c5fd632c 100644 --- a/Documentation/quickstart/compiling.rst +++ b/Documentation/quickstart/compiling.rst @@ -36,23 +36,15 @@ to ``configure.sh`` and indicate your host platform, such as: The ``-l`` tells use that we're on Linux (macOS and Windows builds are possible). Use the ``-h`` argument to see all available options. -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. +You can then customize this configuration by using the menu based +configuration system with: .. code-block:: console $ cd nuttx/ $ make menuconfig - -.. todo:: - Explain some useful options. + +Modifying the configuration is covered in :doc:`configuring`. Build NuttX =========== @@ -62,11 +54,11 @@ We can now build NuttX. To do so, you can simply run: .. code-block:: console $ cd nuttx/ - $ make make + $ make The build will complete by generating the binary outputs -inside `nuttx` directory. Typically this includes the `nuttx` -ELF file (suitable for debugging using `gdb`) and a `nuttx.bin` +inside ``nuttx`` directory. Typically this includes the ``nuttx`` +ELF file (suitable for debugging using ``gdb``) and a ``nuttx.bin`` file that can be flashed to the board. To clean the build, you can do: @@ -75,11 +67,6 @@ To clean the build, you can do: $ make clean -.. warning:: - At the moment it is recommended that after modifying the - configuration you first clean before building again. This - is currently worked on. - ---- Next up is :ref:`running`. diff --git a/Documentation/quickstart/configuring.rst b/Documentation/quickstart/configuring.rst index a289969d4d..0213d410a7 100644 --- a/Documentation/quickstart/configuring.rst +++ b/Documentation/quickstart/configuring.rst @@ -6,48 +6,31 @@ 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. +application. 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. +`kconfig system `_ which +includes various frontends that allow you to modify configuration easily. Usually, the ``menuconfig`` +frontend is used, which is a console based menu system (more info `here `_). -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. +As previously explained in :doc:`compiling`, the first step is to load a premade configuration for +your board. Then, you can modify this configuration to your liking. + +In this example, we will show how you modify the default configuration of the ``sim`` build. #. 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. - -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 + .. code-block:: console $ 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 + +#. Build & run - .. code-block:: bash + .. code-block:: console $ make clean; make $ ./nuttx @@ -55,15 +38,16 @@ has your configuration options selected. From another terminal window, kill the simulator: - .. code-block:: bash + .. code-block:: console $ pkill nuttx -#. Menu Configuration +#. Modify configuration - Showing that ``login:`` is annyoing. Let's use the ``menuconfig`` system to turn it off. + In this case we will remove the login feature (which will boot straight to the prompt). To + do so, we use the ``menuconfig`` frontend. - .. code-block:: bash + .. code-block:: console $ make menuconfig @@ -76,27 +60,24 @@ has your configuration options selected. |br| -#. Application Configuration + The NSH Login setting is under :menuselection:`Application Configuration --> NSH Library`. You + can use :kbd:`🢁` and :kbd:`🢃` keys to navigate and :kbd:`↵` to enter a submenu. + To disable the corresponding setting go to :menuselection:`Console Login` and press :kbd:`spacebar` to + it (so that it has a blank space instead of a star in it). - 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 you need to exit ``menuconfig`` and save the modified configuration. Use the :kbd:`🡸` and + :kbd:`🡺` arrow keys to navigate the lower menu. If you select :menuselection:`Exit` you will be + prompted to save the config. - 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. +#. Build with the new Configuration -#. Make the New Configuration + .. code-block:: console - .. code-block:: bash - - $ make clean; make + $ make #. Run - .. code-block:: bash + .. code-block:: console $ ./nuttx NuttShell (NSH) NuttX-8.2 @@ -104,8 +85,42 @@ has your configuration options selected. Success! +.. tip:: 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)``. + configured in :menuselection:`Application Configuration --> NSH Library --> Message of the Day (MOTD)`. + +Fast configuration changes +-------------------------- + +If you know exactly which configuration symbol you want to change, you can use the ``kconfig-tweak`` tool (comes with the ``kconfig-frontends`` package) to quickly change a setting without going into the configuration frontend. This is useful to change settings such as debug options: + +.. 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 + +This is also useful to script configuration changes that you perform often: + +.. 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 + make oldconfig ---- diff --git a/Documentation/quickstart/debugging.rst b/Documentation/quickstart/debugging.rst index 379240d525..299326b73c 100644 --- a/Documentation/quickstart/debugging.rst +++ b/Documentation/quickstart/debugging.rst @@ -14,11 +14,7 @@ Debug Logging 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 - - $ make menuconfig - -The debug options are available under ``Build Setup`` > ``Debug Options``. You will most likely have to enable the +The debug options are available under :menuselection:`Build Setup --> Debug Options`. You will most likely have to enable the following options: * ``Enable Debug Features`` — selecting this will turn on subsystem-level debugging options, they will become visible @@ -44,82 +40,140 @@ the area you're interested in, and leave the rest disabled, save the config, and 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``). +Syslog timestamps can be enabled in the configuration in :menuselection:`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 `_ -for available debug settings that are available. This can also be configured via the ``menuconfig`` system. +for available debug settings that are available. 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 -------------------------------- +Debugging with ``openocd`` and ``gdb`` +-------------------------------------- -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: +To debug our Nucleo board using its embedded SWD debug adapter, +start ``openocd`` with the following command: .. 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 + $ openocd -f interface/st-link-v2.cfg -f target/stm32f1x.cfg -You can put a bunch of these into a simple script to configure the logging the way you want: +This will start a ``gdb`` server. Then, start ``gdb`` with: .. code-block:: console - #!/bin/bash + $ cd nuttx/ + $ gdb-multiarch nuttx/nuttx - 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 +Inside ``gdb`` console, connect to the ``gdb`` server with: +.. code-block:: -JTAG/SWD Debugging ------------------- + (gdb) target extended-remote :3333 -`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. `SWD `_ is an -Arm-specific interface with a reduced number of signals which can be used alternatively. +You can now use standard ``gdb`` commands. -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. +Debugging with an external JTAG adapter +--------------------------------------- -.. note:: - OpenOCD hasn't announced a stable release for a few years but the development remains active. You'll need to use a - version of OpenOCD recent enough so that it includes NuttX support as `contributed by Sony upstream - `_. The version included in official OS repositories will probably be too old. - You should build from source or use one of the unofficial, more recent builds. See `Getting OpenOCD - `_ for more details. +.. todo:: + Explain this with openocd. It gives the impression that JTAG requires + a specific tool. Also, some of the example commands apply to both cases. + This repeats some of the above. -You will need a board with a JTAG or SWD connector and an `OpenOCD-compatible hardware adapter -`_, ideally a fast one (USB 2.0 High Speed). For example an `Olimex -ARM USB TINY H `_ or a `Segger J-Link -`_. Many other adapters work too, follow the OpenOCD -instructions and the instructions that came with your adapter. +If your board does not have an embedded programmer and uses +`JTAG `_ connector instead, +things are a bit different. This guide assumes 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:: console + + $ JLinkGDBServer -device ATSAMA5D27 -if JTAG -speed 1000 -JTAGConf -1,-1 + +#. Launch the GNU Debugger + + In another terminal window, launch the GDB. In the case of this guide, this came with the + ARM Embedded GNU Toolchain we downloaded in the Install step. + + .. code-block:: console + + $ cd nuttx/ + $ gdb-multiarch nuttx/nuttx + +#. 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) 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. 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 0a02947303..e922ddcfd8 100644 --- a/Documentation/quickstart/index.rst +++ b/Documentation/quickstart/index.rst @@ -22,5 +22,4 @@ to build NuttX. configuring.rst debugging.rst organization.rst - build_and_make.rst diff --git a/Documentation/quickstart/organization.rst b/Documentation/quickstart/organization.rst index e2a1044ea2..eecdc52115 100644 --- a/Documentation/quickstart/organization.rst +++ b/Documentation/quickstart/organization.rst @@ -1,4 +1,9 @@ .. include:: /substitutions.rst + +.. todo:: + This is mostly untouched from the original documentation. It does + not really belong to "quickstart". Also, this needs cleanup. + .. _organization: =================== @@ -506,10 +511,5 @@ support. ================== 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>`__. +all of the top-level control logic to build NuttX. ----- - -Next up is :ref:`build_and_make`. diff --git a/Documentation/quickstart/running.rst b/Documentation/quickstart/running.rst index 4bc59b225c..6ad48e5e91 100644 --- a/Documentation/quickstart/running.rst +++ b/Documentation/quickstart/running.rst @@ -40,7 +40,7 @@ latest Git version. To install it you should: $ git clone git://git.code.sf.net/p/openocd/code openocd $ cd openocd $ ./bootstrap - $ ./configure --prefix install/ + $ ./configure --prefix=install/ $ make install The resulting installation will be under ``openocd/install``. You can add @@ -71,122 +71,6 @@ of your choice where you will see the ``nsh>`` prompt: $ gtkterm -s 115200 -p /dev/ttyUSB0 - -Debugging -========= - -Using ``openocd`` you can also debug NuttX. To do so, first run: - -.. code-block:: console - - $ openocd -f interface/st-link-v2.cfg -f target/stm32f1x.cfg - -which will start a GDB server. Then, start ``gdb`` as: - -.. code-block:: console - - $ cd nuttx/ - $ gdb-multiarch nuttx/nuttx - -Inside ``gdb`` console, connect to the ``openocd`` server with: - -.. code-block:: - - (gdb) target extended-remote :3333 - -You can debug using standard ``gdb`` commands. - -Advanced Debugging with JTAG ----------------------------- - -If your board does not have an embedded programmer and uses -`JTAG `_ connector instead, -things are a bit different. This guide assumes 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:: console - - $ JLinkGDBServer -device ATSAMA5D27 -if JTAG -speed 1000 -JTAGConf -1,-1 - -#. Launch the GNU Debugger - - In another terminal window, launch the GDB. In the case of this guide, this came with the - ARM Embedded GNU Toolchain we downloaded in the Install step. - - .. code-block:: console - - $ cd nuttx/ - $ gdb-multiarch nuttx/nuttx - -#. 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) 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`.