RK3288 Tinker Board S Device Tree Support

by Admin 42 views
Supporting the ASUS Tinker Board S: A Deep Dive into Device Tree Integration

This article delves into the technical aspects of integrating the ASUS Tinker Board S into the Linux kernel. We'll explore the significance of the device tree patch, dissecting its code and understanding its impact on hardware compatibility and system functionality. This is a learning report about patch 2/3 - Add device tree support for Rockchip RK3288 Tinker Board S.

1. Patch Overview: Enabling eMMC on the Tinker Board S

What problems does this patch address? ASUS has released a new version of its development board called the "Tinker Board S." While largely identical to the older "Tinker Board," a key difference lies in its use of onboard eMMC flash memory for primary storage, replacing the SD card slot of the original. To ensure the Linux kernel can properly identify and utilize this new hardware, especially its unique eMMC storage, a dedicated "hardware description" is required. This patch provides that description for the "Tinker Board S," ensuring the kernel recognizes it during boot and activates its onboard storage functionality.

What are the core changes introduced by the patch? The core of this patch is the addition of a device tree source file (DTS): rk3288-tinker-s.dts. This file reuses all common hardware definitions from the existing rk3288-tinker.dtsi file via the #include directive to maximize code reuse. Building upon this, it accomplishes two key things: First, it defines new model and compatible strings in the root node to precisely identify the "Tinker Board S" as a new model. Second, it explicitly enables the eMMC controller by setting the status property of the &emmc node to "okay". This is the core hardware difference between this model and the base model.

2. Essential Technical Background: Understanding Device Trees

Device Tree (DTS/DTB): A device tree is a data structure describing hardware device information, separating hardware details (such as CPU model, memory address, peripheral connections, etc.) from the kernel driver code. This allows the same kernel image to run on multiple boards with different hardware configurations without modification, simply by providing a corresponding device tree file at boot time. DTS (.dts) is a human-readable source format compiled into a binary DTB (.dtb) file, which the bootloader passes to the kernel during startup.

The compatible Property: This is one of the most crucial attributes in a device tree. It's a string list used to uniquely identify a device. The kernel's driver model uses this compatible string to find and match the most suitable driver. The list typically ranges from the most specific name to the most general (e.g., ["asus,rk3288-tinker-s", "asus,rk3288-tinker", "rockchip,rk3288"]), providing a "fallback" mechanism. If the kernel doesn't find a specific driver for tinker-s, it attempts to find a driver for tinker, and so on. Guys, this is how it works, makes sense right?

status = "okay": Within a device tree, a hardware node's enabled state is controlled by the status property. If status is set to "okay" (or the attribute is absent), the hardware device is enabled, and the kernel loads its driver. Setting it to "disabled" causes the kernel to completely ignore the device. This mechanism is ideal for describing hardware platform differences. All possible hardware modules can be defined in a common .dtsi file (and disabled by default), then only the actually present hardware modules are enabled by setting their status to "okay" in the specific board's .dts file. This patch leverages this feature to enable eMMC functionality. It's a clean and efficient way to manage hardware configurations, don't you think?

3. In-Depth Code Review: Dissecting the Device Tree Source

Review Findings and Analysis

Let's dive into the code and see what's really going on! This part is where we become detectives and look closely at the changes made.

File: arch/arm/boot/dts/rk3288-tinker-s.dts

+ // SPDX-License-Identifier: (GPL-2.0+ OR MIT)
+ /*
+ * Copyright (c) 2019 VRULL GmbH
+ * Author: Philipp Tomsich <philipp.tomsich@vrull.eu>
+ */
+ /dts-v1/;
+ #include "rk3288-tinker.dtsi"
+
+ / {
+ model = "ASUS Tinker Board S";
+ compatible = "asus,rk3288-tinker-s", "asus,rk3288-tinker", "rockchip,rk3288";
+ };
+
+ &emmc {
+ status = "okay";
+ };

Code Interpretation:

This code defines a brand new device tree file specifically to support the ASUS Tinker Board S. Guys, think of it as the board's ID card for the kernel!

  • #include "rk3288-tinker.dtsi": This line is key. It first includes all the hardware definitions for the base Tinker Board. This means all common hardware parts (like the CPU, USB, Ethernet, etc.) don't need to be described again. This is like saying, "Hey, it's mostly like the original Tinker Board, so let's start with that description!"

  • / { ... };: This root node section modifies and supplements the root node in the included file. It sets model to "ASUS Tinker Board S", allowing the operating system to display the correct board name. At the same time, it defines the compatible property, adding the most specific identifier asus,rk3288-tinker-s and preserving compatibility with older models and generic chips. This is how the system knows exactly what it's dealing with, and what drivers to use.

  • &emmc { status = "okay"; };: This part is the core functionality of this patch. &emmc is a reference to the eMMC controller node. In the generic .dtsi or higher-level dts file, this node may be defined, but its status is "disabled". By explicitly setting its state to "okay" here, this patch activates the eMMC storage functionality unique to the Tinker Board S. Boom! The eMMC is online and ready to roll.

Checklist Review & Assessment:

  1. Logic & Functional Correctness: The code logic is completely correct. Sharing common definitions via #include and then only overwriting or appending for differences is a best practice in device tree design. Line 14's status = "okay"; correctly switches the eMMC device from disabled to enabled, precisely achieving the goal of adding support for a new hardware variant. The addition of the compatible string also ensures that the kernel driver can correctly match this new device. No logical issues were found. This is solid work, folks.

  2. Coding Style & Readability: The code follows the standard coding style for Linux kernel device tree files. The file header contains the standard SPDX license identifier and copyright information. The code structure is clear, indentation is correct, and a concise and clear node referencing method (&emmc) is used. Overall readability is very high. No style issues were found. It's easy to read and understand, which is always a plus.

  3. Potential Risk Assessment: This change is a new file specifically for new hardware and does not affect the support of any existing boards. It does not modify any shared code or driver logic. Therefore, the risk of introducing regression errors is zero. From a performance and security perspective, the patch only describes hardware and does not involve any execution logic, so there is no possibility of introducing new risks. It's a low-risk, high-reward situation.

  4. Architecture & Maintainability: This patch is exemplary in its architecture. It maximizes the reuse of rk3288-tinker.dtsi content through inheritance and extension, greatly enhancing code maintainability. In the future, if there are common hardware updates to the Tinker Board series (e.g., updating the configuration of a peripheral), only the shared .dtsi file needs to be modified, and all derivative models (including the "S" model here) will automatically benefit. This design makes adding new members to the hardware family very simple and low-risk. It's all about being efficient and organized.

  5. Details & Nit-picking: The code quality is high, but there is one detail that could be improved, as also suggested in the community discussion. In the compatible property on line 10, the strings "asus,rk3288-tinker" and "rockchip,rk3288" are redundant. This is because the root node in the included rk3288-tinker.dtsi file likely already defines these compatibility strings. Defining them again in the .dts file will overwrite the definitions in the .dtsi, which, although the result is the same, creates unnecessary duplication. A more concise and "Don't Repeat Yourself" (DRY) approach would be to only define the most specific compatible string here and rely on the include mechanism to provide more generic fallback options. Ideally, this line should be modified to only include "asus,rk3288-tinker-s" and its inherited "asus,rk3288-tinker", or, if the inheritance chain is already handled in the .dtsi, then only compatible = "asus,rk3288-tinker-s"; would be needed here. It's a small detail, but it's all about keeping things clean and efficient.

4. Community Review: Feedback and Improvements

Thread 1: Philipp Tomsich - Community Review and Feedback on the Patch

  • Philipp Tomsich at Mon, 20 May 2019 13:11:05 +0200:

    • Core point: Submit patch to add device tree support for Asus Tinker Board S. The main difference between this board and the standard Tinker Board is the replacement of the SD card slot with 16GB of eMMC.

    • Labels: (None)

      (EN) The Asus Tinker Board S uses the same baseboard as the Tinker Board, but replaces the SD-Card socket with 16GB of on-board eMMC storage. This commit adds a device-tree for the Tinker Board S by including the existing tinker.dtsi and enabling the on-board eMMC. (ZH) Asus Tinker Board S 使用了与 Tinker Board 相同的基础板，但用 16GB 的板载 eMMC 存储替换了 SD 卡插槽。此提交通过包含现有的 tinker.dtsi 并启用板载 eMMC，为 Tinker Board S 添加了设备树。

    • Heiko Stuebner (replied to Philipp Tomsich) at Mon, 20 May 2019 13:15:16 +0200:

      • Core point: Expressed approval of the patch.
      • Labels: Acked-by: Heiko Stuebner <heiko@sntech.de>

      (EN) Acked-by: Heiko Stuebner <heiko@sntech.de> (ZH) 认可：Heiko Stuebner <heiko@sntech.de>

    • Nicolas Boichat (replied to Philipp Tomsich) at Mon, 20 May 2019 07:22:20 -0400:

      • Core point: Suggested removing the redundant "asus,rk3288-tinker" string from the compatible property because it already exists in the included rk3288-tinker.dtsi file. Given the Reviewed-by label with the acceptance of this modification.
      • Labels: Reviewed-by: Nicolas Boichat <nicolas.boichat@gmail.com>

      (EN) I think you can drop the "asus,rk3288-tinker" compatible, as it is already present in rk3288-tinker.dtsi which you are including. With this change: (ZH) 我认为你可以去掉 "asus,rk3288-tinker" 这个 compatible 字符串，因为它已经存在于你所包含的 rk3288-tinker.dtsi 文件中了。作此修改后：

      • Philipp Tomsich (replied to Nicolas Boichat) at Mon, 20 May 2019 13:25:21 +0200:

        • Core point: Agreed with Nicolas's point and stated that he would remove the redundant compatible string in the next version of the patch.

        (EN) Good point. I will drop the redundant compatible-string from the next version of the patch. (ZH) 说得好。我会在下一个版本的补丁中去掉这个多余的 compatible 字符串。

        • Nicolas Boichat (replied to Philipp Tomsich) at Mon, 20 May 2019 07:31:02 -0400:
          • Core point: Thanked the author for the confirmation and reiterated that his Reviewed-by label is valid.

          (EN) Thanks. My Reviewed-by tag still stands, then. (ZH) 谢谢。那么我的 Reviewed-by 标签依然有效。

In summary, the community review process highlighted a minor redundancy in the compatible property, which the author acknowledged and planned to address in a subsequent patch version. This collaborative approach ensures code quality and adherence to best practices.