[v2,03/12] dt-bindings: connector: Add the GOcontroll Moduline module slot bindings

From: Maud Spierings <maudspierings@gocontroll.com>

Add the bindings that describe a GOcontroll Moduline module slot. This
slot provides all the interfaces to interface with a Moduline compatible
IO module. The actual module is not reasonable to describe as it can be
swapped at will, with this connector the driver will be able to probe
for a module on boot.

The connector consists of 2 parts, one part for interfacing with the SoC
and main board, the other part has 13 IO channels for the module to
interact with the outside world. The functions of these IO channels are
determined by the type of module in the slot. The IO on the SoC side is
as follows:

 - a 3v3 supply, this tends to be the logic level of the module and its
   microcontroller
 - a 5v0 supply, this can be used to power low power peripherals on the
   module
 - a 6v-8v supply, this can be used for high power peripherals on the
   module
 - a 6v-30v supply, this tends to be a dirty supply that comes from the
   controller supply after some circuit protection, or is the same as
   the 6v-8v supply.
 - an SPI bus which carries the communication between the SoC and the
   microcontroller on the module.
 - an I2C bus shared between the SoC and all module slots which can
   carry direct module-to-module communication.
 - a reset line
 - an interrupt line that indicates a clear to transmit signal
 - a sync line shared between the SoC and all module slots which could
   be used to synchronize modules for time sensitive IO spread across
   modules.
 - a SMBus alert line that is shared between the modules but is not
   connected to the SoC so that is ignored.

A slot-number property is used to identify the physical location of a
module slot. Without it, it would be impossible to identify which module
to control if there are multiple of one type, to address the desired IO.

Signed-off-by: Maud Spierings <maudspierings@gocontroll.com>
---
 .../connector/gocontroll,moduline-module-slot.yaml | 88 ++++++++++++++++++++++
 1 file changed, 88 insertions(+)

On Wed, Feb 26, 2025 at 03:19:14PM +0100, Maud Spierings wrote:
> Add the bindings that describe a GOcontroll Moduline module slot. This
> slot provides all the interfaces to interface with a Moduline compatible
> IO module. The actual module is not reasonable to describe as it can be
> swapped at will, with this connector the driver will be able to probe
> for a module on boot.
> 
> The connector consists of 2 parts, one part for interfacing with the SoC
> and main board, the other part has 13 IO channels for the module to
> interact with the outside world. The functions of these IO channels are
> determined by the type of module in the slot. The IO on the SoC side is
> as follows:
> 
>  - a 3v3 supply, this tends to be the logic level of the module and its
>    microcontroller
>  - a 5v0 supply, this can be used to power low power peripherals on the
>    module
>  - a 6v-8v supply, this can be used for high power peripherals on the
>    module
>  - a 6v-30v supply, this tends to be a dirty supply that comes from the
>    controller supply after some circuit protection, or is the same as
>    the 6v-8v supply.
>  - an SPI bus which carries the communication between the SoC and the
>    microcontroller on the module.
>  - an I2C bus shared between the SoC and all module slots which can
>    carry direct module-to-module communication.
>  - a reset line
>  - an interrupt line that indicates a clear to transmit signal
>  - a sync line shared between the SoC and all module slots which could
>    be used to synchronize modules for time sensitive IO spread across
>    modules.
>  - a SMBus alert line that is shared between the modules but is not
>    connected to the SoC so that is ignored.
> 
> A slot-number property is used to identify the physical location of a
> module slot. Without it, it would be impossible to identify which module
> to control if there are multiple of one type, to address the desired IO.

Is that for a person to identify slots or s/w? If just a person, we 
generally use 'label' as in a sticker on the connector. If s/w, we 
generally try to avoid made up indexing in DT though there are some 
exceptions.

> 
> Signed-off-by: Maud Spierings <maudspierings@gocontroll.com>
> ---
>  .../connector/gocontroll,moduline-module-slot.yaml | 88 ++++++++++++++++++++++
>  1 file changed, 88 insertions(+)
> 
> diff --git a/Documentation/devicetree/bindings/connector/gocontroll,moduline-module-slot.yaml b/Documentation/devicetree/bindings/connector/gocontroll,moduline-module-slot.yaml
> new file mode 100644
> index 0000000000000000000000000000000000000000..a16ae2762d160180d5b163e20f5294235e65053b
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/connector/gocontroll,moduline-module-slot.yaml
> @@ -0,0 +1,88 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/connector/gocontroll,moduline-module-slot.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: GOcontroll Moduline Module slot
> +
> +maintainers:
> +  - Maud Spierings <maudspierings@gocontroll.com>
> +
> +description:
> +  The GOcontroll Moduline module slot represents a connector that fullfills the
> +  Moduline slot specification, and can thus house any IO module that is also
> +  built to this spec.
> +
> +properties:
> +  compatible:
> +    const: gocontroll,moduline-module-slot
> +
> +  reg:
> +    maxItems: 1
> +
> +  interrupts:
> +    description: indicates readiness, high means busy.
> +    maxItems: 1
> +  reset-gpios:
> +    description: resets the module, active low.
> +    maxItems: 1
> +  sync-gpios:
> +    description: sync line between all module slots.
> +    maxItems: 1
> +
> +  vdd-supply:
> +    description: low power 3v3 supply generally for the microcontroller.
> +  vddp-supply:
> +    description: medium power 5v0 supply for on module low power peripherals.
> +  vddhpp-supply:
> +    description: high power 6v-8v supply for on module high power peripherals.
> +  power-supply:
> +    description: high power 6v-30v supply for high power module circuits.
> +
> +  i2c-bus:
> +    description: i2c bus shared between module slots and the SoC
> +    $ref: /schemas/types.yaml#/definitions/phandle
> +
> +  slot-number:
> +    description:
> +      The number of the module slot representing the location of on the pcb.
> +      This enables access to the modules based on slot location.
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +
> +  spi-max-frequency: true
> +
> +required:
> +  - compatible
> +  - reg
> +  - reset-gpios
> +  - interrupts
> +  - sync-gpios
> +  - i2c-bus
> +  - slot-number
> +
> +additionalProperties: false
> +
> +examples:
> +  - |
> +    #include <dt-bindings/gpio/gpio.h>
> +    #include <dt-bindings/interrupt-controller/irq.h>
> +
> +    spi {
> +        #address-cells = <1>;
> +        #size-cells = <0>;
> +
> +        connector@0 {

I find this being a SPI device a bit strange. Is there a defined SPI 
device that every slot is going to have? Or the connector has SPI 
interface and *anything* could be attached on it?

> +            reg = <0>;
> +            compatible = "gocontroll,moduline-module-slot";
> +            reset-gpios = <&gpio5 10 GPIO_ACTIVE_LOW>;
> +            sync-gpios = <&gpio4 16 GPIO_ACTIVE_HIGH>;
> +            interrupt-parent = <&gpio4>;
> +            interrupts = <5 IRQ_TYPE_EDGE_FALLING>;
> +            vdd-supply = <&reg_3v3_per>;
> +            vddp-supply = <&reg_5v0>;
> +            vddhpp-supply = <&reg_6v4>;
> +            i2c-bus = <&i2c2>;
> +            slot-number = <1>;
> +        };
> +    };
> 
> -- 
> 2.48.1
>

From: Rob Herring <robh@kernel.org>
Sent: Friday, March 14, 2025 10:06 PM
 
>On Wed, Feb 26, 2025 at 03:19:14PM +0100, Maud Spierings wrote:
>> Add the bindings that describe a GOcontroll Moduline module slot. This
>> slot provides all the interfaces to interface with a Moduline compatible
>> IO module. The actual module is not reasonable to describe as it can be
>> swapped at will, with this connector the driver will be able to probe
>> for a module on boot.
>>
>> The connector consists of 2 parts, one part for interfacing with the SoC
>> and main board, the other part has 13 IO channels for the module to
>> interact with the outside world. The functions of these IO channels are
>> determined by the type of module in the slot. The IO on the SoC side is
>> as follows:
>>
>>  - a 3v3 supply, this tends to be the logic level of the module and its
>>    microcontroller
>>  - a 5v0 supply, this can be used to power low power peripherals on the
>>    module
>>  - a 6v-8v supply, this can be used for high power peripherals on the
>>    module
>>  - a 6v-30v supply, this tends to be a dirty supply that comes from the
>>    controller supply after some circuit protection, or is the same as
>>    the 6v-8v supply.
>>  - an SPI bus which carries the communication between the SoC and the
>>    microcontroller on the module.
>>  - an I2C bus shared between the SoC and all module slots which can
>>    carry direct module-to-module communication.
>>  - a reset line
>>  - an interrupt line that indicates a clear to transmit signal
>>  - a sync line shared between the SoC and all module slots which could
>>    be used to synchronize modules for time sensitive IO spread across
>>    modules.
>>  - a SMBus alert line that is shared between the modules but is not
>>    connected to the SoC so that is ignored.
>>
>> A slot-number property is used to identify the physical location of a
>> module slot. Without it, it would be impossible to identify which module
>> to control if there are multiple of one type, to address the desired IO.
>
>Is that for a person to identify slots or s/w? If just a person, we
>generally use 'label' as in a sticker on the connector. If s/w, we
>generally try to avoid made up indexing in DT though there are some
>exceptions.

I guess both, I am not quite sure how the uapi will look like eventually.
Right now we just kind of know that spidev1.0 is slot 1 etc.

Maybe label: true could be enough but that seems to generic, it allows too
much wiggle room, if there is an eventual library that uses the kernel
uapi instead of the spidev interface it must be consistent. Or can the
label be restricted to being "moduleslot#"? I feel that numbers best
represent the way we lay out these module slots, and will provide the best
interface.

>> Signed-off-by: Maud Spierings <maudspierings@gocontroll.com>
>> ---
>>  .../connector/gocontroll,moduline-module-slot.yaml | 88 ++++++++++++++++++++++
>>  1 file changed, 88 insertions(+)
>>
>> diff --git a/Documentation/devicetree/bindings/connector/gocontroll,moduline-module-slot.yaml b/Documentation/devicetree/bindings/connector/gocontroll,moduline-module-slot.yaml
>> new file mode 100644
>> index 0000000000000000000000000000000000000000..a16ae2762d160180d5b163e20f5294235e65053b
>> --- /dev/null
>> +++ b/Documentation/devicetree/bindings/connector/gocontroll,moduline-module-slot.yaml
>> @@ -0,0 +1,88 @@
>> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
>> +%YAML 1.2
>> +---
>> +$id: http://devicetree.org/schemas/connector/gocontroll,moduline-module-slot.yaml#
>> +$schema: http://devicetree.org/meta-schemas/core.yaml#
>> +
>> +title: GOcontroll Moduline Module slot
>> +
>> +maintainers:
>> +  - Maud Spierings <maudspierings@gocontroll.com>
>> +
>> +description:
>> +  The GOcontroll Moduline module slot represents a connector that fullfills the
>> +  Moduline slot specification, and can thus house any IO module that is also
>> +  built to this spec.
>> +
>> +properties:
>> +  compatible:
>> +    const: gocontroll,moduline-module-slot
>> +
>> +  reg:
>> +    maxItems: 1
>> +
>> +  interrupts:
>> +    description: indicates readiness, high means busy.
>> +    maxItems: 1
>> +  reset-gpios:
>> +    description: resets the module, active low.
>> +    maxItems: 1
>> +  sync-gpios:
>> +    description: sync line between all module slots.
>> +    maxItems: 1
>> +
>> +  vdd-supply:
>> +    description: low power 3v3 supply generally for the microcontroller.
>> +  vddp-supply:
>> +    description: medium power 5v0 supply for on module low power peripherals.
>> +  vddhpp-supply:
>> +    description: high power 6v-8v supply for on module high power peripherals.
>> +  power-supply:
>> +    description: high power 6v-30v supply for high power module circuits.
>> +
>> +  i2c-bus:
>> +    description: i2c bus shared between module slots and the SoC
>> +    $ref: /schemas/types.yaml#/definitions/phandle
>> +
>> +  slot-number:
>> +    description:
>> +      The number of the module slot representing the location of on the pcb.
>> +      This enables access to the modules based on slot location.
>> +    $ref: /schemas/types.yaml#/definitions/uint32
>> +
>> +  spi-max-frequency: true
>> +
>> +required:
>> +  - compatible
>> +  - reg
>> +  - reset-gpios
>> +  - interrupts
>> +  - sync-gpios
>> +  - i2c-bus
>> +  - slot-number
>> +
>> +additionalProperties: false
>> +
>> +examples:
>> +  - |
>> +    #include <dt-bindings/gpio/gpio.h>
>> +    #include <dt-bindings/interrupt-controller/irq.h>
>> +
>> +    spi {
>> +        #address-cells = <1>;
>> +        #size-cells = <0>;
>> +
>> +        connector@0 {
>
>I find this being a SPI device a bit strange. Is there a defined SPI
>device that every slot is going to have? Or the connector has SPI
>interface and *anything* could be attached on it?

So a module slot is like a pcie slot, it can be occupied or not, and when
it is occupied it can be any kind of module, but it can at least only be
one module, there is no hub like functionality.

On this module is a microcontroller or perhaps even an FPGA in the future
which is the spi-device, it has the miso, mosi, sclk and cs hooked up to
it.

For now this tends to be some kind of stm32f4xx, but it is very much not
set in stone. The only thing sure is there is some kind of module
controller that is hooked up to the spi device when a module is present.

So I would say it is option 2 of what you ask. But the 'anything' is
restricted to module compatible with the standard, its not just going to 
be some IC like an ADC chip like the mcp3004 that we use on the mainboard.

>> +            reg = <0>;
>> +            compatible = "gocontroll,moduline-module-slot";
>> +            reset-gpios = <&gpio5 10 GPIO_ACTIVE_LOW>;
>> +            sync-gpios = <&gpio4 16 GPIO_ACTIVE_HIGH>;
>> +            interrupt-parent = <&gpio4>;
>> +            interrupts = <5 IRQ_TYPE_EDGE_FALLING>;
>> +            vdd-supply = <&reg_3v3_per>;
>> +            vddp-supply = <&reg_5v0>;
>> +            vddhpp-supply = <&reg_6v4>;
>> +            i2c-bus = <&i2c2>;
>> +            slot-number = <1>;
>> +        };
>> +    };
>>
>> --
>> 2.48.1
>>

I hope this cleared everything up and the bindings are still okay

Kind Regards,
Maud

On Sat, Mar 15, 2025 at 07:32:28AM +0000, Maud Spierings | GOcontroll wrote:
> >> +required:
> >> +  - compatible
> >> +  - reg
> >> +  - reset-gpios
> >> +  - interrupts
> >> +  - sync-gpios
> >> +  - i2c-bus
> >> +  - slot-number
> >> +
> >> +additionalProperties: false
> >> +
> >> +examples:
> >> +  - |
> >> +    #include <dt-bindings/gpio/gpio.h>
> >> +    #include <dt-bindings/interrupt-controller/irq.h>
> >> +
> >> +    spi {
> >> +        #address-cells = <1>;
> >> +        #size-cells = <0>;
> >> +
> >> +        connector@0 {
> >
> >I find this being a SPI device a bit strange. Is there a defined SPI
> >device that every slot is going to have? Or the connector has SPI
> >interface and *anything* could be attached on it?
> 
> So a module slot is like a pcie slot, it can be occupied or not, and when

But which buses...

Best regards,
Krzysztof

From: Krzysztof Kozlowski <krzk@kernel.org>
Sent: Monday, March 17, 2025 11:34 AM
 
>On Sat, Mar 15, 2025 at 07:32:28AM +0000, Maud Spierings | GOcontroll wrote:
>> >> +required:
>> >> +  - compatible
>> >> +  - reg
>> >> +  - reset-gpios
>> >> +  - interrupts
>> >> +  - sync-gpios
>> >> +  - i2c-bus
>> >> +  - slot-number
>> >> +
>> >> +additionalProperties: false
>> >> +
>> >> +examples:
>> >> +  - |
>> >> +    #include <dt-bindings/gpio/gpio.h>
>> >> +    #include <dt-bindings/interrupt-controller/irq.h>
>> >> +
>> >> +    spi {
>> >> +        #address-cells = <1>;
>> >> +        #size-cells = <0>;
>> >> +
>> >> +        connector@0 {
>> >
>> >I find this being a SPI device a bit strange. Is there a defined SPI
>> >device that every slot is going to have? Or the connector has SPI
>> >interface and *anything* could be attached on it?
>>
>> So a module slot is like a pcie slot, it can be occupied or not, and when
>
>But which buses...

I don't think I am fully understanding what you are asking of me. The
module will always be an spi device, that is the main communication bus.

Kind regards,
Maud

On Mon, Mar 17, 2025 at 5:42 AM Maud Spierings | GOcontroll
<maudspierings@gocontroll.com> wrote:
>
> From: Krzysztof Kozlowski <krzk@kernel.org>
> Sent: Monday, March 17, 2025 11:34 AM
>
> >On Sat, Mar 15, 2025 at 07:32:28AM +0000, Maud Spierings | GOcontroll wrote:
> >> >> +required:
> >> >> +  - compatible
> >> >> +  - reg
> >> >> +  - reset-gpios
> >> >> +  - interrupts
> >> >> +  - sync-gpios
> >> >> +  - i2c-bus
> >> >> +  - slot-number
> >> >> +
> >> >> +additionalProperties: false
> >> >> +
> >> >> +examples:
> >> >> +  - |
> >> >> +    #include <dt-bindings/gpio/gpio.h>
> >> >> +    #include <dt-bindings/interrupt-controller/irq.h>
> >> >> +
> >> >> +    spi {
> >> >> +        #address-cells = <1>;
> >> >> +        #size-cells = <0>;
> >> >> +
> >> >> +        connector@0 {
> >> >
> >> >I find this being a SPI device a bit strange. Is there a defined SPI
> >> >device that every slot is going to have? Or the connector has SPI
> >> >interface and *anything* could be attached on it?
> >>
> >> So a module slot is like a pcie slot, it can be occupied or not, and when
> >
> >But which buses...
>
> I don't think I am fully understanding what you are asking of me. The
> module will always be an spi device, that is the main communication bus.

Okay, that clears up whether it should be a SPI device or not, and I
think it should as SPI is always used. The 2nd question is what does
"gocontroll,moduline-module-slot" mean exactly. Normally, the
compatible implies how you interact with the device (or what is the
programming model). For SPI, that's what do the SPI transactions look
like to begin with. Does the slot spec define that such that every
module is the same? Then when it comes to different module types, are
those discoverable (e.g. PCI has vendor and device ID) or will you
need "compatible" to make that distinction?

Rob

From: Rob Herring <robh@kernel.org>
Sent: Tuesday, March 18, 2025 4:37 PM
 
>On Mon, Mar 17, 2025 at 5:42 AM Maud Spierings | GOcontroll
><maudspierings@gocontroll.com> wrote:
>>
>> From: Krzysztof Kozlowski <krzk@kernel.org>
>> Sent: Monday, March 17, 2025 11:34 AM
>>
>> >On Sat, Mar 15, 2025 at 07:32:28AM +0000, Maud Spierings | GOcontroll wrote:
>> >> >> +required:
>> >> >> +  - compatible
>> >> >> +  - reg
>> >> >> +  - reset-gpios
>> >> >> +  - interrupts
>> >> >> +  - sync-gpios
>> >> >> +  - i2c-bus
>> >> >> +  - slot-number
>> >> >> +
>> >> >> +additionalProperties: false
>> >> >> +
>> >> >> +examples:
>> >> >> +  - |
>> >> >> +    #include <dt-bindings/gpio/gpio.h>
>> >> >> +    #include <dt-bindings/interrupt-controller/irq.h>
>> >> >> +
>> >> >> +    spi {
>> >> >> +        #address-cells = <1>;
>> >> >> +        #size-cells = <0>;
>> >> >> +
>> >> >> +        connector@0 {
>> >> >
>> >> >I find this being a SPI device a bit strange. Is there a defined SPI
>> >> >device that every slot is going to have? Or the connector has SPI
>> >> >interface and *anything* could be attached on it?
>> >>
>> >> So a module slot is like a pcie slot, it can be occupied or not, and when
>> >
>> >But which buses...
>>
>> I don't think I am fully understanding what you are asking of me. The
>> module will always be an spi device, that is the main communication bus.
>
>Okay, that clears up whether it should be a SPI device or not, and I
>think it should as SPI is always used. The 2nd question is what does
>"gocontroll,moduline-module-slot" mean exactly. Normally, the
>compatible implies how you interact with the device (or what is the
>programming model). For SPI, that's what do the SPI transactions look
>like to begin with. Does the slot spec define that such that every
>module is the same? Then when it comes to different module types, are
>those discoverable (e.g. PCI has vendor and device ID) or will you
>need "compatible" to make that distinction?

The slot spec defines the physical interface, what pins etc and the
interaction with the bootloader. From the module bootloader it can
retrieve the module hardware identifier. This is a group of 4 bytes:
1. The standard version (currently and for the foreseable future 20)
2. Category currently these exist:
    10: Input
    20: Output
    30: Communication
    40: Multi function
3. A specific module identifier in this category
4. The module hw version

So a common module is 20-10-1-6, which is the 6 Channel Input module
version 6. It was the first input module type so it is number 1.

After this follow 3 bytes for the firmware revision which is a standard
semantic scheme of major.feature.fix.

The actual communication with the firmware is not standardized. Each
module has its own needs when it comes to that. This will be handled in a
userspace program. Our communication library is open source and can be
adapted to any shape a user wishes.

So there is no seperate compatible needed for each module, this would make
swapping modules dramatically more involved and hurt our ease of use.

I am not quite sure yet if the firmware update part will be moved into the
kernel driver as that is a stable part that can easily be there.

So the "slot" will mostly just interact with the module bootloader and set
the module up for userspace use.

kind regards,
Maud