Re: [PATCH RFC v1 2/3] dt-bindings: mailbox: Add thead,th1520-mailbox bindings

[Michal Wilczynski <m.wilczynski@samsung.com>]

Thank you for your review ! Will make sure all feedback is addressed in
v2.

On 9/18/24 22:36, Rob Herring wrote:
> On Wed, Sep 18, 2024 at 03:49:00PM +0200, Michal Wilczynski wrote:
>> Add bindings for the mailbox controller. This work is based on the vendor
>> kernel. [1]
>>
>> Link: https://protect2.fireeye.com/v1/url?k=385466ab-59df7384-3855ede4-74fe485cbfe7-af60aa2866e904f3&q=1&e=e3a5dfb9-1855-473e-9766-37a7ab5fbec5&u=https%3A%2F%2Fgithub.com%2Frevyos%2Fthead-kernel.git [1]
>>
>> Signed-off-by: Michal Wilczynski <m.wilczynski@samsung.com>
>> ---
>>  .../bindings/mailbox/thead,th1520-mbox.yaml   | 83 +++++++++++++++++++
>>  MAINTAINERS                                   |  1 +
>>  2 files changed, 84 insertions(+)
>>  create mode 100644 Documentation/devicetree/bindings/mailbox/thead,th1520-mbox.yaml
>>
>> diff --git a/Documentation/devicetree/bindings/mailbox/thead,th1520-mbox.yaml b/Documentation/devicetree/bindings/mailbox/thead,th1520-mbox.yaml
>> new file mode 100644
>> index 000000000000..f446fae76398
>> --- /dev/null
>> +++ b/Documentation/devicetree/bindings/mailbox/thead,th1520-mbox.yaml
>> @@ -0,0 +1,83 @@
>> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
>> +
>> +%YAML 1.2
>> +---
>> +$id: https://protect2.fireeye.com/v1/url?k=8a32b8a9-ebb9ad86-8a3333e6-74fe485cbfe7-0fff00bcf0ce8f57&q=1&e=e3a5dfb9-1855-473e-9766-37a7ab5fbec5&u=http%3A%2F%2Fdevicetree.org%2Fschemas%2Fmailbox%2Fthead%2Cth1520-mbox.yaml%23
>> +$schema: https://protect2.fireeye.com/v1/url?k=6b7f6c2c-0af47903-6b7ee763-74fe485cbfe7-f082b0e2a978f637&q=1&e=e3a5dfb9-1855-473e-9766-37a7ab5fbec5&u=http%3A%2F%2Fdevicetree.org%2Fmeta-schemas%2Fcore.yaml%23
>> +
>> +title: T-head TH1520 Mailbox Controller
>> +
>> +description: |
> 
> Don't need '|' if no formatting.
> 
>> +  The T-head mailbox controller enables two cores within the SoC to
>> +  communicate and coordinate by passing messages (e.g., data, status,
>> +  and control) through the mailbox channels. It also provides the ability
>> +  for one core to signal the other processor using interrupts.
>> +
>> +maintainers:
>> +  - Michal Wilczynski <m.wilczynski@samsung.com>
>> +
>> +properties:
>> +  compatible:
>> +    const: thead,th1520-mbox
>> +
>> +  reg:
>> +    description: Contains base addresses and sizes for the mailbox and remote ICUs.
> 
> Drop. Redundant.
> 
>> +    items:
>> +      - description: Mailbox local base address
>> +      - description: Remote ICU 0 base address
>> +      - description: Remote ICU 1 base address
>> +      - description: Remote ICU 2 base address
>> +
>> +  reg-names:
>> +    items:
>> +      - const: local_base
> 
> Just 'local'
> 
>> +      - const: remote_icu0
>> +      - const: remote_icu1
>> +      - const: remote_icu2
>> +
>> +  interrupts:
>> +    maxItems: 1
>> +    description: Interrupt for the mailbox controller.
> 
> Drop description. That's obvious.
> 
>> +
>> +  clocks:
>> +    maxItems: 1
>> +    description: Clock phandle for the mailbox controller.
> 
> Drop
> 
>> +
>> +  clock-names:
>> +    items:
>> +      - const: ipg
>> +
>> +  icu_cpu_id:
> 
> Needs a vendor prefix and s/_/-/.
> 
>> +    $ref: /schemas/types.yaml#/definitions/uint32
>> +    description: CPU ID for the ICU.
> 
> Constraints?

There are a total of four ICU's, so this could be constrained as you
say. Thanks will fix.

> 
> Nowhere in this patch is ICU defined.

ICU stands for Interrupt Controller Unit. Will make sure it's properly
documented.

> 
>> +
>> +  '#mbox-cells':
>> +    const: 2
>> +    description: Number of cells required to encode the mailbox specifier.
> 
> You need to say what each cell contains.
> 
>> +
>> +additionalProperties: false
>> +
>> +required:
>> +  - compatible
>> +  - reg
>> +  - reg-names
>> +  - interrupts
>> +  - icu_cpu_id
>> +  - '#mbox-cells'
>> +
>> +dependencies:
>> +  clock-names: [ clocks ]
> 
> Core schema already does this.
> 
>> +
>> +examples:
>> +  - |
>> +    mbox_910t: mbox@ffffc38000 {
> 
> Drop unused labels.
> 
> Standard name is 'mailbox', not 'mbox'.
> 
>> +      compatible = "thead,th1520-mbox";
>> +      reg = <0xff 0xffc38000 0x0 0x4000>,
>> +            <0xff 0xffc44000 0x0 0x1000>,
>> +            <0xff 0xffc4c000 0x0 0x1000>,
>> +            <0xff 0xffc54000 0x0 0x1000>;
>> +      reg-names = "local_base", "remote_icu0", "remote_icu1", "remote_icu2";
>> +      interrupts = <28 IRQ_TYPE_LEVEL_HIGH>;
>> +      icu_cpu_id = <0>;
>> +      #mbox-cells = <2>;
>> +    };
>> diff --git a/MAINTAINERS b/MAINTAINERS
>> index 7331b30deef8..49198b2ed2e7 100644
>> --- a/MAINTAINERS
>> +++ b/MAINTAINERS
>> @@ -19719,6 +19719,7 @@ L:	linux-riscv@lists.infradead.org
>>  S:	Maintained
>>  T:	git https://protect2.fireeye.com/v1/url?k=a5b0cb39-c43bde16-a5b14076-74fe485cbfe7-e7359d7be6d6a5b5&q=1&e=e3a5dfb9-1855-473e-9766-37a7ab5fbec5&u=https%3A%2F%2Fgithub.com%2Fpdp7%2Flinux.git
>>  F:	Documentation/devicetree/bindings/clock/thead,th1520-clk-ap.yaml
>> +F:	Documentation/devicetree/bindings/mailbox/thead,th1520-mbox.yaml
>>  F:	arch/riscv/boot/dts/thead/
>>  F:	drivers/clk/thead/clk-th1520-ap.c
>>  F:	drivers/mailbox/mailbox-th1520.c
>> -- 
>> 2.34.1
>>
>