I2S Interface Debugging and DTS Configuration on the RK3568 Platform

1. Project Objective

The core objective of this task was to successfully enable and debug multiple I2S interfaces (I2S1, I2S2, I2S3) on the RK3568 platform to establish digital audio communication with external devices, such as an FPGA. This specifically included:

  • Configuring I2S1 and I2S3 as audio output (Playback).
  • Configuring I2S2 as audio input (Capture).

2. Debugging Workflow and Process

The entire debugging process followed a clear workflow: Hardware Analysis -> DTS Configuration -> Command-line Testing -> Problem Isolation and Resolution.

  1. Preparation - Hardware Resource Analysis:

    • First, the I2S hardware resources of the RK3568 SoC were analyzed to clarify the basic functions and use cases of the I2S0/1/2/3 controllers (e.g., I2S0 for HDMI, I2S1/2/3 for general purpose).
    • The I2S controller nodes (i2s@fe4...) in the DTS were mapped to the corresponding GPIO pins on the product schematic, laying a solid foundation for the subsequent pinctrl configuration.

  2. Implementation - DTS Configuration and Sound Card Registration:

    • Utilized the simple-audio-card driver model to “link” the SoC’s I2S controller (CPU DAI) with a virtual dummy-codec (Codec DAI), thereby registering three separate sound cards within the ALSA framework.
    • DTS nodes were written for card 1 (I2S1, output), card 2 (I2S2, input), and card 3 (I2S3, output) respectively.

  3. Verification - Systematic Testing and Issue Detection:

    • Using the aplay -l and arecord -l commands, it was successfully verified that all three sound cards were registered in the system.
    • I2S1 (Output): Tested with speaker-test -D hw:1,0 ...; the device functioned normally with no errors.
    • I2S2 (Input): Tested with arecord -D hw:2,0 ...; the command hung as expected while waiting for an external clock, which is consistent with the correct behavior of I2S Slave mode.
    • I2S3 (Output): Tested with speaker-test -D hw:3,0 ...; a critical issue was discovered: although the device could be opened, it continuously reported a Write error: -32, Broken pipe error.

3. Core Knowledge Acquisition and Consolidation

During the debugging process, a systematic understanding of the Linux audio subsystem and DTS was developed.

  • I2S Protocol Fundamentals:

    • Pin Functions: Clarified the core roles of SCLK (Bit Clock), WS/LRCLK (Frame Sync/Left-Right Select), SD/D0 (Serial Data), and MCLK (Master Clock).
    • Master/Slave Mode: Gained an in-depth understanding of the differences between Master (clock provider) and Slave (clock consumer) modes, and mastered the “data source as the clock source” best practice principle (SoC as Master for output, SoC as Slave for input).

  • Linux Audio Subsystem (ASoC & ALSA):

    • ASoC Architecture: Mastered the core “Platform-Codec-Machine” three-component decoupled architecture. Clearly mapped the rockchip-i2s-tdm driver to Platform, dummy-codec to Codec, and simple-audio-card to Machine.
    • DAI Concept: Understood that CPU DAI and Codec DAI are the two software endpoints used by the Machine driver for “linking”.

  • In-depth Device Tree (DTS) Application:

    • Master/Slave Configuration: Confirmed that I2S Master/Slave mode is configured within the simple-audio-card node via properties like simple-audio-card,bitclock-master and simple-audio-card,frame-master, not in the I2S hardware node itself.
    • Debugging Tools: Mastered the core debugging technique of using the dtc utility for reverse engineering. The ability to decompile a .dtb back to a .dts on the development host to inspect the final effective device tree became the key to solving critical issues.

4. Key Issues and Solutions

Two typical issues were encountered and successfully resolved through analysis.

  • Issue 1: DTS Compilation Failure: Unable to parse input tree

    • Symptom: Adding a standalone dummycodec node in a .dtsi file caused a syntax error during compilation.
    • Analysis: DTS syntax requires that all custom top-level nodes must be contained within the scope of the root node / { ... };.
    • Solution: The dummycodec node definition was moved inside the / { ... }; structure, resolving the issue and deepening the understanding of DTS file structure.

  • Issue 2: Continuous Broken pipe Errors During I2S3 Testing

    • Symptom: speaker-test constantly encountered data underrun errors when writing data to I2S3.
    • Analysis Process:
      1. Initial Check: Tried simplifying the pinctrl configuration for I2S3, but the issue persisted.
      2. Core Method - Comparative Analysis: Since I2S1 was working correctly, its final configuration served as the “golden reference.”
      3. Key Tool - dtc: Used the dtc utility to decompile the final .dtb file and extract the effective node definitions for I2S1 and I2S3 for a line-by-line comparison.
      4. Difference Found: Discovered that the problematic I2S3 node contained an extra proprietary property, rockchip,bclk-fs = <32>;, which was absent in the working I2S1 node.
    • Root Cause: This proprietary property forced the I2S hardware to use a fixed clock ratio, which conflicted with the dynamic ratio being set by the simple-audio-card driver, leading to hardware malfunction.
    • Solution: In the board-level DTS file, the conflicting property inherited from the upstream .dtsi was explicitly removed using the /delete-property/ rockchip,bclk-fs; directive for the &i2s3_2ch node, completely resolving the problem.

5. Testing Methods and Tools

This debugging effort led to the establishment of a standard, reproducible command-line testing (and debugging) workflow:

  • Device Enumeration: aplay -l / arecord -l (To check if sound cards are registered)
  • Output Testing: speaker-test -D hw:X,Y -c 2 -r 48000 -f S16_LE (To verify the output path without needing an audio file)
  • Input Testing: arecord -D hw:X,Y -c 2 -r 48000 -f S16_LE -d 5 test.wav (To verify the input path configuration)
  • DTS Verification: dtc -I dtb -O dts -o final.dts <path_to_dtb> (To decompile and inspect the final device tree)

6. Tech Stack and Tools

  • Hardware Platform: Rockchip RK3568 SoC
  • Software Environment: Linux Kernel 5.10, Buildroot
  • Core Technologies: Device Tree (DTS), I2S ASoC Subsystem
  • Debugging Tools: dtc, speaker-test, aplay, arecord, dmesg, serial console