How-to: Display Interface Debugging Standard Operating Procedure (SOP)

Categories:

  6 minute read  

How-to: Display Interface Debugging Standard Operating Procedure (SOP)

Phase 1: Preparation & Info Gathering

Goal: Before writing any code or DTS, ensure you have all the necessary “blueprints” and “manuals.”

  1. Obtain the Hardware Schematic: This is your foundation. You need to know:

    • Which physical interface on the main SoC is the display interface (MIPI/LVDS) connected to? (DSI0 or DSI1?)
    • Which GPIO or PWM controller are the relevant control pins (RESET, POWER_ENABLE, BACKLIGHT_PWM) connected to?
    • Which I2C controller on the main SoC is the interface’s I2C bus connected to? (Used for touch or configuring bridge chips).

  2. Obtain the Target Device “Manual” (Datasheet): Your “screen” could be a physical panel or an FPGA.

    • If it’s a physical panel: Obtain the datasheet for the screen module. You need to find:
      • display-timings: Resolution, refresh rate, h/v porch, sync len, etc.
      • panel-init-sequence: The long string of DCS commands that need to be sent after power-on.
      • Interface parameters: How many MIPI lanes? Is the data format RGB888 or RGB666?
      • Power supply and reset timing requirements: Should power be applied before reset? What are the required delays in milliseconds?
    • If it’s an FPGA: Treat the FPGA engineer as your datasheet. Ask them for all the parameters listed above. The FPGA’s design document is your “manual.”

  3. Obtain Platform Reference Materials:

    • The SoC’s TRM (Technical Reference Manual): To understand the working principles of modules like VOP, DSI/LVDS controllers, Pinctrl, etc.
    • Official DTS examples from the SoC’s SDK: This is your best source for copying and reference, especially for VOP routing and Pinctrl configurations.

Phase 1 Deliverable: A checklist of information containing all the parameters needed for the DTS, as well as a clear understanding of the hardware connections. In this context, your colleague’s DTS is part of the “target device manual.”

Phase 2: DTS Configuration & Compilation

Goal: “Translate” the information gathered in Phase 1 into the DTS language, so the kernel knows how to drive the hardware.

  1. Configure Pin Control (pinctrl):

    • In the pinctrl node, configure the correct function multiplexing for all pins required by the display interface (data lines, clock lines, control lines). Refer to the official DTS examples for syntax.

  2. Configure Core Controllers (&dsi0, &vop, etc.):

    • Enable (status = "okay";) the VOP, DSI/LVDS controller, MIPI PHY, etc.

  3. Configure Display Routing:

    • This is a critical platform-specific step. Correctly connect the VOP’s output to the display interface’s input, following the official DTS examples.

  4. Create the Panel Node:

    • Under the corresponding interface node (e.g., &dsi0), create a panel sub-node.
    • Fill in all the parameters obtained from the datasheet/FPGA engineer: compatible, reg, display-timings, dsi,lanes, dsi,format, etc.
    • Key Principle: If connecting directly to a physical panel, fill in all parameters (including the initialization sequence). If the output is for an FPGA, only fill in the core timing parameters required by the FPGA and remove everything related to the physical panel (backlight, init sequence, power supplies, etc.).

  5. Compile the Kernel: Ensure there are no DTS syntax errors.

Phase 2 Deliverable: A successfully compiled kernel image (e.g., boot.img) that includes the new display configuration.

Phase 3: Low-level Validation

Goal: Without relying on high-level applications (Android/Linux Desktop), verify that the kernel driver has loaded correctly and that physical signals are being output. This is the most critical step!

  1. Check the Kernel Log (dmesg):

    • Flash the new kernel and boot into the serial console.
    • Enter dmesg | grep -i panel: See if your panel driver (e.g., simple-panel) was successfully probed (loaded). If there are errors, the log will tell you the reason (e.g., pinctrl not found, failed to get clock, etc.).
    • Enter dmesg | grep -i dsi or dmesg | grep -i drm: Check for errors from the DRM (Direct Rendering Manager) subsystem and the DSI controller.

  2. Check the Sysfs Interface (/sys):

    • ls /sys/class/drm/: You should see a node representing your screen, such as card0-DSI-1.
    • cat /sys/class/drm/card0-DSI-1/modes: Check the resolution and timings recognized by the kernel. This must match what you configured in the DTS!
    • cat /sys/class/backlight/.../brightness: If you have a backlight, try writing a brightness value to see if the backlight responds.

  3. Physical Signal Measurement (The Moment of Truth):

    • Use an oscilloscope! This is your eyes.
    • Measure the MIPI/LVDS clock line:
      • Is there a waveform? A waveform indicates that the PHY and controller are at least working.
      • Is the waveform frequency correct? This verifies if your clock-frequency configuration has taken effect.
    • Measure the MIPI/LVDS data lines:
      • Are there data signals? (MIPI typically shows bursty data).
    • At this point, if the screen/FPGA is not yet working correctly, but you see the correct clock and data signals on the oscilloscope, then congratulations! The driver configuration on the Rockchip side is most likely correct. The problem has now shifted to the screen/FPGA side.

Phase 3 Deliverable: Confirmation that the kernel driver has loaded and that there are signal outputs on the SoC’s physical pins. Do not proceed to the next phase until this one is complete.

Phase 4: High-level Integration & Debugging

Goal: With the low-level signals confirmed to be OK, resolve issues related to display content, colors, offsets, etc.

  1. Verify Display Content:

    • If the system can boot to the desktop, check if the display is normal.
    • If the screen is black but low-level signals are present, the problem could be:
      • Incorrect or incomplete panel-init-sequence (for physical panels).
      • Slight deviations in timing parameters (e.g., a porch value is off by one or two pixels).
      • Data format mismatch (data-mapping for LVDS, dsi,format for MIPI).
      • The FPGA side is not configured correctly (your situation).
      • Physical connection issues (poor cable contact, differential pairs swapped, etc.).

  2. Use Debugging Tools:

    • Rockchip’s modetest tool: This can force a color bar test pattern on a specific display, bypassing the complex UI system. It is an excellent tool for verifying the DRM driver and hardware path.
    • cat /dev/urandom > /dev/fb0: Pipe random data to the framebuffer device to see if “snow” or static appears on the screen. If there is activity, it means the path from memory to the screen is working.
    • Adjust DTS parameters: Based on display anomalies (e.g., screen corruption, color cast, incomplete display), fine-tune parameters like display-timings, data-mapping, recompile, and iterate quickly.

Phase 4 Deliverable: A normally functioning display or a video stream that is correctly received and processed by the FPGA.

By following this procedure, you can break down the vague task of “lighting up a screen” into clear, verifiable sub-goals. Each step has defined entry criteria and deliverables, allowing you to systematically locate problems instead of relying on guesswork.