Re: [PATCH RFC 05/12] dt-bindings: serial: Add BL808 UART

[sashiko-bot@kernel.org]

Thank you for your contribution! Sashiko AI review found 2 potential issue(s) to consider:
- [Medium] dt-bindings: serial: missing SoC-specific compatible in bflb,uart.yaml
- [Low] dt-bindings: serial: unused label in bflb,uart.yaml example
--

commit 1bdd5b51639067c3a28b1a40beeb8fbfbbc65a65
Author: Kwanghoon Son <asdfkwang@gmail.com>

dt-bindings: serial: Add BL808 UART

This commit adds the Device Tree binding schema for the Bouffalo Lab UART
controller, describing its register range, interrupt, and baud clock input.

Link: https://docs.zephyrproject.org/latest/build/dts/api/bindings/serial/bflb,uart.html

> diff --git a/Documentation/devicetree/bindings/serial/bflb,uart.yaml b/Documentation/devicetree/bindings/serial/bflb,uart.yaml
> new file mode 100644
> index 0000000000000..df29d258f0a1c
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/serial/bflb,uart.yaml
> @@ -0,0 +1,57 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/serial/bflb,uart.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Bouffalo Lab UART Controller
> +
> +description: |
> +  UART IP used by Bouffalo Lab SoCs. Initial Linux support covers the
> +  BL808 controller with a 32-byte FIFO. The compatible follows Zephyr.
> +
> +maintainers:
> +  - Kwanghoon Son <asdfkwang@gmail.com>
> +
> +allOf:
> +  - $ref: serial.yaml#
> +
> +properties:
> +  compatible:
> +    const: bflb,uart

[Severity: Medium]
Should the compatible property in Documentation/devicetree/bindings/serial/bflb,uart.yaml
include a SoC-specific compatible string such as bflb,bl808-uart (either
alone or with bflb,uart as a fallback), and should the description section
describe the hardware rather than what Linux currently supports?

Documentation/devicetree/bindings/writing-bindings.rst requires SoC-specific
compatible strings for SoC devices rather than generic vendor-wide names, and
notes that bindings should describe the hardware rather than what an OS or
driver currently supports.

In the accompanying driver (drivers/tty/serial/bflb_uart.rs), tx_empty()
relies on a hardcoded 32-byte FIFO depth to check whether all TX FIFO slots
are free:

    const FIFO_DEPTH: u32 = 32;
    ...
    fn tx_empty(&self) -> bool {
        self.read::<FIFO_CONFIG1>() & TX_FIFO_CNT_MASK == FIFO_DEPTH
    }

Without a SoC-specific compatible string like bflb,bl808-uart, Device Trees
using only bflb,uart cannot distinguish the BL808 UART from other Bouffalo Lab
SoCs with different FIFO depths or hardware capabilities without breaking the
DT ABI.

[ ... ]

> +examples:
> +  - |
> +    #include <dt-bindings/interrupt-controller/irq.h>
> +
> +    uart3: serial@30002000 {
> +        compatible = "bflb,uart";

[Severity: Low]
Can the unused uart3 label be dropped from the serial@30002000 node in the
examples section of Documentation/devicetree/bindings/serial/bflb,uart.yaml?

Because uart3 is never referenced by a phandle in the example, running
scripts/dtc/dt-check-style --mode=strict reports an unused-labels warning in
check_unused_labels().

-- 
Sashiko AI review · https://sashiko.dev/#/patchset/20261029-rust-bl808-console-v1-0-b736ee920078@gmail.com?part=5