Documentation: various improvements to quickstart section
This commit is contained in:
Matias N
Brennan Ashton
parent
ce146e91ef
commit
3aacc506dc
@ -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 <nuttx_boards>`
|
||||
that describes the current configuration, and
|
||||
- The makefile fragment :ref:`Make.defs <nuttx_boards>`
|
||||
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 <nuttx_boards>`.
|
||||
|
||||
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.
|
||||
@ -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`.
|
||||
|
||||
@ -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 <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.
|
||||
`kconfig system <https://www.kernel.org/doc/Documentation/kbuild/kconfig-language.txt>`_ 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 <https://en.wikipedia.org/wiki/Menuconfig>`_).
|
||||
|
||||
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 ``<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 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 ``<return>`` to select it, hit ``<return>`` again, and again, finally
|
||||
hitting ``<return>`` 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
|
||||
|
||||
----
|
||||
|
||||
|
||||
@ -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 <https://github.com/apache/incubator-nuttx/blob/master/include/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 <https://github.com/apache/incubator-nuttx/blob/master/include/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 <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. `SWD <https://en.wikipedia.org/wiki/JTAG#Similar_interface_standards>`_ 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 <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 <http://openocd.org/>`_ 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
|
||||
<http://openocd.zylin.com/#/c/4103/>`_. 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
|
||||
<http://openocd.org/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
|
||||
<http://openocd.org/supported-jtag-interfaces/>`_, ideally a fast one (USB 2.0 High Speed). For example an `Olimex
|
||||
ARM USB TINY H <https://www.olimex.com/Products/ARM/JTAG/ARM-USB-TINY-H/>`_ or a `Segger J-Link
|
||||
<https://www.segger.com/products/debug-probes/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 <https://en.wikipedia.org/wiki/JTAG>`_ connector instead,
|
||||
things are a bit different. This guide assumes you have a JTAG hardware debugger like a
|
||||
`Segger J-Link <https://www.segger.com/products/debug-probes/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 <https://micro-ros.github.io/docs/tutorials/advanced/nuttx/debugging/>`_.
|
||||
|
||||
See the section :ref:`Running <running>` for a brief tutorial on how to use GDB.
|
||||
|
||||
----
|
||||
|
||||
Next up is :ref:`organization`.
|
||||
|
||||
@ -22,5 +22,4 @@ to build NuttX.
|
||||
configuring.rst
|
||||
debugging.rst
|
||||
organization.rst
|
||||
build_and_make.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`.
|
||||
|
||||
@ -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 <https://en.wikipedia.org/wiki/JTAG>`_ connector instead,
|
||||
things are a bit different. This guide assumes you have a JTAG hardware debugger like a
|
||||
`Segger J-Link <https://www.segger.com/products/debug-probes/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`.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user