Re: [PATCH 1/3] dt-bindings: soc: renesas: add MFIS binding documentation

[Geert Uytterhoeven]

Hi Krzysztof,

On Wed, 18 Mar 2026 at 10:17, Krzysztof Kozlowski <krzk@xxxxxxxxxx> wrote:
> On Tue, Mar 17, 2026 at 02:06:34PM +0100, Wolfram Sang wrote:
> > Add device tree bindings for the Renesas Multifunctional Interface
> > (MFIS) as found on the Renesas R-Car X5H (r8a78000) SoC. MFIS includes
> > features like Mailbox/HW Spinlock/Product Register.
> >
> > Signed-off-by: Wolfram Sang <wsa+renesas@xxxxxxxxxxxxxxxxxxxx>

> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/soc/renesas/renesas,r8a78000-mfis.yaml

> > +  "#hwlock-cells":
> > +    const: 1
> > +
> > +  "#mbox-cells":
> > +    const: 2
> > +    description:
> > +      The first cell is the channel number as specified in the documentation
> > +      of the SoC. The second cell may specify flags as described in the file
> > +      <dt-bindings/mailbox/renesas,r8a78000-mfis.h>.

> > --- /dev/null
> > +++ b/include/dt-bindings/mailbox/renesas,r8a78000-mfis.h
> > @@ -0,0 +1,27 @@
> > +/* SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) */
> > +/*
> > + * Constants for the mailbox part of the Renesas MFIS IP core.
> > + */
> > +
> > +#ifndef _DT_BINDINGS_MAILBOX_RENESAS_MFIS_H
> > +#define _DT_BINDINGS_MAILBOX_RENESAS_MFIS_H
> > +
> > +/*
> > + * MFIS HW design before r8a78001 requires a channel to be marked as either
> > + * TX or RX.
> > + */
> > +#define MFIS_CHANNEL_TX      (0 << 0)
>
> 0, bindings constants are abstract (so without dedicated meaning)
> numbers, starting from 0 or 1 and incremented by 1. Shifting this
> implies there is some other logic and that would mean - not a binding.
>
> > +#define MFIS_CHANNEL_RX      (1 << 0)
>
> 1
>
>
> > +
> > +/*
> > + * MFIS variants before r8a78001 work with pairs of IICR and EICR registers.
> > + * Usually, it is specified in the datasheets which of the two a specific core
> > + * should use. Then, it does not need extra description in DT. For plain MFIS
> > + * of r8a78000, this is selectable, though. According to the system design and
> > + * the firmware in use, these channels need to be marked. This is not needed
> > + * with other versions of the MFIS, not even with MFIS-SCP of r8a78000.
> > + */
> > +#define MFIS_CHANNEL_IICR    (0 << 1)
> > +#define MFIS_CHANNEL_EICR    (1 << 1)
>
> Same here.

These are flags as the documentation for the #mbox-cells property in the
bindings file states, to be ORed.

E.g. include/dt-bindings/i2c/i2c.h and include/dt-bindings/i3c/i3c.h
also use shifts to make this clear.
include/dt-bindings/gpio/gpio.h uses "Bit N express ..." comments instead.

Gr{oetje,eeting}s,

                        Geert

-- 
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- geert@xxxxxxxxxxxxxx

In personal conversations with technical people, I call myself a hacker. But
when I'm talking to journalists I just say "programmer" or something like that.
                                -- Linus Torvalds