598e3eedb4
by the below command:
find . -type f -name '*.rst' -exec sed --in-place 's/[[:space:]]\+$//' {} \+
Signed-off-by: Xiang Xiao <xiaoxiang@xiaomi.com>
193 lines
5.1 KiB
ReStructuredText
193 lines
5.1 KiB
ReStructuredText
.. include:: /substitutions.rst
|
|
.. _running:
|
|
|
|
=======
|
|
Running
|
|
=======
|
|
|
|
In order to finally run NuttX on your board, you first have to flash the NuttX
|
|
binary. As an easy start, it is recommended that you choose a well supported board
|
|
which also integrates the debugger/programmer in the board itself exposed via USB
|
|
connector.
|
|
|
|
A good choice is a Nucleo or Discovery board from ST Microelectronics,
|
|
as there is a wide choice of suported boards for the STM32 architecture in NuttX.
|
|
Also, these boards expose an UART port over the USB connection which allows you
|
|
to interact with NuttX via the interactive console without any extra hardware.
|
|
For the purposes of this guide, we will use the Nucleo F103RB board.
|
|
|
|
Flashing
|
|
========
|
|
|
|
There are various tools you can use to flash the NuttX binary to your Nucleo
|
|
board. One common option is to use `openocd` which supports a large number
|
|
of programmers and target microcontrollers.
|
|
|
|
To install the stable version of openocd you can do:
|
|
|
|
.. code-block:: console
|
|
|
|
$ apt install openocd
|
|
|
|
.. todo:: add instructions for other platforms
|
|
|
|
You should note that openocd project has not made stable releases for long
|
|
time and support for newer hardware will probably be only available in the
|
|
latest Git version. To install it you should:
|
|
|
|
.. code-block:: console
|
|
|
|
$ git clone git://git.code.sf.net/p/openocd/code openocd
|
|
$ cd openocd
|
|
$ ./bootstrap
|
|
$ ./configure --prefix install/
|
|
$ make install
|
|
|
|
The resulting installation will be under ``openocd/install``. You can add
|
|
``openocd/install/bin`` to your ``PATH``.
|
|
|
|
Now, to flash the binary to your board, connect the USB cable and do:
|
|
|
|
.. code-block:: console
|
|
|
|
$ cd nuttx/
|
|
$ openocd -f interface/st-link-v2.cfg -f target/stm32f1x.cfg -c 'init' \
|
|
-c 'program nuttx/nuttx.bin verify reset' -c 'shutdown'
|
|
|
|
Access NuttShell
|
|
================
|
|
|
|
Once you flash your board, it will reset and offer a prompt over the serial
|
|
console. With the Nucleo board, you can simply open the terminal program
|
|
of your choice where you will see the ``nsh>`` prompt:
|
|
|
|
.. tabs::
|
|
|
|
.. code-tab:: console picocom (CLI)
|
|
|
|
$ picocom -b 115200 /dev/ttyUSB0
|
|
|
|
.. code-tab:: console gtkterm (GUI)
|
|
|
|
$ 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`.
|