Exceptions
==========

A DPU program can stop in fault for 3 reasons.

Only ``dpu-lldb`` is capable of printing the stop reason.
The **Host API** will only say that a DPU is in fault, and not the reason of the fault.

Memory fault
------------

This exception happens when the DPU tries to perform a load or a store at an address which is either out of the **WRAM** or not aligned on its size.

In any case, ``dpu-lldb`` will print the following message when it happens:

.. literalinclude:: ../../../endtests/documentation/exceptions_example/memory_fault.output

DMA fault
---------

This exception happens when the DPU tries to perform a DMA operation with the **WRAM** addresses out of the **WRAM** and/or the **MRAM** addresses out of the **MRAM**.
Note that it does not apply only to the starting address, but the whole range targeted by the transfer.

In any case, ``dpu-lldb`` will print the following message when it happens:

.. literalinclude:: ../../../endtests/documentation/exceptions_example/dma_fault.output

.. _faults:

Fault
-----

Faults are generated by the DPU **Runtime Library**, when it detects something wrong at runtime.

The list of known errors is listed here-after:

  +-------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+
  | Error message (stop reason printed by ``dpu-lldb``)                                             | Error description                                                                                    |
  +=================================================================================================+======================================================================================================+
  | .. literalinclude:: ../../../endtests/documentation/exceptions_example/heap_full.output         | Raised when the dpu cannot allocate more memory                                                      |
  +-------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+
  | .. literalinclude:: ../../../endtests/documentation/exceptions_example/div_by_zero.output       | Raised when the dpu tries to compute a division by zero                                              |
  +-------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+
  | .. literalinclude:: ../../../endtests/documentation/exceptions_example/assert.output            | Raised by a call to ``assert`` (if ``NDEBUG`` is undefined) if the specified condition is false      |
  +-------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+
  | .. literalinclude:: ../../../endtests/documentation/exceptions_example/halt.output              | Raised by a call to ``halt`` (defined in ``defs.h``)                                                 |
  +-------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+
  | .. literalinclude:: ../../../endtests/documentation/exceptions_example/printf_overflow.output   | Raised when a printf message is bigger than the printf buffer                                        |
  +-------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+
  | .. literalinclude:: ../../../endtests/documentation/exceptions_example/already_profiling.output | Raised when calling ``profiling_start`` twice in a row without calling ``profiling_stop`` in-between |
  +-------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+
  | .. literalinclude:: ../../../endtests/documentation/exceptions_example/not_profiling.output     | Raised when calling ``profiling_sop`` without calling ``profiling_start`` beforehand                 |
  +-------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+
  | .. literalinclude:: ../../../endtests/documentation/exceptions_example/wrong_alignment.output   | Raised when calling ``mram_write_unaligned`` with MRAM/WRAM addresses unequal modulo 8               |
  +-------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+