doc: add documenatation about I2C_DUMP_MESSAGES
Add the documentation about I2C_DUMP_MESSAGES and about the I2C_DUMP_MESSAGES_FILTER in the develop/debug/index.rst doc file. Signed-off-by: Michał Barnaś <mb@semihalf.com>
This commit is contained in:
parent
8f01cb8147
commit
9b2b964616
1 changed files with 73 additions and 0 deletions
|
@ -286,6 +286,79 @@ Support for Zephyr RTOS awareness is implemented in `pyOCD v0.11.0`_ and later.
|
|||
It is compatible with GDB PyOCD Debugging in Eclipse, but you must enable
|
||||
CONFIG_DEBUG_THREAD_INFO=y in your application.
|
||||
|
||||
Debugging I2C communication
|
||||
***************************
|
||||
|
||||
There is a possibility to log all or some of the I2C transactions done by the application.
|
||||
This feature is enabled by the Kconfig option :kconfig:option:`CONFIG_I2C_DUMP_MESSAGES`, but it
|
||||
uses the ``LOG_DBG`` function to print the contents so the
|
||||
:kconfig:option:`CONFIG_I2C_LOG_LEVEL_DBG` option must also be enabled.
|
||||
|
||||
The sample output of the dump looks like this::
|
||||
|
||||
D: I2C msg: io_i2c_ctrl7_port0, addr=50
|
||||
D: W len=01: 00
|
||||
D: R Sr P len=08:
|
||||
D: contents:
|
||||
D: 43 42 41 00 00 00 00 00 |CBA.....
|
||||
|
||||
The first line indicates the I2C controller and the target address of the transaction.
|
||||
In above example, the I2C controller is named ``io_i2c_ctrl7_port0`` and the target device address
|
||||
is ``0x50``
|
||||
|
||||
.. note::
|
||||
|
||||
the address, length and contents values are in hexadecimal, but lack the ``0x`` prefix
|
||||
|
||||
Next lines contain messages, both sent and received. The contents of write messages is
|
||||
always shown, while the content of read messages is controlled by a parameter to the
|
||||
function ``i2c_dump_msgs_rw``. This function is available for use by user, but is also
|
||||
called internally by ``i2c_transfer`` API function with read content dump enabled.
|
||||
Before the length parameter, the header of the message is printed using abbreviations:
|
||||
|
||||
- W - write message
|
||||
- R - read message
|
||||
- Sr - restart bit
|
||||
- P - stop bit
|
||||
|
||||
The above example shows one write message with byte ``0x00`` representing the address of register to
|
||||
read from the I2C target. After that the log shows the length of received message and following
|
||||
that, the bytes read from the target ``43 42 41 00 00 00 00 00``.
|
||||
The content dump consist of both the hex and ASCII representation.
|
||||
|
||||
Filtering the I2C communication dump
|
||||
====================================
|
||||
|
||||
By default, all I2C communication is logged between all I2C controllers and I2C targets.
|
||||
It may litter the log with unrelated devices and make it difficult to effectively debug the
|
||||
communication with a device of interest.
|
||||
|
||||
Enable the Kconfig option :kconfig:option:`CONFIG_I2C_DUMP_MESSAGES_ALLOWLIST` to create an
|
||||
allowlist of I2C targets to log.
|
||||
The allowlist of devices is configured using the devicetree, for example::
|
||||
|
||||
/ {
|
||||
i2c {
|
||||
display0: some-display@a {
|
||||
...
|
||||
};
|
||||
sensor3: some-sensor@b {
|
||||
...
|
||||
};
|
||||
};
|
||||
|
||||
i2c-dump-allowlist {
|
||||
compatible = "zephyr,i2c-dump-allowlist";
|
||||
devices = < &display0 >, < &sensor3 >;
|
||||
};
|
||||
};
|
||||
|
||||
The filters nodes are identified by the compatible string with ``zephyr,i2c-dump-allowlist`` value.
|
||||
The devices are selected using the ``devices`` property with phandles to the devices on the I2C bus.
|
||||
|
||||
In the above example, the communication with device ``display0`` and ``sensor3`` will be displayed
|
||||
in the log.
|
||||
|
||||
|
||||
|
||||
.. _Eclipse IDE for C/C++ Developers: https://www.eclipse.org/downloads/packages/eclipse-ide-cc-developers/oxygen2
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue