debugger.rst 4.97 KB
Newer Older
Rahix's avatar
Rahix committed
1
2
3
4
5
6
7
.. _debugger:

Debugger
========
If you have one of our debuggers for card10, this page details how you can use
it.  The debugger looks like either one in the following pictures:

Rahix's avatar
Rahix committed
8
.. image:: static/debuggers.png
Rahix's avatar
Rahix committed
9

10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
First of all, you need to connect your debugger and card10.  There are three
connections that you need (take a look at the above diagram for more info):

* ``HDK``: This connection provides debugging (SWD) and UART.
* ``DEV``: This connection provides power (battery charger) and the native USB
  connection (bootloader).
* ``USB-C``: Connect the proved USB-C cable with the side which has the blue
  dot, so the blue dots have the same side.

Console
-------
When using the debugger, you will usually have two /dev/ttyACM* devices (one
each for ``HDK`` and ``DEV``).  To avoid confusion, allow access without
``sudo`` and tell ModemManager to ignore them, you can use the following udev
rule file (saved under ``/etc/udev/rules.d/99-card10.rules``):

.. code-block:: text

  SUBSYSTEM=="tty", ATTRS{idVendor}=="0d28", ATTRS{idProduct}=="0204", MODE="0664", GROUP="plugdev", SYMLINK+="ttyACM-card10-hdk", ENV{ID_MM_DEVICE_IGNORE}="1"
  SUBSYSTEM=="tty", ATTRS{idVendor}=="0b6a", ATTRS{idProduct}=="003c", MODE="0664", GROUP="plugdev", SYMLINK+="ttyACM-card10-dev", ENV{ID_MM_DEVICE_IGNORE}="1"

After changing udev rules, you need to tell the udev daemon:

.. code-block:: shell-session

  $ sudo udevadm control --reload

Now, additional symlinks (``/dev/ttyACM-card10-hdk`` and
``/dev/ttyACM-card10-dev``) will be created when connecting the card10.

Rahix's avatar
Rahix committed
40
41
42
43
44
45
46
47
48
49
OpenOCD
-------
For debugging card10, you need our `own fork`_ of OpenOCD.  It contains a patch
which allows flashing both flash-banks instead of just one.  Install it using
the following commands:

.. _own fork: https://git.card10.badge.events.ccc.de/card10/openocd

.. code-block:: shell-session

genofire's avatar
genofire committed
50
   $ git clone --recursive https://git.card10.badge.events.ccc.de/card10/openocd.git
Rahix's avatar
Rahix committed
51
52
53
54
55
   $ cd openocd

   $ ./bootstrap
   $ ./configure --disable-werror

Zlatko's avatar
Zlatko committed
56
.. warning::
Zlatko's avatar
Zlatko committed
57
58
    Make sure ``CMSIS-DAP Compliant Debugger`` is set to **yes (auto)** after
    running ``./configure`` (if it is not, you might need to install ``libhidapi-dev``
Rahix's avatar
Rahix committed
59
    (Ubuntu)). If you get errors making the documentation you can
Zlatko's avatar
Zlatko committed
60
    ``touch doc/openocd.info`` to skip it and continue with ``make``.
61
62
63
64
65

.. code-block:: shell-session

   $ make -j8

Rahix's avatar
Rahix committed
66
67
68
69
70

Please run ``make install`` after removing any already installed OpenOCD
version. Otherwise please always specify the full path to OpenOCD (the binary
is under ``src/openocd``).

71
72
.. note::

schneider's avatar
schneider committed
73
74
75
76
   If you want to use OpenOCD as normal user, copy ``contrib/60-openocd.rules``
   into the ``/etc/udev/rules.d/`` directory and run ``udevadm control --reload``
   afterwards.

Rahix's avatar
Rahix committed
77
78
79
80
81
GDB (``arm-none-eabi-gdb``)
---------------------------
Apart from OpenOCD you also need ``arm-none-eabi-gdb``.  You should install
that package from your distros repositories:

82
83
* Ubuntu (older): ``gdb-arm-none-eabi``
* Ubuntu (newer): ``gdb-multiarch``
Rahix's avatar
Rahix committed
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
* Arch: ``arm-none-eabi-gdb``

Debugging
---------
Run OpenOCD from the ``openocd/scripts`` directory in the firmware repository.
Call it as ``openocd -f interface/cmsis-dap.cfg -f target/max32665.cfg``.  If
the debugger and card10 are connected correctly, you should see the following
output:

.. code-block:: shell-session

   $ openocd -f interface/cmsis-dap.cfg -f target/max32665.cfg
   Info : CMSIS-DAP: SWD  Supported
   Info : CMSIS-DAP: FW Version = 1.0
   Info : CMSIS-DAP: Interface Initialised (SWD)
   Info : SWCLK/TCK = 0 SWDIO/TMS = 1 TDI = 0 TDO = 0 nTRST = 0 nRESET = 1
   Info : CMSIS-DAP: Interface ready
   Info : clock speed 2000 kHz
   Info : SWD DPIDR 0x2ba01477
   Info : max32xxx.cpu: hardware has 6 breakpoints, 4 watchpoints
   Info : Listening on port 3333 for gdb connections

schneider's avatar
schneider committed
106
Next, start *GDB* in parallel and connect it to OpenOCD.  You can do this easily
schneider's avatar
schneider committed
107
108
if you run GDB from the firmware repository root where we have provided an
``init.gdb`` file. Specify ``-x init.gdb`` to use this file.  Apart from
schneider's avatar
schneider committed
109
110
automatically connecting to OpenOCD, this script file also defines a ``reset``
command to soft-reset card10.
Rahix's avatar
Rahix committed
111
112
113

.. code-block:: shell-session

schneider's avatar
schneider committed
114
   $ arm-none-eabi-gdb -x init.gdb build/hw-tests/hello-world/hello-world.elf
Rahix's avatar
Rahix committed
115
116
117
   ...
   (gdb)

Techy's avatar
Techy committed
118
119
120
.. note::
   You will also find the following self-describing gdb files in the firmware
   root directory, which do not require additional arguments:
Rahix's avatar
Rahix committed
121
   ``flash-all.gdb,  flash-bootloader.gdb,
Techy's avatar
Techy committed
122
123
   flash-both.gdb,  flash-epicardium.gdb,  flash-pycardium.gdb``

schneider's avatar
schneider committed
124
125
126
127
128
129
130
.. warning::
   If you are used to use ``mon reset halt``, be aware that the card10 prototypes
   do not connect the reset line to the debugger. OpenOCD is configured to only do
   a soft-reset. This reset only resets the core, but not its peripherals.
   Our custom ``reset`` sets a special bit in the CPU which also resets the
   peripherals.

Rahix's avatar
Rahix committed
131
132
133
134
135
136
137
138
You are now connected to card10 and ready to start debugging!  If card10 is
still running, stop it using

.. code-block:: text

   (gdb) mon reset halt

Following that, you can debug as you would normally.