WF200 SPI Startup Debugging

When getting started with WF200 and using a SPI bus on a Linux platform, after adapting the device tree to your hardware (as described in https://github.com/SiliconLabs/wfx-linux-driver/blob/master/README.md#spi) you may still run into issues.

Part of this article (i.e. the SPI logic analyser captures) are also application to RTOS/Bare Metal use cases

This article provides detailed information on techniques used to trace SPI startup both using a logic analyser and HIF traces in the context of a Linux application.

Attached Files

The attached files are those used to illustrate this article:

• Spi_startup_log.txt contains the corresponding HIF traces
• traces_spi_startup_dmesg.txt contains the corresponding dmesg traces

SPI Startup Phase

Here is a zoomed-out capture of the SPI startup phase:

When zooming on the very first transactions (those used to check that the SPI connection is correct), we see:

then

In the traces, this corresponds to:

trace_spi_start-1844 [000] .... 1517.940786: io_write32: CONFIG: 00045600
trace_spi_start-1844 [000] .... 1517.940852: io_read32: CONFIG: 02045600
trace_spi_start-1844 [000] .... 1517.940902: io_write32: SET_GEN_R_W: 87000000
trace_spi_start-1844 [000] .... 1517.940946: io_read32: SET_GEN_R_W: 070b8775

Note the 16 bits swap: What the analyzer shows as '0x5600 0x0004' is traced as 00045600

Basically, if you reach this step you have a good chance that your SPI bus is properly working.

FW Download

The next steps are

• FW download
• PDS download

Those are also part of the traces and capture.

If you miss the FW file, you will get a message similar to:

wfx: Silicon Labs WFX_2.3.5
wfx-spi spi3.0: SPI transfer failed: -22
wfx-spi spi3.0: Falling back to user helper
wfx-spi spi3.0: can't load wfm_wf200_C0.sec, falling back to wfm_wf200.sec wfx-spi spi3.0: Falling back to user helper wfx-spi spi3.0: can't load wfm_wf200.sec
wfx-spi spi3.0: no error reported by secure boot
wfx-spi: probe of spi3.0 failed with error -11

In this situation, follow the instructions in https://github.com/SiliconLabs/wfx-firmware/blob/master/PDS/README.md to create the PDS file you need and copy it under /lib/firmware.

When SPI is not Working

If your SPI bus connection is not working, you will get traces similar to:

[   49.490494] wfx: Silicon Labs WFX_2.2.5
[   49.496933] wfx-spi spi0.0: chip mute. Bus configuration error or chip wasn't reset?
[   49.504816] wfx-spi: probe of spi0.0 failed with error -5

First of all, make sure that you have the proper SDIO_DAT2/HIF_SEL level following reset, as indicated in paragraph 'Host Interface' of the WF200 Datasheet

Second, you need to make sure you follow the Chip Select requirements in the Host Interface (keeping CS low for the entire length of a command).

Some processors will have CS going up between each byte. In this situation, refer to your processor's documentation to know how to use a GPIO instead of the HW SPI CS for Chip Select (under Linux, this is configured via the device tree, see 'cs-gpio' in the device tree documentation).

Once those checks are completed, if you still have startup issue you can start considering tracing HIF messages and connecting a logic analyzer to know more about what goes wrong. 

You may also refer to  the Linux Device Tree Debugging article first, to check your device tree adaptations.

Bash script to trace SPI HIF messages at Startup

#!/bin/bash
# usage:
# sudo ./trace_spi_startup

check_root()
{
    if [ $(id -u) != 0 ]; then
        echo "ERROR: please run this script as root (running 'sudo $(basename $0)' should work)" >&2
        exit 1
    fi
}

check_root

dmesg -C > /dev/null

echo "Loading wfx SPI driver..." > /dev/kmsg

echo spi0.0 > /sys/bus/spi/drivers/wfx-spi/unbind

echo 1 > /sys/kernel/debug/tracing/events/wfx/io_read/enable
echo 1 > /sys/kernel/debug/tracing/events/wfx/io_write/enable
echo 1 > /sys/kernel/debug/tracing/events/wfx/io_read32/enable
echo 1 > /sys/kernel/debug/tracing/events/wfx/io_write32/enable

echo spi0.0 > /sys/bus/spi/drivers/wfx-spi/bind

cat /sys/kernel/debug/tracing/trace_pipe &

echo 0 > /sys/kernel/debug/tracing/events/wfx/io_read/enable
echo 0 > /sys/kernel/debug/tracing/events/wfx/io_write/enable
echo 0 > /sys/kernel/debug/tracing/events/wfx/io_read32/enable
echo 0 > /sys/kernel/debug/tracing/events/wfx/io_write32/enable


exit 0

Correct messages

Chip Select and IRQ

Here is a series of transactions showing the Chip Select and IRQ signals.

Note how CS is active for the entire duration of the messages.

Message on IRQ

Here is a (zoomed in from above) view of a message triggered by an interruption coming from the WFx

Note how the IRQ signal falls down right after the CONTROL register is read.

Corresponding traces

io_read32: CONTROL <==> 0x9002 :

• MSB[15] 1: Read,
• [14:12] 0x1: CONTROL,
• [11:0] 2: 2 *16 bits.
• CONTROL value = 0x00003004

WF200 SPI Startup Debugging

When getting started with WF200 and using a SPI bus on a Linux platform, after adapting the device tree to your hardware (as described in https://github.com/SiliconLabs/wfx-linux-driver/blob/master/README.md#spi) you may still run into issues.

Part of this article (i.e. the SPI logic analyser captures) are also application to RTOS/Bare Metal use cases

This article provides detailed information on techniques used to trace SPI startup both using a logic analyser and HIF traces in the context of a Linux application.

Attached Files

The attached files are those used to illustrate this article:

• Spi_startup_log.txt contains the corresponding HIF traces
• traces_spi_startup_dmesg.txt contains the corresponding dmesg traces

SPI Startup Phase

Here is a zoomed-out capture of the SPI startup phase:

When zooming on the very first transactions (those used to check that the SPI connection is correct), we see:

then

In the traces, this corresponds to:

trace_spi_start-1844 [000] .... 1517.940786: io_write32: CONFIG: 00045600
trace_spi_start-1844 [000] .... 1517.940852: io_read32: CONFIG: 02045600
trace_spi_start-1844 [000] .... 1517.940902: io_write32: SET_GEN_R_W: 87000000
trace_spi_start-1844 [000] .... 1517.940946: io_read32: SET_GEN_R_W: 070b8775

Note the 16 bits swap: What the analyzer shows as '0x5600 0x0004' is traced as 00045600

Basically, if you reach this step you have a good chance that your SPI bus is properly working.

FW Download

The next steps are

• FW download
• PDS download

Those are also part of the traces and capture.

If you miss the FW file, you will get a message similar to:

wfx: Silicon Labs WFX_2.3.5
wfx-spi spi3.0: SPI transfer failed: -22
wfx-spi spi3.0: Falling back to user helper
wfx-spi spi3.0: can't load wfm_wf200_C0.sec, falling back to wfm_wf200.sec wfx-spi spi3.0: Falling back to user helper wfx-spi spi3.0: can't load wfm_wf200.sec
wfx-spi spi3.0: no error reported by secure boot
wfx-spi: probe of spi3.0 failed with error -11

In this situation, follow the instructions in https://github.com/SiliconLabs/wfx-firmware/blob/master/PDS/README.md to create the PDS file you need and copy it under /lib/firmware.

When SPI is not Working

If your SPI bus connection is not working, you will get traces similar to:

[   49.490494] wfx: Silicon Labs WFX_2.2.5
[   49.496933] wfx-spi spi0.0: chip mute. Bus configuration error or chip wasn't reset?
[   49.504816] wfx-spi: probe of spi0.0 failed with error -5

First of all, make sure that you have the proper SDIO_DAT2/HIF_SEL level following reset, as indicated in paragraph 'Host Interface' of the WF200 Datasheet

Second, you need to make sure you follow the Chip Select requirements in the Host Interface (keeping CS low for the entire length of a command).

Some processors will have CS going up between each byte. In this situation, refer to your processor's documentation to know how to use a GPIO instead of the HW SPI CS for Chip Select (under Linux, this is configured via the device tree, see 'cs-gpio' in the device tree documentation).

Once those checks are completed, if you still have startup issue you can start considering tracing HIF messages and connecting a logic analyzer to know more about what goes wrong. 

You may also refer to  the Linux Device Tree Debugging article first, to check your device tree adaptations.

Bash script to trace SPI HIF messages at Startup

#!/bin/bash
# usage:
# sudo ./trace_spi_startup

check_root()
{
    if [ $(id -u) != 0 ]; then
        echo "ERROR: please run this script as root (running 'sudo $(basename $0)' should work)" >&2
        exit 1
    fi
}

check_root

dmesg -C > /dev/null

echo "Loading wfx SPI driver..." > /dev/kmsg

echo spi0.0 > /sys/bus/spi/drivers/wfx-spi/unbind

echo 1 > /sys/kernel/debug/tracing/events/wfx/io_read/enable
echo 1 > /sys/kernel/debug/tracing/events/wfx/io_write/enable
echo 1 > /sys/kernel/debug/tracing/events/wfx/io_read32/enable
echo 1 > /sys/kernel/debug/tracing/events/wfx/io_write32/enable

echo spi0.0 > /sys/bus/spi/drivers/wfx-spi/bind

cat /sys/kernel/debug/tracing/trace_pipe &

echo 0 > /sys/kernel/debug/tracing/events/wfx/io_read/enable
echo 0 > /sys/kernel/debug/tracing/events/wfx/io_write/enable
echo 0 > /sys/kernel/debug/tracing/events/wfx/io_read32/enable
echo 0 > /sys/kernel/debug/tracing/events/wfx/io_write32/enable


exit 0

Correct messages

Chip Select and IRQ

Here is a series of transactions showing the Chip Select and IRQ signals.

Note how CS is active for the entire duration of the messages.

Message on IRQ

Here is a (zoomed in from above) view of a message triggered by an interruption coming from the WFx

Note how the IRQ signal falls down right after the CONTROL register is read.

Corresponding traces

io_read32: CONTROL <==> 0x9002 :

• MSB[15] 1: Read,
• [14:12] 0x1: CONTROL,
• [11:0] 2: 2 *16 bits.
• CONTROL value = 0x00003004

WF200 SPI Startup Debugging

When getting started with WF200 and using a SPI bus on a Linux platform, after adapting the device tree to your hardware (as described in https://github.com/SiliconLabs/wfx-linux-driver/blob/master/README.md#spi) you may still run into issues.

Part of this article (i.e. the SPI logic analyser captures) are also application to RTOS/Bare Metal use cases

This article provides detailed information on techniques used to trace SPI startup both using a logic analyser and HIF traces in the context of a Linux application.

Attached Files

The attached files are those used to illustrate this article:

• Spi_startup_log.txt contains the corresponding HIF traces
• traces_spi_startup_dmesg.txt contains the corresponding dmesg traces

SPI Startup Phase

Here is a zoomed-out capture of the SPI startup phase:

When zooming on the very first transactions (those used to check that the SPI connection is correct), we see:

then

In the traces, this corresponds to:

trace_spi_start-1844 [000] .... 1517.940786: io_write32: CONFIG: 00045600
trace_spi_start-1844 [000] .... 1517.940852: io_read32: CONFIG: 02045600
trace_spi_start-1844 [000] .... 1517.940902: io_write32: SET_GEN_R_W: 87000000
trace_spi_start-1844 [000] .... 1517.940946: io_read32: SET_GEN_R_W: 070b8775

Note the 16 bits swap: What the analyzer shows as '0x5600 0x0004' is traced as 00045600

Basically, if you reach this step you have a good chance that your SPI bus is properly working.

FW Download

The next steps are

• FW download
• PDS download

Those are also part of the traces and capture.

If you miss the FW file, you will get a message similar to:

wfx: Silicon Labs WFX_2.3.5
wfx-spi spi3.0: SPI transfer failed: -22
wfx-spi spi3.0: Falling back to user helper
wfx-spi spi3.0: can't load wfm_wf200_C0.sec, falling back to wfm_wf200.sec wfx-spi spi3.0: Falling back to user helper wfx-spi spi3.0: can't load wfm_wf200.sec
wfx-spi spi3.0: no error reported by secure boot
wfx-spi: probe of spi3.0 failed with error -11

In this situation, follow the instructions in https://github.com/SiliconLabs/wfx-firmware/blob/master/PDS/README.md to create the PDS file you need and copy it under /lib/firmware.

When SPI is not Working

If your SPI bus connection is not working, you will get traces similar to:

[   49.490494] wfx: Silicon Labs WFX_2.2.5
[   49.496933] wfx-spi spi0.0: chip mute. Bus configuration error or chip wasn't reset?
[   49.504816] wfx-spi: probe of spi0.0 failed with error -5

First of all, make sure that you have the proper SDIO_DAT2/HIF_SEL level following reset, as indicated in paragraph 'Host Interface' of the WF200 Datasheet

Second, you need to make sure you follow the Chip Select requirements in the Host Interface (keeping CS low for the entire length of a command).

Some processors will have CS going up between each byte. In this situation, refer to your processor's documentation to know how to use a GPIO instead of the HW SPI CS for Chip Select (under Linux, this is configured via the device tree, see 'cs-gpio' in the device tree documentation).

Once those checks are completed, if you still have startup issue you can start considering tracing HIF messages and connecting a logic analyzer to know more about what goes wrong. 

You may also refer to  the Linux Device Tree Debugging article first, to check your device tree adaptations.

Bash script to trace SPI HIF messages at Startup

#!/bin/bash
# usage:
# sudo ./trace_spi_startup

check_root()
{
    if [ $(id -u) != 0 ]; then
        echo "ERROR: please run this script as root (running 'sudo $(basename $0)' should work)" >&2
        exit 1
    fi
}

check_root

dmesg -C > /dev/null

echo "Loading wfx SPI driver..." > /dev/kmsg

echo spi0.0 > /sys/bus/spi/drivers/wfx-spi/unbind

echo 1 > /sys/kernel/debug/tracing/events/wfx/io_read/enable
echo 1 > /sys/kernel/debug/tracing/events/wfx/io_write/enable
echo 1 > /sys/kernel/debug/tracing/events/wfx/io_read32/enable
echo 1 > /sys/kernel/debug/tracing/events/wfx/io_write32/enable

echo spi0.0 > /sys/bus/spi/drivers/wfx-spi/bind

cat /sys/kernel/debug/tracing/trace_pipe &

echo 0 > /sys/kernel/debug/tracing/events/wfx/io_read/enable
echo 0 > /sys/kernel/debug/tracing/events/wfx/io_write/enable
echo 0 > /sys/kernel/debug/tracing/events/wfx/io_read32/enable
echo 0 > /sys/kernel/debug/tracing/events/wfx/io_write32/enable


exit 0

Correct messages

Chip Select and IRQ

Here is a series of transactions showing the Chip Select and IRQ signals.

Note how CS is active for the entire duration of the messages.

Message on IRQ

Here is a (zoomed in from above) view of a message triggered by an interruption coming from the WFx

Note how the IRQ signal falls down right after the CONTROL register is read.

Corresponding traces

io_read32: CONTROL <==> 0x9002 :

• MSB[15] 1: Read,
• [14:12] 0x1: CONTROL,
• [11:0] 2: 2 *16 bits.
• CONTROL value = 0x00003004

WF200 SPI Startup Debugging

When getting started with WF200 and using a SPI bus on a Linux platform, after adapting the device tree to your hardware (as described in https://github.com/SiliconLabs/wfx-linux-driver/blob/master/README.md#spi) you may still run into issues.

Part of this article (i.e. the SPI logic analyser captures) are also application to RTOS/Bare Metal use cases

This article provides detailed information on techniques used to trace SPI startup both using a logic analyser and HIF traces in the context of a Linux application.

Attached Files

The attached files are those used to illustrate this article:

• Spi_startup_log.txt contains the corresponding HIF traces
• traces_spi_startup_dmesg.txt contains the corresponding dmesg traces

SPI Startup Phase

Here is a zoomed-out capture of the SPI startup phase:

When zooming on the very first transactions (those used to check that the SPI connection is correct), we see:

then

In the traces, this corresponds to:

trace_spi_start-1844 [000] .... 1517.940786: io_write32: CONFIG: 00045600
trace_spi_start-1844 [000] .... 1517.940852: io_read32: CONFIG: 02045600
trace_spi_start-1844 [000] .... 1517.940902: io_write32: SET_GEN_R_W: 87000000
trace_spi_start-1844 [000] .... 1517.940946: io_read32: SET_GEN_R_W: 070b8775

Note the 16 bits swap: What the analyzer shows as '0x5600 0x0004' is traced as 00045600

Basically, if you reach this step you have a good chance that your SPI bus is properly working.

FW Download

The next steps are

• FW download
• PDS download

Those are also part of the traces and capture.

If you miss the FW file, you will get a message similar to:

wfx: Silicon Labs WFX_2.3.5
wfx-spi spi3.0: SPI transfer failed: -22
wfx-spi spi3.0: Falling back to user helper
wfx-spi spi3.0: can't load wfm_wf200_C0.sec, falling back to wfm_wf200.sec wfx-spi spi3.0: Falling back to user helper wfx-spi spi3.0: can't load wfm_wf200.sec
wfx-spi spi3.0: no error reported by secure boot
wfx-spi: probe of spi3.0 failed with error -11

In this situation, follow the instructions in https://github.com/SiliconLabs/wfx-firmware/blob/master/PDS/README.md to create the PDS file you need and copy it under /lib/firmware.

When SPI is not Working

If your SPI bus connection is not working, you will get traces similar to:

[   49.490494] wfx: Silicon Labs WFX_2.2.5
[   49.496933] wfx-spi spi0.0: chip mute. Bus configuration error or chip wasn't reset?
[   49.504816] wfx-spi: probe of spi0.0 failed with error -5

First of all, make sure that you have the proper SDIO_DAT2/HIF_SEL level following reset, as indicated in paragraph 'Host Interface' of the WF200 Datasheet

Second, you need to make sure you follow the Chip Select requirements in the Host Interface (keeping CS low for the entire length of a command).

Some processors will have CS going up between each byte. In this situation, refer to your processor's documentation to know how to use a GPIO instead of the HW SPI CS for Chip Select (under Linux, this is configured via the device tree, see 'cs-gpio' in the device tree documentation).

Once those checks are completed, if you still have startup issue you can start considering tracing HIF messages and connecting a logic analyzer to know more about what goes wrong. 

You may also refer to  the Linux Device Tree Debugging article first, to check your device tree adaptations.

Bash script to trace SPI HIF messages at Startup

#!/bin/bash
# usage:
# sudo ./trace_spi_startup

check_root()
{
    if [ $(id -u) != 0 ]; then
        echo "ERROR: please run this script as root (running 'sudo $(basename $0)' should work)" >&2
        exit 1
    fi
}

check_root

dmesg -C > /dev/null

echo "Loading wfx SPI driver..." > /dev/kmsg

echo spi0.0 > /sys/bus/spi/drivers/wfx-spi/unbind

echo 1 > /sys/kernel/debug/tracing/events/wfx/io_read/enable
echo 1 > /sys/kernel/debug/tracing/events/wfx/io_write/enable
echo 1 > /sys/kernel/debug/tracing/events/wfx/io_read32/enable
echo 1 > /sys/kernel/debug/tracing/events/wfx/io_write32/enable

echo spi0.0 > /sys/bus/spi/drivers/wfx-spi/bind

cat /sys/kernel/debug/tracing/trace_pipe &

echo 0 > /sys/kernel/debug/tracing/events/wfx/io_read/enable
echo 0 > /sys/kernel/debug/tracing/events/wfx/io_write/enable
echo 0 > /sys/kernel/debug/tracing/events/wfx/io_read32/enable
echo 0 > /sys/kernel/debug/tracing/events/wfx/io_write32/enable


exit 0

WF200 SPI Startup Debugging

When getting started with WF200 and using a SPI bus on a Linux platform, after adapting the device tree to your hardware (as described in https://github.com/SiliconLabs/wfx-linux-driver/blob/master/README.md#spi) you may still run into issues.

Part of this article (i.e. the SPI logic analyser captures) are also application to RTOS/Bare Metal use cases

This article provides detailed information on techniques used to trace SPI startup both using a logic analyser and HIF traces in the context of a Linux application.

Attached Files

The attached files are those used to illustrate this article:

• Spi_startup_log.txt contains the corresponding HIF traces
• traces_spi_startup_dmesg.txt contains the corresponding dmesg traces

SPI Startup Phase

Here is a zoomed-out capture of the SPI startup phase:

When zooming on the very first transactions (those used to check that the SPI connection is correct), we see:

then

In the traces, this corresponds to:

trace_spi_start-1844 [000] .... 1517.940786: io_write32: CONFIG: 00045600
trace_spi_start-1844 [000] .... 1517.940852: io_read32: CONFIG: 02045600
trace_spi_start-1844 [000] .... 1517.940902: io_write32: SET_GEN_R_W: 87000000
trace_spi_start-1844 [000] .... 1517.940946: io_read32: SET_GEN_R_W: 070b8775

Note the 16 bits swap: What the analyzer shows as '0x5600 0x0004' is traced as 00045600

Basically, if you reach this step you have a good chance that your SPI bus is properly working.

FW Download

The next steps are

• FW download
• PDS download

Those are also part of the traces and capture.

If you miss the FW file, you will get a message similar to:

wfx: Silicon Labs WFX_2.3.5
wfx-spi spi3.0: SPI transfer failed: -22
wfx-spi spi3.0: Falling back to user helper
wfx-spi spi3.0: can't load wfm_wf200_C0.sec, falling back to wfm_wf200.sec wfx-spi spi3.0: Falling back to user helper wfx-spi spi3.0: can't load wfm_wf200.sec
wfx-spi spi3.0: no error reported by secure boot
wfx-spi: probe of spi3.0 failed with error -11

In this situation, follow the instructions in https://github.com/SiliconLabs/wfx-firmware/blob/master/PDS/README.md to create the PDS file you need and copy it under /lib/firmware.

When SPI is not Working

If your SPI bus connection is not working, you will get traces similar to:

[   49.490494] wfx: Silicon Labs WFX_2.2.5
[   49.496933] wfx-spi spi0.0: chip mute. Bus configuration error or chip wasn't reset?
[   49.504816] wfx-spi: probe of spi0.0 failed with error -5

First of all, make sure that you have the proper SDIO_DAT2/HIF_SEL level following reset, as indicated in paragraph 'Host Interface' of the WF200 Datasheet

This is the situation where you can start considering tracing HIF messages and connecting a logic analyzer to know more about what goes wrong. 

You may also refer to  the Linux Device Tree Debugging article first, to check your device tree adaptations.

Bash script to trace SPI HIF messages at Startup

#!/bin/bash
# usage:
# sudo ./trace_spi_startup

check_root()
{
    if [ $(id -u) != 0 ]; then
        echo "ERROR: please run this script as root (running 'sudo $(basename $0)' should work)" >&2
        exit 1
    fi
}

check_root

dmesg -C > /dev/null

echo "Loading wfx SPI driver..." > /dev/kmsg

echo spi0.0 > /sys/bus/spi/drivers/wfx-spi/unbind

echo 1 > /sys/kernel/debug/tracing/events/wfx/io_read/enable
echo 1 > /sys/kernel/debug/tracing/events/wfx/io_write/enable
echo 1 > /sys/kernel/debug/tracing/events/wfx/io_read32/enable
echo 1 > /sys/kernel/debug/tracing/events/wfx/io_write32/enable

echo spi0.0 > /sys/bus/spi/drivers/wfx-spi/bind

cat /sys/kernel/debug/tracing/trace_pipe &

echo 0 > /sys/kernel/debug/tracing/events/wfx/io_read/enable
echo 0 > /sys/kernel/debug/tracing/events/wfx/io_write/enable
echo 0 > /sys/kernel/debug/tracing/events/wfx/io_read32/enable
echo 0 > /sys/kernel/debug/tracing/events/wfx/io_write32/enable


exit 0

Device tree debugging

On Linux platforms, devices are physically connected to buses and the device tree needs to reflect this for device to be detected.

It is important to debug device tree issues at startup. To achieve this, a very convenient tool is dtc (aka 'device tree compiler').

Keep in mind that any change to the device tree is only taken into account on the next reboot, so changing the device tree means rebooting!

Installing dtc

Installing dtc on the target machine is convenient, but may not be allowed on the target. We describe below an alternative solution, where dtc is installed on another machine.

apt-get install device-tree-compiler

Retrieving the current device tree rather than looking at the sources

The point with device tree is that looking at the sources (.dts/.dtsi) files you don't really have the view the host has on the final device tree.

To cope with this, we recommend looking at the 'device tree seen by the host', directly from the file system at /sys/firmware/device_tree/base/

• This reflects the device tree content after editing/compiling/booting

Retrieving the device tree using dtc

$ dtc --sort -I fs -O dts  /sys/firmware/devicetree/base > device_tree.out

NB: The 'dts' format allows the resulting file to be edited in a human-readable format. If edited as if it were a C file you can benefit from code folding to get a better view of the contents. With the '--sort' option, comparing device trees is much easier.

Retrieving the device tree without dtc support on your platform

• On your platform
  • Create an archive from your file system's device tree

tar zcf device_tree.tar.gz /sys/firmware/device_tree/base/

• Copy this file to a platform supporting dtc
• On a platform supporting dtc
  • decompress the archive
  • retrieve the device tree using dtc from the new directory (note how the path starts with 'sys' instead of '/sys' here, since the entire content has been extracted locally)

tar xvf device-tree.tar.gz
dtc --sort -I fs -O dts sys/firmware/devicetree/base/ > device_tree.out

Retrieving the device tree from the .dtb (device tree blob) file

As a last resort, get the .dtb file used at boot and decompile it using dtc on a platform supporting it.

$ dtc --sort -I dtb -O dts  your_dtb_file.dtb > device_tree.out

NB: Checking the device tree from the file system rather than from the .dtb file is safer, since it removes the risk of using the wrong file. The file system content is 'what the kernel sees'.

Debugging device tree issues by comparison

Once you have 2 different files before/after adding your device tree you can easily diff them and spot all differences brought in by your .dts/.dtsi source files.

In case of potential device tree issues, make sure all the changes you expect are visible, otherwise you may be facing issues in your .dts/.dtsi source files.

I created a general use KBA about Linux Device Tree Debugging:

https://www.silabs.com/community/wireless/wi-fi/knowledge-base.entry.html/2020/01/30/linux_device_treedebugging-WnIr

This should help locating device tree errors for SDIO or SPI WFx connection.

Device tree debugging

On Linux platforms, devices are physically connected to buses and the device tree needs to reflect this for device to be detected.

It is important to debug device tree issues at startup. To achieve this, a very convenient tool is dtc (aka 'device tree compiler').

Keep in mind that any change to the device tree is only taken into account on the next reboot, so changing the device tree means rebooting!

Installing dtc

Installing dtc on the target machine is convenient, but may not be allowed on the target. We describe below an alternative solution, where dtc is installed on another machine.

apt-get install device-tree-compiler

Retrieving the current device tree rather than looking at the sources

The point with device tree is that looking at the sources (.dts/.dtsi) files you don't really have the view the host has on the final device tree.

To cope with this, we recommend looking at the 'device tree seen by the host', directly from the file system at /sys/firmware/device_tree/base/

• This reflects the device tree content after editing/compiling/booting

Retrieving the device tree using dtc

$ dtc --sort -I fs -O dts  /sys/firmware/devicetree/base > device_tree.out

NB: The 'dts' format allows the resulting file to be edited in a human-readable format. If edited as if it were a C file you can benefit from code folding to get a better view of the contents. With the '--sort' option, comparing device trees is much easier.

Retrieving the device tree without dtc support on your platform

• On your platform
  • Create an archive from your file system's device tree

tar zcf device_tree.tar.gz /sys/firmware/device_tree/base/

• Copy this file to a platform supporting dtc
• On a platform supporting dtc
  • decompress the archive
  • retrieve the device tree using dtc from the new directory (note how the path starts with 'sys' instead of '/sys' here, since the entire content has been extracted locally)

tar xvf device-tree.tar.gz
dtc --sort -I fs -O dts sys/firmware/devicetree/base/ > device_tree.out

Retrieving the device tree from the .dtb (device tree blob) file

As a last resort, get the .dtb file used at boot and decompile it using dtc on a platform supporting it.

$ dtc --sort -I dtb -O dts  your_dtb_file.dtb > device_tree.out

NB: Checking the device tree from the file system rather than from the .dtb file is safer, since it removes the risk of using the wrong file. The file system content is 'what the kernel sees'.

Debugging device tree issues by comparison

Once you have 2 different files before/after adding your device tree you can easily diff them and spot all differences brought in by your .dts/.dtsi source files.

In case of potential device tree issues, make sure all the changes you expect are visible, otherwise you may be facing issues in your .dts/.dtsi source files.

Linux SDIO part detection on the SDIO bus

Under Linux, SDIO parts are bound to the mmc bus.

Before using a Wi-Fi part connected to the SDIO bus of a Linux system, it is necessary that the system detects the HW on the bus. 

When detection succeeds, the kernel has retrieved the VID/PID for the device.

Looking for a driver matching the VID/PID is only possible if the VID/PID has been retrieved from the device.

• As as consequence, device tree changes related to your device have no effect until SDIO detection is OK.

Linux systems will try to detect SDIO parts on the bus at boot, and every time the mmc bus is bound. Unbinding/binding the mmc bus is what we will use to trace mmc messages related to SDIO detection.

SDIO Detection message

The following message should be visible in dmesg once boot is complete:

mmcX new high speed SDIO card at address 0001

one-line check:

$ dmesg | grep 'new high speed SDIO'

• Until this message is present in dmesg
  

  • Any device tree change related to your part is not used by the kernel
  • it is useless to try to load the driver

If this message is not found, it is necessary to debug SDIO detection, going through the following steps:

1. Retrieving the current device tree 
2. Checking which mmc bus is used for SDIO
3. Making sure SDIO detection is enabled in the device tree
4. Checking the mmc bus commands during the SDIO detection phase
5. Checking the SDIO detection result

These steps are detailed below.

Keep in mind that any change to the device tree is only taken into account on the next reboot, so changing the device tree means rebooting!

Retrieving the current device tree

Refer to Linux Device Tree Debugging for information on retrieving the device tree content in a file.

Debugging device tree issues by comparison

1. Take a reference device tree snapshot from the file system without any change related to the new part.
2. Add you device tree changes
3. Take a new device tree snapshot from the file system with your part-related changes
4. Compare both files, making sure that every line you added reflects in the changes
5. In case there is any missing line, check you input .dts/.dtsi files

Making sure SDIO is enabled in Device Tree

In order for the Linux system to try detecting a part on the SDIO bus, the SDIO bus needs to be part of the Device Tree used at boot.

one-line check (SDIO pins selection):

$ grep sdio_pins device_tree.out

Typical result:

                sdio_pins = "/soc/gpio@7e200000/sdio_pins";
                        sdio_pins {

If this returns an empty line, SDIO detection is not even triggered. Refer to your system documentation to know how to add SDIO to the device tree.

Check the SDIO pins allocation in the 'sdio_pins' node to make sure they match your HW 

Checking which mmc bus is used for SDIO

one-line check (SDIO mmc bus selection):

$ grep -E "mmc[0-2]|mmc@" device_tree.out

The result should contain:

mmc1 = "/soc/sdio@7e300000";

or (depending on the kernel, i.e. the device tree version)

mmc = "/soc/mmc@7e300000";

If this returns an empty line, SDIO is not connected to any mmc bus. Refer to your system documentation to know how to add SDIO to the device tree.

Checking the mmc bus commands during the SDIO detection phase

Until the above checks are ok, it is pointless trying to trace SDIO detection messages, since detection is not even triggered.

This is the trickiest part, since it involves tracking message normally issued at boot, when the system is attempting SDIO detection. 

In reality, these are issued every time the mmc bus is bound to the system, so unbinding/binding the mmc bus will trigger a new detection attempt. We use this to avoid activating the traces at boot time, since this is not easy to do.

Preparing the kernel event traces (to be executed with root privileges):
Activating mmc request traces:

# echo 1 > /sys/kernel/debug/tracing/events/mmc/mmc_request_done/enable

Not tracing mmc CMD53 (once working in high-speed mode, to avoid being overloaded with traces once detected):

# echo 'cmd_opcode != 53' > /sys/kernel/debug/tracing/events/mmc/mmc_request_done/filter

Tracing the kernel events on mmc1 (adapt the mmc to your own use case):

# cat /sys/kernel/debug/tracing/trace_pipe | grep mmc1 &

Unbinding/Binding the mmc bus to trigger a reset and reload the driver: 

echo 3f300000.mmc > /sys/bus/platform/drivers/mmc-bcm2835/unbind 2>/dev/null
sleep 2
echo 3f300000.mmc > /sys/bus/platform/drivers/mmc-bcm2835/bind

Typical traces (limited view zooming on 'cmd_opcode' due to extra long lines):

2835/unbind 2>/dev/null
mmc_request[afec7ba4]: cmd_opcode=52
mmc_request[afec7ba4]: cmd_opcode=52
mmc_request[afec7bbc]: cmd_opcode=52
mmc_request[afec7bbc]: cmd_opcode=52

2835/bind
mmc_request[b9657df4]: cmd_opcode=52
mmc_request[b9657df4]: cmd_opcode=52
mmc_request[b9657e1c]: cmd_opcode=0 
mmc_request[b9657e24]: cmd_opcode=8 
mmc_request[b9657dd4]: cmd_opcode=5 
mmc_request[b9657d6c]: cmd_opcode=5 
mmc_request[b9657d74]: cmd_opcode=3 
mmc_request[b9657d7c]: cmd_opcode=7 
mmc_request[b9657d54]: cmd_opcode=52
. . .(26 times). . .
mmc_request[b9657cf4]: cmd_opcode=52

NB: The attached SDIO_Detection_mmc_request_done_traces.txt file contains the typical traces.

Stopping mmc request traces (once the traces have been retrieved):

This step is necessary to stop tracing, which is otherwise still active. No additional traces are shown because SDIO traffic only uses CMD53 once detection is complete, and CMD53 are filtered out. It is better to stop tracing completely.

# echo 0 > /sys/kernel/debug/tracing/events/mmc/mmc_request_done/enable

Checking the SDIO detection result

$ dmesg | grep mmc

If detection is correct, the 'mmcX new high speed SDIO card at address 0001' message is present in dmesg.

Otherwise, check for errors related to the mmc item corresponding to your part.

SDIO pins used for the detection phase

The SDIO detection as shown above only uses SD_CMD and SD_CLK pins, and is generally performed with a 400kHz SD_CLK. 

SD_DAT[3:0] are not used yet, so SDIO detection may succeed even though SD_DAT[3:0] are not properly routed.

Max SDIO speed too high

During the last steps of SDIO detection, the SoC sets the SDIO part to 'high-speed' mode on 4 data bits, then configures its own hardware to the maximum selected SDIO speed (controllable in the device tree) only at the very end of the SDIO detection, after a long series of about 26 CMD52 commands.

In case there are issues related to the max clock speed, the last CMD52 commands will return with 'cmd_err=-110' (which means 'TIMEOUT'), and will be followed by a short burst of about 4 CMD55 commands.

Whenever the SDIO detection loop fails, it is repeated with a slower clock speed (400, 300, 200, 100 kHz, respectively), but is still ending with the max clock. If the max clock is too high, all 4 loops will eventually fail, therefore the traces will show 4 repeated patterns of:

CMD52
CMD52
CMD0
CMD8
CMD5
CMD5
CMD7
CMD52
. . .
CMD52 / cmd_err=-110
CMD55 / cmd_err=-110
CMD55 / cmd_err=-110
CMD55 / cmd_err=-110
CMD55 / cmd_err=-110

And dmesg will show:

mmc1: error -110 whilst initialising SDIO card
mmc1: error -110 whilst initialising SDIO card
mmc1: error -110 whilst initialising SDIO card
mmc1: error -110 whilst initialising SDIO card

In this case, check your device tree documentation to check how to reduce the maximum SDIO clock.

Checking GPIO allocation

sudo cat /sys/kernel/debug/gpio

Output:

GPIOs 0-53, platform/3f200000.gpio, pinctrl-bcm2835:
 gpio-12 ( |wakeup ) out lo
 gpio-13 ( |reset ) out hi

GPIOs 100-101, platform/soc:virtgpio, brcmvirt-gpio, can sleep:
 gpio-100 ( |? ) out lo

Check that wakeup and reset are properly allocated

Linux SDIO part detection on the SDIO bus

Under Linux, SDIO parts are bound to the mmc bus.

Before using a Wi-Fi part connected to the SDIO bus of a Linux system, it is necessary that the system detects the HW on the bus. 

When detection succeeds, the kernel has retrieved the VID/PID for the device.

Looking for a driver matching the VID/PID is only possible if the VID/PID has been retrieved from the device.

• As as consequence, device tree changes related to your device have no effect until SDIO detection is OK.

Linux systems will try to detect SDIO parts on the bus at boot, and every time the mmc bus is bound. Unbinding/binding the mmc bus is what we will use to trace mmc messages related to SDIO detection.

SDIO Detection message

The following message should be visible in dmesg once boot is complete:

mmcX new high speed SDIO card at address 0001

one-line check:

$ dmesg | grep 'new high speed SDIO'

• Until this message is present in dmesg
  

  • Any device tree change related to your part is not used by the kernel
  • it is useless to try to load the driver

If this message is not found, it is necessary to debug SDIO detection, going through the following steps:

1. Retrieving the current device tree 
2. Checking which mmc bus is used for SDIO
3. Making sure SDIO detection is enabled in the device tree
4. Checking the mmc bus commands during the SDIO detection phase
5. Checking the SDIO detection result

These steps are detailed below.

Keep in mind that any change to the device tree is only taken into account on the next reboot, so changing the device tree means rebooting!

Retrieving the current device tree

Refer to https://www.silabs.com/community/wireless/wi-fi/knowledge-base.entry.html/2020/01/30/linux_device_treedebugging-WnIr for information on retrieving the device tree content in a file.

Debugging device tree issues by comparison

1. Take a reference device tree snapshot from the file system without any change related to the new part.
2. Add you device tree changes
3. Take a new device tree snapshot from the file system with your part-related changes
4. Compare both files, making sure that every line you added reflects in the changes
5. In case there is any missing line, check you input .dts/.dtsi files

Making sure SDIO is enabled in Device Tree

In order for the Linux system to try detecting a part on the SDIO bus, the SDIO bus needs to be part of the Device Tree used at boot.

one-line check (SDIO pins selection):

$ grep sdio_pins device_tree.out

Typical result:

                sdio_pins = "/soc/gpio@7e200000/sdio_pins";
                        sdio_pins {

If this returns an empty line, SDIO detection is not even triggered. Refer to your system documentation to know how to add SDIO to the device tree.

Check the SDIO pins allocation in the 'sdio_pins' node to make sure they match your HW 

Checking which mmc bus is used for SDIO

one-line check (SDIO mmc bus selection):

$ grep -E "mmc[0-2]|mmc@" device_tree.out

The result should contain:

mmc1 = "/soc/sdio@7e300000";

or (depending on the kernel, i.e. the device tree version)

mmc = "/soc/mmc@7e300000";

If this returns an empty line, SDIO is not connected to any mmc bus. Refer to your system documentation to know how to add SDIO to the device tree.

Checking the mmc bus commands during the SDIO detection phase

Until the above checks are ok, it is pointless trying to trace SDIO detection messages, since detection is not even triggered.

This is the trickiest part, since it involves tracking message normally issued at boot, when the system is attempting SDIO detection. 

In reality, these are issued every time the mmc bus is bound to the system, so unbinding/binding the mmc bus will trigger a new detection attempt. We use this to avoid activating the traces at boot time, since this is not easy to do.

Preparing the kernel event traces (to be executed with root privileges):
Activating mmc request traces:

# echo 1 > /sys/kernel/debug/tracing/events/mmc/mmc_request_done/enable

Not tracing mmc CMD53 (once working in high-speed mode, to avoid being overloaded with traces once detected):

# echo 'cmd_opcode != 53' > /sys/kernel/debug/tracing/events/mmc/mmc_request_done/filter

Tracing the kernel events on mmc1 (adapt the mmc to your own use case):

# cat /sys/kernel/debug/tracing/trace_pipe | grep mmc1 &

Unbinding/Binding the mmc bus to trigger a reset and reload the driver: 

echo 3f300000.mmc > /sys/bus/platform/drivers/mmc-bcm2835/unbind 2>/dev/null
sleep 2
echo 3f300000.mmc > /sys/bus/platform/drivers/mmc-bcm2835/bind

Typical traces (limited view zooming on 'cmd_opcode' due to extra long lines):

2835/unbind 2>/dev/null
mmc_request[afec7ba4]: cmd_opcode=52
mmc_request[afec7ba4]: cmd_opcode=52
mmc_request[afec7bbc]: cmd_opcode=52
mmc_request[afec7bbc]: cmd_opcode=52

2835/bind
mmc_request[b9657df4]: cmd_opcode=52
mmc_request[b9657df4]: cmd_opcode=52
mmc_request[b9657e1c]: cmd_opcode=0 
mmc_request[b9657e24]: cmd_opcode=8 
mmc_request[b9657dd4]: cmd_opcode=5 
mmc_request[b9657d6c]: cmd_opcode=5 
mmc_request[b9657d74]: cmd_opcode=3 
mmc_request[b9657d7c]: cmd_opcode=7 
mmc_request[b9657d54]: cmd_opcode=52
. . .(26 times). . .
mmc_request[b9657cf4]: cmd_opcode=52

NB: The attached SDIO_Detection_mmc_request_done_traces.txt file contains the typical traces.

Stopping mmc request traces (once the traces have been retrieved):

This step is necessary to stop tracing, which is otherwise still active. No additional traces are shown because SDIO traffic only uses CMD53 once detection is complete, and CMD53 are filtered out. It is better to stop tracing completely.

# echo 0 > /sys/kernel/debug/tracing/events/mmc/mmc_request_done/enable

Checking the SDIO detection result

$ dmesg | grep mmc

If detection is correct, the 'mmcX new high speed SDIO card at address 0001' message is present in dmesg.

Otherwise, check for errors related to the mmc item corresponding to your part.

SDIO pins used for the detection phase

The SDIO detection as shown above only uses SD_CMD and SD_CLK pins, and is generally performed with a 400kHz SD_CLK. 

SD_DAT[3:0] are not used yet, so SDIO detection may succeed even though SD_DAT[3:0] are not properly routed.

Max SDIO speed too high

During the last steps of SDIO detection, the SoC sets the SDIO part to 'high-speed' mode on 4 data bits, then configures its own hardware to the maximum selected SDIO speed (controllable in the device tree) only at the very end of the SDIO detection, after a long series of about 26 CMD52 commands.

In case there are issues related to the max clock speed, the last CMD52 commands will return with 'cmd_err=-110' (which means 'TIMEOUT'), and will be followed by a short burst of about 4 CMD55 commands.

Whenever the SDIO detection loop fails, it is repeated with a slower clock speed (400, 300, 200, 100 kHz, respectively), but is still ending with the max clock. If the max clock is too high, all 4 loops will eventually fail, therefore the traces will show 4 repeated patterns of:

CMD52
CMD52
CMD0
CMD8
CMD5
CMD5
CMD7
CMD52
. . .
CMD52 / cmd_err=-110
CMD55 / cmd_err=-110
CMD55 / cmd_err=-110
CMD55 / cmd_err=-110
CMD55 / cmd_err=-110

And dmesg will show:

mmc1: error -110 whilst initialising SDIO card
mmc1: error -110 whilst initialising SDIO card
mmc1: error -110 whilst initialising SDIO card
mmc1: error -110 whilst initialising SDIO card

In this case, check your device tree documentation to check how to reduce the maximum SDIO clock.

Checking GPIO allocation

sudo cat /sys/kernel/debug/gpio

Output:

GPIOs 0-53, platform/3f200000.gpio, pinctrl-bcm2835:
 gpio-12 ( |wakeup ) out lo
 gpio-13 ( |reset ) out hi

GPIOs 100-101, platform/soc:virtgpio, brcmvirt-gpio, can sleep:
 gpio-100 ( |? ) out lo

Check that wakeup and reset are properly allocated