Debugging
=========

Debugging a misbehaving program or embedded controller can be very hard, in
particular because the teensy development board does not expose any JTAG headers
(which is a pity because the microcontroller has them).

Print-style debugging
---------------------

The go-to way practised in the firmware is classical print statements. Logging
flags (:ref:`logging_flags`) are used to turn on/off these print statements in
certain parts of the code.

Post mortems
------------

The teensy code can put some debugging information after some trap condition
(such as a nullpointer access) into RAM. This feature is passed by the firmware
into the system logs so there is a minimum chance to undestand at least the final
reason for a crash. However, the stack pointer address of such a crash is typically not
useful.

Native debugging
----------------

In the native :ref:`environment <pioenv>`, debugging is trivial because any system native
debugger can be easily used. Since a recent version of the code, the *ArduinoFake*
shim library allows to exploit the full debugging capabilities of your IDE (or
``pio debug``, respectively) as if you would not work with any firmware at all.

Debugging with VSCode (MacOS with lldb)
.......................................

To properly use the native debug mode provided by VSCode, you need to modify the ``launch.json`` file, that configures the debug process. 
To access the file, first open the ``Run and Debug`` menu in VSCode. Then click on the small gear labeled ``Open 'launch.json'`` (probably on the top of the window).
Then amend the ``configurations`` tag by this code: 

::

    {
        "name": "LUCIDAC Debug",
        "type": "cppdbg",
        "request": "launch",
        "program": "${workspaceFolder}/.pio/build/native/program",
        "args": [],
        "stopAtEntry": false,
        "cwd": "${fileDirname}",
        "environment": [],
        "externalConsole": false,
        "MIMode": "lldb",
        "preLaunchTask": {
            "type": "PlatformIO",
            "task": "Pre-Debug"
        }
    }

Now you should see a new debugging target called ``LUCIDAC Debug`` in the respective dropdown menu (probably next to the small gear icon). After selecting this target, you can start the debugging process.

Other approaches
----------------

*Gdb stubs* are something we have not evaulated yet. Most likely it is not
feasible in time critical situations, thought.