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>

doc/develop/debug/index.rst

@@ -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