From 6808ccd03b068ee171ac36a501223c7729d31a46 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Barna=C5=9B?= Date: Fri, 31 Mar 2023 18:41:54 +0200 Subject: [PATCH 1/6] i2c: use device instead of name for i2c dump messages MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit changes the parameter of i2c_dump_msgs function from string name to pointer to the device structure. It allows for comparison of device pointers and allow to use the printed device name in i2c shell commands. Signed-off-by: Michał Barnaś --- drivers/eeprom/eeprom_at2x_emul.c | 2 +- drivers/fuel_gauge/max17048/emul_max17048.c | 2 +- drivers/fuel_gauge/sbs_gauge/emul_sbs_gauge.c | 2 +- drivers/i2c/Kconfig | 1 + drivers/i2c/i2c_common.c | 6 +++--- drivers/sensor/akm09918c/akm09918c_emul.c | 2 +- drivers/sensor/bmi160/emul_bmi160.c | 2 +- drivers/usb/bc12/emul_bc12_pi3usb9201.c | 2 +- include/zephyr/drivers/i2c.h | 16 ++++++++-------- 9 files changed, 18 insertions(+), 17 deletions(-) diff --git a/drivers/eeprom/eeprom_at2x_emul.c b/drivers/eeprom/eeprom_at2x_emul.c index 25d079dfa6da97..91033c02b4ac86 100644 --- a/drivers/eeprom/eeprom_at2x_emul.c +++ b/drivers/eeprom/eeprom_at2x_emul.c @@ -81,7 +81,7 @@ static int at24_emul_transfer(const struct emul *target, struct i2c_msg *msgs, return -EIO; } - i2c_dump_msgs_rw("emul", msgs, num_msgs, addr, false); + i2c_dump_msgs_rw(target->dev, msgs, num_msgs, addr, false); switch (num_msgs) { case 1: if (msgs->flags & I2C_MSG_READ) { diff --git a/drivers/fuel_gauge/max17048/emul_max17048.c b/drivers/fuel_gauge/max17048/emul_max17048.c index 3ae1565cb47550..a3a09f4c03e9a2 100644 --- a/drivers/fuel_gauge/max17048/emul_max17048.c +++ b/drivers/fuel_gauge/max17048/emul_max17048.c @@ -75,7 +75,7 @@ static int max17048_emul_transfer_i2c(const struct emul *target, struct i2c_msg __ASSERT_NO_MSG(msgs && num_msgs); - i2c_dump_msgs_rw("emul", msgs, num_msgs, addr, false); + i2c_dump_msgs_rw(target->dev, msgs, num_msgs, addr, false); switch (num_msgs) { case 2: if (msgs->flags & I2C_MSG_READ) { diff --git a/drivers/fuel_gauge/sbs_gauge/emul_sbs_gauge.c b/drivers/fuel_gauge/sbs_gauge/emul_sbs_gauge.c index c84a73e75ffe00..64668d54307e37 100644 --- a/drivers/fuel_gauge/sbs_gauge/emul_sbs_gauge.c +++ b/drivers/fuel_gauge/sbs_gauge/emul_sbs_gauge.c @@ -233,7 +233,7 @@ static int sbs_gauge_emul_transfer_i2c(const struct emul *target, struct i2c_msg __ASSERT_NO_MSG(msgs && num_msgs); - i2c_dump_msgs_rw("emul", msgs, num_msgs, addr, false); + i2c_dump_msgs_rw(target->dev, msgs, num_msgs, addr, false); switch (num_msgs) { case 2: if (msgs->flags & I2C_MSG_READ) { diff --git a/drivers/i2c/Kconfig b/drivers/i2c/Kconfig index 655d7f6e0bc01c..8ae217f82bfe46 100644 --- a/drivers/i2c/Kconfig +++ b/drivers/i2c/Kconfig @@ -32,6 +32,7 @@ config I2C_STATS config I2C_DUMP_MESSAGES bool "Log all I2C transactions" depends on LOG + depends on I2C_LOG_LEVEL_DBG help Dump every I2C transaction to the system log as debug level log messages. diff --git a/drivers/i2c/i2c_common.c b/drivers/i2c/i2c_common.c index aaae974add8de1..6094ed12c776f9 100644 --- a/drivers/i2c/i2c_common.c +++ b/drivers/i2c/i2c_common.c @@ -25,10 +25,10 @@ void z_i2c_transfer_signal_cb(const struct device *dev, } #endif -void i2c_dump_msgs_rw(const char *name, const struct i2c_msg *msgs, - uint8_t num_msgs, uint16_t addr, bool dump_read) +void i2c_dump_msgs_rw(const struct device *dev, const struct i2c_msg *msgs, uint8_t num_msgs, + uint16_t addr, bool dump_read) { - LOG_DBG("I2C msg: %s, addr=%x", name, addr); + LOG_DBG("I2C msg: %s, addr=%x", dev->name, addr); for (unsigned int i = 0; i < num_msgs; i++) { const struct i2c_msg *msg = &msgs[i]; const bool is_read = msg->flags & I2C_MSG_READ; diff --git a/drivers/sensor/akm09918c/akm09918c_emul.c b/drivers/sensor/akm09918c/akm09918c_emul.c index 2112acc8c001df..a8ce27fd3d3641 100644 --- a/drivers/sensor/akm09918c/akm09918c_emul.c +++ b/drivers/sensor/akm09918c/akm09918c_emul.c @@ -76,7 +76,7 @@ static int akm09918c_emul_transfer_i2c(const struct emul *target, struct i2c_msg { struct akm09918c_emul_data *data = target->data; - i2c_dump_msgs_rw("emul", msgs, num_msgs, addr, false); + i2c_dump_msgs_rw(target->dev, msgs, num_msgs, addr, false); if (num_msgs < 1) { LOG_ERR("Invalid number of messages: %d", num_msgs); diff --git a/drivers/sensor/bmi160/emul_bmi160.c b/drivers/sensor/bmi160/emul_bmi160.c index 78fe6d3ef881b3..3870346cd30191 100644 --- a/drivers/sensor/bmi160/emul_bmi160.c +++ b/drivers/sensor/bmi160/emul_bmi160.c @@ -241,7 +241,7 @@ static int bmi160_emul_transfer_i2c(const struct emul *target, struct i2c_msg *m __ASSERT_NO_MSG(msgs && num_msgs); - i2c_dump_msgs_rw("emul", msgs, num_msgs, addr, false); + i2c_dump_msgs_rw(target->dev, msgs, num_msgs, addr, false); switch (num_msgs) { case 2: if (msgs->flags & I2C_MSG_READ) { diff --git a/drivers/usb/bc12/emul_bc12_pi3usb9201.c b/drivers/usb/bc12/emul_bc12_pi3usb9201.c index 6d6842939cdb15..f798d4d9ac0cd6 100644 --- a/drivers/usb/bc12/emul_bc12_pi3usb9201.c +++ b/drivers/usb/bc12/emul_bc12_pi3usb9201.c @@ -192,7 +192,7 @@ static int pi3usb9201_emul_transfer(const struct emul *target, struct i2c_msg *m return -EIO; } - i2c_dump_msgs("emul", msgs, num_msgs, addr); + i2c_dump_msgs(target->dev, msgs, num_msgs, addr); /* Only single byte register access permitted. Write operations must * consist of 2 write bytes: register offset, register data. Read diff --git a/include/zephyr/drivers/i2c.h b/include/zephyr/drivers/i2c.h index 95d0cf1e9c1b0b..c3ea9bb43ebc91 100644 --- a/include/zephyr/drivers/i2c.h +++ b/include/zephyr/drivers/i2c.h @@ -488,33 +488,33 @@ static inline bool i2c_is_ready_dt(const struct i2c_dt_spec *spec) * D: R len=01: 6c * @endcode * - * @param name Name of this dump, displayed at the top. + * @param dev Target for the messages being sent. Its name will be printed in the log. * @param msgs Array of messages to dump. * @param num_msgs Number of messages to dump. * @param addr Address of the I2C target device. * @param dump_read Dump data from I2C reads, otherwise only writes have data dumped. */ -void i2c_dump_msgs_rw(const char *name, const struct i2c_msg *msgs, - uint8_t num_msgs, uint16_t addr, bool dump_read); +void i2c_dump_msgs_rw(const struct device *dev, const struct i2c_msg *msgs, uint8_t num_msgs, + uint16_t addr, bool dump_read); /** * @brief Dump out an I2C message, before it is executed. * * This is equivalent to: * - * i2c_dump_msgs_rw(name, msgs, num_msgs, addr, false); + * i2c_dump_msgs_rw(dev, msgs, num_msgs, addr, false); * * The read messages' data isn't dumped. * - * @param name Name of this dump, displayed at the top. + * @param dev Target for the messages being sent. Its name will be printed in the log. * @param msgs Array of messages to dump. * @param num_msgs Number of messages to dump. * @param addr Address of the I2C target device. */ -static inline void i2c_dump_msgs(const char *name, const struct i2c_msg *msgs, +static inline void i2c_dump_msgs(const struct device *dev, const struct i2c_msg *msgs, uint8_t num_msgs, uint16_t addr) { - i2c_dump_msgs_rw(name, msgs, num_msgs, addr, false); + i2c_dump_msgs_rw(dev, msgs, num_msgs, addr, false); } #if defined(CONFIG_I2C_STATS) || defined(__DOXYGEN__) @@ -772,7 +772,7 @@ static inline int z_impl_i2c_transfer(const struct device *dev, i2c_xfer_stats(dev, msgs, num_msgs); if (IS_ENABLED(CONFIG_I2C_DUMP_MESSAGES)) { - i2c_dump_msgs_rw(dev->name, msgs, num_msgs, addr, true); + i2c_dump_msgs_rw(dev, msgs, num_msgs, addr, true); } return res; From 63259646b3be83d8da3dab8a09261acb3c2a73dc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Barna=C5=9B?= Date: Fri, 31 Mar 2023 18:44:40 +0200 Subject: [PATCH 2/6] i2c: improve the message dumps messages MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit changes the format of printed messages to align the following strings and make it more readable. Signed-off-by: Michał Barnaś --- drivers/i2c/i2c_common.c | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/drivers/i2c/i2c_common.c b/drivers/i2c/i2c_common.c index 6094ed12c776f9..616e15a2d03c3a 100644 --- a/drivers/i2c/i2c_common.c +++ b/drivers/i2c/i2c_common.c @@ -35,15 +35,13 @@ void i2c_dump_msgs_rw(const struct device *dev, const struct i2c_msg *msgs, uint const bool dump_data = dump_read || !is_read; if (msg->len == 1 && dump_data) { - LOG_DBG(" %c %s%s len=01: %02x", is_read ? 'R' : 'W', - msg->flags & I2C_MSG_RESTART ? "Sr " : "", - msg->flags & I2C_MSG_STOP ? "P" : "", - msg->buf[0]); + LOG_DBG(" %c %2s %1s len=01: %02x", is_read ? 'R' : 'W', + msg->flags & I2C_MSG_RESTART ? "Sr" : "", + msg->flags & I2C_MSG_STOP ? "P" : "", msg->buf[0]); } else { - LOG_DBG(" %c %s%s len=%02x: ", is_read ? 'R' : 'W', - msg->flags & I2C_MSG_RESTART ? "Sr " : "", - msg->flags & I2C_MSG_STOP ? "P" : "", - msg->len); + LOG_DBG(" %c %2s %1s len=%02x: ", is_read ? 'R' : 'W', + msg->flags & I2C_MSG_RESTART ? "Sr" : "", + msg->flags & I2C_MSG_STOP ? "P" : "", msg->len); if (dump_data) { LOG_HEXDUMP_DBG(msg->buf, msg->len, "contents:"); } From edec16e111b80fca4d7510d31e897f61bc9874c5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Barna=C5=9B?= Date: Fri, 31 Mar 2023 18:57:46 +0200 Subject: [PATCH 3/6] i2c: add filtering of i2c dumped messages MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit adds option to dump i2c messages of only specified devices. It makes it easier to debug communication of specific i2c device instead of logging all i2c communication. The filter of devices is specifiec in device-tree using the node with "zephyr,i2c-dump-filter" compatible string. Example of device-tree node: i2c-dump-filter { compatible = "zephyr,i2c-dump-filter"; devices = < &display0 >, < &sensor3 >; }; Signed-off-by: Michał Barnaś --- drivers/i2c/Kconfig | 16 +++++++++- drivers/i2c/i2c_common.c | 30 +++++++++++++++++++ .../i2c/zephyr,i2c-dump-allowlist.yaml | 16 ++++++++++ 3 files changed, 61 insertions(+), 1 deletion(-) create mode 100644 dts/bindings/i2c/zephyr,i2c-dump-allowlist.yaml diff --git a/drivers/i2c/Kconfig b/drivers/i2c/Kconfig index 8ae217f82bfe46..5f62fbb4eb1e9e 100644 --- a/drivers/i2c/Kconfig +++ b/drivers/i2c/Kconfig @@ -30,12 +30,26 @@ config I2C_STATS Enable I2C Stats. config I2C_DUMP_MESSAGES - bool "Log all I2C transactions" + bool "Log I2C transactions" depends on LOG depends on I2C_LOG_LEVEL_DBG help Dump every I2C transaction to the system log as debug level log messages. +config I2C_DUMP_MESSAGES_ALLOWLIST + bool "Use allowlist for logging of I2C transactions" + depends on I2C_DUMP_MESSAGES + depends on DT_HAS_ZEPHYR_I2C_DUMP_ALLOWLIST_ENABLED + help + Use allowlist to specify which devices transactions should be logged. + The allowlist is defined in the devicetree using the compatible string of + "zephyr,i2c-dump-allowlist" and phandles to the devices that need to be traced. + Example of devicetree node: + i2c-dump-allowlist { + compatible = "zephyr,i2c-dump-allowlist"; + devices = < &display0 >, < &sensor3 >; + }; + config I2C_CALLBACK bool "I2C asynchronous callback API" help diff --git a/drivers/i2c/i2c_common.c b/drivers/i2c/i2c_common.c index 616e15a2d03c3a..93986d6f58db61 100644 --- a/drivers/i2c/i2c_common.c +++ b/drivers/i2c/i2c_common.c @@ -25,9 +25,39 @@ void z_i2c_transfer_signal_cb(const struct device *dev, } #endif +#ifdef CONFIG_I2C_DUMP_MESSAGES_ALLOWLIST +#define DEF_BUS_WITH_ADDR(node, prop, idx) I2C_DT_SPEC_GET(DT_PHANDLE_BY_IDX(node, prop, idx)), +#define DEF_ALLOWLIST_DEV(node) DT_FOREACH_PROP_ELEM(node, devices, DEF_BUS_WITH_ADDR) + +struct i2c_dt_spec messages_allowlist[] = { + DT_FOREACH_STATUS_OKAY(zephyr_i2c_dump_allowlist, DEF_ALLOWLIST_DEV)}; + +#undef DEF_ALLOWLIST_DEV +#undef DEF_BUS_WITH_ADDR +#endif + void i2c_dump_msgs_rw(const struct device *dev, const struct i2c_msg *msgs, uint8_t num_msgs, uint16_t addr, bool dump_read) { +#ifdef CONFIG_I2C_DUMP_MESSAGES_ALLOWLIST + bool found_dev = 0; + + for (int a = 0; a < ARRAY_SIZE(messages_allowlist); a++) { + struct i2c_dt_spec *allowed = &messages_allowlist[a]; + + if (dev != allowed->bus || addr != allowed->addr) { + continue; + } else { + found_dev = 1; + break; + } + } + + if (!found_dev) { + return; + } +#endif + LOG_DBG("I2C msg: %s, addr=%x", dev->name, addr); for (unsigned int i = 0; i < num_msgs; i++) { const struct i2c_msg *msg = &msgs[i]; diff --git a/dts/bindings/i2c/zephyr,i2c-dump-allowlist.yaml b/dts/bindings/i2c/zephyr,i2c-dump-allowlist.yaml new file mode 100644 index 00000000000000..b1657aa7459543 --- /dev/null +++ b/dts/bindings/i2c/zephyr,i2c-dump-allowlist.yaml @@ -0,0 +1,16 @@ +# Copyright 2023 Google LLC +# SPDX-License-Identifier: Apache-2.0 + +description: Devices allowlist for i2c messages dump + +compatible: "zephyr,i2c-dump-allowlist" + +include: base.yaml + +properties: + status: + const: "okay" + + devices: + required: true + type: phandles From 05cdf159b461dd3e9ab662902afaa16e3e414b67 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Barna=C5=9B?= Date: Thu, 3 Aug 2023 14:16:59 +0200 Subject: [PATCH 4/6] doc: fix missing and remove obsolete links MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fix text that should be linking to the URLs but was missing the link reference and remove the obsolete links. Signed-off-by: Michał Barnaś --- doc/develop/application/index.rst | 4 +--- doc/develop/modules.rst | 9 ++++----- 2 files changed, 5 insertions(+), 8 deletions(-) diff --git a/doc/develop/application/index.rst b/doc/develop/application/index.rst index 7307d6c572ce63..d37e4bc635c2a7 100644 --- a/doc/develop/application/index.rst +++ b/doc/develop/application/index.rst @@ -431,7 +431,7 @@ should know about. * :makevar:`SHIELD`: see :ref:`shields` -* :makevar:`ZEPHYR_MODULES`: A CMake list containing absolute paths of +* :makevar:`ZEPHYR_MODULES`: A `CMake list`_ containing absolute paths of additional directories with source code, Kconfig, etc. that should be used in the application build. See :ref:`modules` for details. If you set this variable, it must be a complete list of all modules to use, as the build @@ -1579,6 +1579,4 @@ CONFIG_DEBUG_THREAD_INFO=y in your application. .. _GNU MCU Eclipse plug-ins: https://gnu-mcu-eclipse.github.io/plugins/install/ .. _pyOCD v0.11.0: https://github.com/mbedmicro/pyOCD/releases/tag/v0.11.0 .. _CMake list: https://cmake.org/cmake/help/latest/manual/cmake-language.7.html#lists -.. _add_subdirectory(): https://cmake.org/cmake/help/latest/command/add_subdirectory.html -.. _using Chocolatey: https://chocolatey.org/packages/RapidEE .. _example-application: https://github.com/zephyrproject-rtos/example-application diff --git a/doc/develop/modules.rst b/doc/develop/modules.rst index 5ee6648d329248..45167585cd6586 100644 --- a/doc/develop/modules.rst +++ b/doc/develop/modules.rst @@ -276,7 +276,7 @@ The merging of pull requests in the main branch of a module repository must be coupled with the corresponding manifest file update in the zephyr main tree. -**Issue Reporting:** GitHub issues are intentionally disabled in module +**Issue Reporting:** `GitHub issues`_ are intentionally disabled in module repositories, in favor of a centralized policy for issue reporting. Tickets concerning, for example, bugs or enhancements in modules shall be opened in the main @@ -625,7 +625,7 @@ variables. For example: include(${ZEPHYR_CURRENT_MODULE_DIR}/cmake/code.cmake) -It is possible to append values to a Zephyr CMake list variable from the module's first +It is possible to append values to a Zephyr `CMake list`_ variable from the module's first CMakeLists.txt file. To do so, append the value to the list and then set the list in the PARENT_SCOPE of the CMakeLists.txt file. For example, to append ``bar`` to the ``FOO_LIST`` variable in the @@ -671,7 +671,7 @@ example: include(${SYSBUILD_CURRENT_MODULE_DIR}/cmake/code.cmake) -It is possible to append values to a Zephyr CMake list variable from the +It is possible to append values to a Zephyr `CMake list`_ variable from the module's first CMakeLists.txt file. To do so, append the value to the list and then set the list in the PARENT_SCOPE of the CMakeLists.txt file. For example, to append ``bar`` to the @@ -794,7 +794,7 @@ Create a ``MODULE_EXT_ROOT`` with the following structure └── Kconfig and then build your application by specifying ``-DMODULE_EXT_ROOT`` parameter to -the CMake build system. The ``MODULE_EXT_ROOT`` accepts a CMake list of roots as +the CMake build system. The ``MODULE_EXT_ROOT`` accepts a `CMake list`_ of roots as argument. A Zephyr module can automatically be added to the ``MODULE_EXT_ROOT`` @@ -1151,5 +1151,4 @@ revision needs to be changed to the commit hash from the module repository. .. _CMake list: https://cmake.org/cmake/help/latest/manual/cmake-language.7.html#lists .. _add_subdirectory(): https://cmake.org/cmake/help/latest/command/add_subdirectory.html - .. _GitHub issues: https://github.com/zephyrproject-rtos/zephyr/issues From fe5937dc69da317cbd0cd03ef316907e84702b0f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Barna=C5=9B?= Date: Thu, 3 Aug 2023 14:20:11 +0200 Subject: [PATCH 5/6] doc: extract the documentation about debugging to another file MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Move the chapters about Application Debugging and Debugging using Eclipse to another file for easier search and to allow more debugging chapters to be inserted here. Signed-off-by: Michał Barnaś --- doc/develop/application/index.rst | 290 ----------------------------- doc/develop/debug/index.rst | 293 ++++++++++++++++++++++++++++++ doc/develop/index.rst | 1 + 3 files changed, 294 insertions(+), 290 deletions(-) create mode 100644 doc/develop/debug/index.rst diff --git a/doc/develop/application/index.rst b/doc/develop/application/index.rst index d37e4bc635c2a7..0dae0d288e01c5 100644 --- a/doc/develop/application/index.rst +++ b/doc/develop/application/index.rst @@ -1054,169 +1054,6 @@ again. target name, for example ``west build -t run_qemu`` or ``ninja run_qemu`` for QEMU. -.. _application_debugging: - -Application Debugging -********************* - -This section is a quick hands-on reference to start debugging your -application with QEMU. Most content in this section is already covered in -`QEMU`_ and `GNU_Debugger`_ reference manuals. - -.. _QEMU: http://wiki.qemu.org/Main_Page - -.. _GNU_Debugger: http://www.gnu.org/software/gdb - -In this quick reference, you'll find shortcuts, specific environmental -variables, and parameters that can help you to quickly set up your debugging -environment. - -The simplest way to debug an application running in QEMU is using the GNU -Debugger and setting a local GDB server in your development system through QEMU. - -You will need an :abbr:`ELF (Executable and Linkable Format)` binary image for -debugging purposes. The build system generates the image in the build -directory. By default, the kernel binary name is :file:`zephyr.elf`. The name -can be changed using :kconfig:option:`CONFIG_KERNEL_BIN_NAME`. - -GDB server -========== - -We will use the standard 1234 TCP port to open a :abbr:`GDB (GNU Debugger)` -server instance. This port number can be changed for a port that best suits the -development environment. There are multiple ways to do this. Each way starts a -QEMU instance with the processor halted at startup and with a GDB server -instance listening for a connection. - -Running QEMU directly -~~~~~~~~~~~~~~~~~~~~~ - -You can run QEMU to listen for a "gdb connection" before it starts executing any -code to debug it. - -.. code-block:: bash - - qemu -s -S - -will setup Qemu to listen on port 1234 and wait for a GDB connection to it. - -The options used above have the following meaning: - -* ``-S`` Do not start CPU at startup; rather, you must type 'c' in the - monitor. -* ``-s`` Shorthand for :literal:`-gdb tcp::1234`: open a GDB server on - TCP port 1234. - - -Running QEMU via :command:`ninja` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Run the following inside the build directory of an application: - -.. code-block:: console - - ninja debugserver - -QEMU will write the console output to the path specified in -:makevar:`${QEMU_PIPE}` via CMake, typically :file:`qemu-fifo` within the build -directory. You may monitor this file during the run with :command:`tail -f -qemu-fifo`. - -Running QEMU via :command:`west` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Run the following from your project root: - -.. code-block:: console - - west build -t debugserver_qemu - -QEMU will write the console output to the terminal from which you invoked -:command:`west`. - -Configuring the :command:`gdbserver` listening device -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The Kconfig option :kconfig:option:`CONFIG_QEMU_GDBSERVER_LISTEN_DEV` controls -the listening device, which can be a TCP port number or a path to a character -device. GDB releases 9.0 and newer also support Unix domain sockets. - -If the option is unset, then the QEMU invocation will lack a ``-s`` or a -``-gdb`` parameter. You can then use the :envvar:`QEMU_EXTRA_FLAGS` shell -environment variable to pass in your own listen device configuration. - -GDB client -========== - -Connect to the server by running :command:`gdb` and giving these commands: - -.. code-block:: bash - - $ path/to/gdb path/to/zephyr.elf - (gdb) target remote localhost:1234 - (gdb) dir ZEPHYR_BASE - -.. note:: - - Substitute the correct :ref:`ZEPHYR_BASE ` for your - system. - -You can use a local GDB configuration :file:`.gdbinit` to initialize your GDB -instance on every run. Your home directory is a typical location for -:file:`.gdbinit`, but you can configure GDB to load from other locations, -including the directory from which you invoked :command:`gdb`. This example -file performs the same configuration as above: - -.. code-block:: none - - target remote localhost:1234 - dir ZEPHYR_BASE - -Alternate interfaces -~~~~~~~~~~~~~~~~~~~~ - -GDB provides a curses-based interface that runs in the terminal. Pass the ``--tui`` -option when invoking :command:`gdb` or give the ``tui enable`` command within -:command:`gdb`. - -.. note:: - - The GDB version on your development system might not support the ``--tui`` - option. Please make sure you use the GDB binary from the SDK which - corresponds to the toolchain that has been used to build the binary. - -Finally, the command below connects to the GDB server using the :abbr:`DDD -(Data Display Debugger)`, a graphical frontend for GDB. The following command -loads the symbol table from the ELF binary file, in this instance, -:file:`zephyr.elf`. - -.. code-block:: bash - - ddd --gdb --debugger "gdb zephyr.elf" - -Both commands execute :command:`gdb`. The command name might -change depending on the toolchain you are using and your cross-development -tools. - -:command:`ddd` may not be installed in your -development system by default. Follow your system instructions to install -it. For example, use :command:`sudo apt-get install ddd` on an Ubuntu system. - -Debugging -========= - -As configured above, when you connect the GDB client, the application will be -stopped at system startup. You may set breakpoints, step through code, etc. as -when running the application directly within :command:`gdb`. - -.. note:: - - :command:`gdb` will not print the system console output as the application runs, - unlike when you run a native application in GDB directly. If you just - :command:`continue` after connecting the client, the application will run, - but nothing will appear to happen. Check the console output as described - above. - .. _custom_board_definition: Custom Board, Devicetree and SOC Definitions @@ -1449,134 +1286,7 @@ Cache variable: :goals: build :compact: - - -Debug with Eclipse -****************** - -Overview -======== - -CMake supports generating a project description file that can be imported into -the Eclipse Integrated Development Environment (IDE) and used for graphical -debugging. - -The `GNU MCU Eclipse plug-ins`_ provide a mechanism to debug ARM projects in -Eclipse with pyOCD, Segger J-Link, and OpenOCD debugging tools. - -The following tutorial demonstrates how to debug a Zephyr application in -Eclipse with pyOCD in Windows. It assumes you have already installed the GCC -ARM Embedded toolchain and pyOCD. - -Set Up the Eclipse Development Environment -========================================== - -#. Download and install `Eclipse IDE for C/C++ Developers`_. - -#. In Eclipse, install the GNU MCU Eclipse plug-ins by opening the menu - ``Window->Eclipse Marketplace...``, searching for ``GNU MCU Eclipse``, and - clicking ``Install`` on the matching result. - -#. Configure the path to the pyOCD GDB server by opening the menu - ``Window->Preferences``, navigating to ``MCU``, and setting the ``Global - pyOCD Path``. - -Generate and Import an Eclipse Project -====================================== - -#. Set up a GNU Arm Embedded toolchain as described in - :ref:`toolchain_gnuarmemb`. - -#. Navigate to a folder outside of the Zephyr tree to build your application. - - .. code-block:: console - - # On Windows - cd %userprofile% - - .. note:: - If the build directory is a subdirectory of the source directory, as is - usually done in Zephyr, CMake will warn: - - "The build directory is a subdirectory of the source directory. - - This is not supported well by Eclipse. It is strongly recommended to use - a build directory which is a sibling of the source directory." - -#. Configure your application with CMake and build it with ninja. Note the - different CMake generator specified by the ``-G"Eclipse CDT4 - Ninja"`` - argument. This will generate an Eclipse project description file, - :file:`.project`, in addition to the usual ninja build files. - - .. zephyr-app-commands:: - :tool: all - :app: %ZEPHYR_BASE%\samples\synchronization - :host-os: win - :board: frdm_k64f - :gen-args: -G"Eclipse CDT4 - Ninja" - :goals: build - :compact: - -#. In Eclipse, import your generated project by opening the menu - ``File->Import...`` and selecting the option ``Existing Projects into - Workspace``. Browse to your application build directory in the choice, - ``Select root directory:``. Check the box for your project in the list of - projects found and click the ``Finish`` button. - -Create a Debugger Configuration -=============================== - -#. Open the menu ``Run->Debug Configurations...``. - -#. Select ``GDB PyOCD Debugging``, click the ``New`` button, and configure the - following options: - - - In the Main tab: - - - Project: ``my_zephyr_app@build`` - - C/C++ Application: :file:`zephyr/zephyr.elf` - - - In the Debugger tab: - - - pyOCD Setup - - - Executable path: :file:`${pyocd_path}\\${pyocd_executable}` - - Uncheck "Allocate console for semihosting" - - - Board Setup - - - Bus speed: 8000000 Hz - - Uncheck "Enable semihosting" - - - GDB Client Setup - - - Executable path example (use your ``GNUARMEMB_TOOLCHAIN_PATH``): - :file:`C:\\gcc-arm-none-eabi-6_2017-q2-update\\bin\\arm-none-eabi-gdb.exe` - - - In the SVD Path tab: - - - File path: :file:`\\modules\\hal\\nxp\\mcux\\devices\\MK64F12\\MK64F12.xml` - - .. note:: - This is optional. It provides the SoC's memory-mapped register - addresses and bitfields to the debugger. - -#. Click the ``Debug`` button to start debugging. - -RTOS Awareness -============== - -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. - - - .. _CMake: https://www.cmake.org .. _CMake introduction: https://cmake.org/cmake/help/latest/manual/cmake.1.html#description -.. _Eclipse IDE for C/C++ Developers: https://www.eclipse.org/downloads/packages/eclipse-ide-cc-developers/oxygen2 -.. _GNU MCU Eclipse plug-ins: https://gnu-mcu-eclipse.github.io/plugins/install/ -.. _pyOCD v0.11.0: https://github.com/mbedmicro/pyOCD/releases/tag/v0.11.0 .. _CMake list: https://cmake.org/cmake/help/latest/manual/cmake-language.7.html#lists .. _example-application: https://github.com/zephyrproject-rtos/example-application diff --git a/doc/develop/debug/index.rst b/doc/develop/debug/index.rst new file mode 100644 index 00000000000000..27722464bf0977 --- /dev/null +++ b/doc/develop/debug/index.rst @@ -0,0 +1,293 @@ +.. _develop_debug: + +Debugging +######### + +.. _application_debugging: + +Application Debugging +********************* + +This section is a quick hands-on reference to start debugging your +application with QEMU. Most content in this section is already covered in +`QEMU`_ and `GNU_Debugger`_ reference manuals. + +.. _QEMU: http://wiki.qemu.org/Main_Page + +.. _GNU_Debugger: http://www.gnu.org/software/gdb + +In this quick reference, you'll find shortcuts, specific environmental +variables, and parameters that can help you to quickly set up your debugging +environment. + +The simplest way to debug an application running in QEMU is using the GNU +Debugger and setting a local GDB server in your development system through QEMU. + +You will need an :abbr:`ELF (Executable and Linkable Format)` binary image for +debugging purposes. The build system generates the image in the build +directory. By default, the kernel binary name is :file:`zephyr.elf`. The name +can be changed using :kconfig:option:`CONFIG_KERNEL_BIN_NAME`. + +GDB server +========== + +We will use the standard 1234 TCP port to open a :abbr:`GDB (GNU Debugger)` +server instance. This port number can be changed for a port that best suits the +development environment. There are multiple ways to do this. Each way starts a +QEMU instance with the processor halted at startup and with a GDB server +instance listening for a connection. + +Running QEMU directly +~~~~~~~~~~~~~~~~~~~~~ + +You can run QEMU to listen for a "gdb connection" before it starts executing any +code to debug it. + +.. code-block:: bash + + qemu -s -S + +will setup Qemu to listen on port 1234 and wait for a GDB connection to it. + +The options used above have the following meaning: + +* ``-S`` Do not start CPU at startup; rather, you must type 'c' in the + monitor. +* ``-s`` Shorthand for :literal:`-gdb tcp::1234`: open a GDB server on + TCP port 1234. + + +Running QEMU via :command:`ninja` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Run the following inside the build directory of an application: + +.. code-block:: console + + ninja debugserver + +QEMU will write the console output to the path specified in +:makevar:`${QEMU_PIPE}` via CMake, typically :file:`qemu-fifo` within the build +directory. You may monitor this file during the run with :command:`tail -f +qemu-fifo`. + +Running QEMU via :command:`west` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Run the following from your project root: + +.. code-block:: console + + west build -t debugserver_qemu + +QEMU will write the console output to the terminal from which you invoked +:command:`west`. + +Configuring the :command:`gdbserver` listening device +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The Kconfig option :kconfig:option:`CONFIG_QEMU_GDBSERVER_LISTEN_DEV` controls +the listening device, which can be a TCP port number or a path to a character +device. GDB releases 9.0 and newer also support Unix domain sockets. + +If the option is unset, then the QEMU invocation will lack a ``-s`` or a +``-gdb`` parameter. You can then use the :envvar:`QEMU_EXTRA_FLAGS` shell +environment variable to pass in your own listen device configuration. + +GDB client +========== + +Connect to the server by running :command:`gdb` and giving these commands: + +.. code-block:: bash + + $ path/to/gdb path/to/zephyr.elf + (gdb) target remote localhost:1234 + (gdb) dir ZEPHYR_BASE + +.. note:: + + Substitute the correct :ref:`ZEPHYR_BASE ` for your + system. + +You can use a local GDB configuration :file:`.gdbinit` to initialize your GDB +instance on every run. Your home directory is a typical location for +:file:`.gdbinit`, but you can configure GDB to load from other locations, +including the directory from which you invoked :command:`gdb`. This example +file performs the same configuration as above: + +.. code-block:: none + + target remote localhost:1234 + dir ZEPHYR_BASE + +Alternate interfaces +~~~~~~~~~~~~~~~~~~~~ + +GDB provides a curses-based interface that runs in the terminal. Pass the ``--tui`` +option when invoking :command:`gdb` or give the ``tui enable`` command within +:command:`gdb`. + +.. note:: + + The GDB version on your development system might not support the ``--tui`` + option. Please make sure you use the GDB binary from the SDK which + corresponds to the toolchain that has been used to build the binary. + +Finally, the command below connects to the GDB server using the :abbr:`DDD +(Data Display Debugger)`, a graphical frontend for GDB. The following command +loads the symbol table from the ELF binary file, in this instance, +:file:`zephyr.elf`. + +.. code-block:: bash + + ddd --gdb --debugger "gdb zephyr.elf" + +Both commands execute :command:`gdb`. The command name might +change depending on the toolchain you are using and your cross-development +tools. + +:command:`ddd` may not be installed in your +development system by default. Follow your system instructions to install +it. For example, use :command:`sudo apt-get install ddd` on an Ubuntu system. + +Debugging +========= + +As configured above, when you connect the GDB client, the application will be +stopped at system startup. You may set breakpoints, step through code, etc. as +when running the application directly within :command:`gdb`. + +.. note:: + + :command:`gdb` will not print the system console output as the application runs, + unlike when you run a native application in GDB directly. If you just + :command:`continue` after connecting the client, the application will run, + but nothing will appear to happen. Check the console output as described + above. + +Debug with Eclipse +****************** + +Overview +======== + +CMake supports generating a project description file that can be imported into +the Eclipse Integrated Development Environment (IDE) and used for graphical +debugging. + +The `GNU MCU Eclipse plug-ins`_ provide a mechanism to debug ARM projects in +Eclipse with pyOCD, Segger J-Link, and OpenOCD debugging tools. + +The following tutorial demonstrates how to debug a Zephyr application in +Eclipse with pyOCD in Windows. It assumes you have already installed the GCC +ARM Embedded toolchain and pyOCD. + +Set Up the Eclipse Development Environment +========================================== + +#. Download and install `Eclipse IDE for C/C++ Developers`_. + +#. In Eclipse, install the `GNU MCU Eclipse plug-ins`_ by opening the menu + ``Window->Eclipse Marketplace...``, searching for ``GNU MCU Eclipse``, and + clicking ``Install`` on the matching result. + +#. Configure the path to the pyOCD GDB server by opening the menu + ``Window->Preferences``, navigating to ``MCU``, and setting the ``Global + pyOCD Path``. + +Generate and Import an Eclipse Project +====================================== + +#. Set up a GNU Arm Embedded toolchain as described in + :ref:`toolchain_gnuarmemb`. + +#. Navigate to a folder outside of the Zephyr tree to build your application. + + .. code-block:: console + + # On Windows + cd %userprofile% + + .. note:: + If the build directory is a subdirectory of the source directory, as is + usually done in Zephyr, CMake will warn: + + "The build directory is a subdirectory of the source directory. + + This is not supported well by Eclipse. It is strongly recommended to use + a build directory which is a sibling of the source directory." + +#. Configure your application with CMake and build it with ninja. Note the + different CMake generator specified by the ``-G"Eclipse CDT4 - Ninja"`` + argument. This will generate an Eclipse project description file, + :file:`.project`, in addition to the usual ninja build files. + + .. zephyr-app-commands:: + :tool: all + :app: %ZEPHYR_BASE%\samples\synchronization + :host-os: win + :board: frdm_k64f + :gen-args: -G"Eclipse CDT4 - Ninja" + :goals: build + :compact: + +#. In Eclipse, import your generated project by opening the menu + ``File->Import...`` and selecting the option ``Existing Projects into + Workspace``. Browse to your application build directory in the choice, + ``Select root directory:``. Check the box for your project in the list of + projects found and click the ``Finish`` button. + +Create a Debugger Configuration +=============================== + +#. Open the menu ``Run->Debug Configurations...``. + +#. Select ``GDB PyOCD Debugging``, click the ``New`` button, and configure the + following options: + + - In the Main tab: + + - Project: ``my_zephyr_app@build`` + - C/C++ Application: :file:`zephyr/zephyr.elf` + + - In the Debugger tab: + + - pyOCD Setup + + - Executable path: :file:`${pyocd_path}\\${pyocd_executable}` + - Uncheck "Allocate console for semihosting" + + - Board Setup + + - Bus speed: 8000000 Hz + - Uncheck "Enable semihosting" + + - GDB Client Setup + + - Executable path example (use your ``GNUARMEMB_TOOLCHAIN_PATH``): + :file:`C:\\gcc-arm-none-eabi-6_2017-q2-update\\bin\\arm-none-eabi-gdb.exe` + + - In the SVD Path tab: + + - File path: :file:`\\modules\\hal\\nxp\\mcux\\devices\\MK64F12\\MK64F12.xml` + + .. note:: + This is optional. It provides the SoC's memory-mapped register + addresses and bitfields to the debugger. + +#. Click the ``Debug`` button to start debugging. + +RTOS Awareness +============== + +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. + + + +.. _Eclipse IDE for C/C++ Developers: https://www.eclipse.org/downloads/packages/eclipse-ide-cc-developers/oxygen2 +.. _GNU MCU Eclipse plug-ins: https://gnu-mcu-eclipse.github.io/plugins/install/ +.. _pyOCD v0.11.0: https://github.com/mbedmicro/pyOCD/releases/tag/v0.11.0 diff --git a/doc/develop/index.rst b/doc/develop/index.rst index 25efad6cfcb4ac..7067ea5653c595 100644 --- a/doc/develop/index.rst +++ b/doc/develop/index.rst @@ -10,6 +10,7 @@ Developing with Zephyr beyond-GSG.rst env_vars.rst application/index.rst + debug/index.rst api/index.rst languages/index.rst optimizations/index From d670f1ba6ecd7988c4220025513f55895c40f6c4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Barna=C5=9B?= Date: Thu, 3 Aug 2023 14:40:22 +0200 Subject: [PATCH 6/6] doc: add documenatation about I2C_DUMP_MESSAGES MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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ś --- doc/develop/debug/index.rst | 73 +++++++++++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+) diff --git a/doc/develop/debug/index.rst b/doc/develop/debug/index.rst index 27722464bf0977..a7afdab8c31d56 100644 --- a/doc/develop/debug/index.rst +++ b/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