Re: [dtschema PATCH] schemas: i2c: Add missing properties and descriptions

[Alain Volmat <alain.volmat@foss.st.com>]

Hi,

Acked-by: Alain Volmat <alain.volmat@foss.st.com>

Thanks.
Alain

On Wed, Apr 27, 2022 at 12:59:56PM -0500, Rob Herring wrote:
> Add remaining properties and descriptions from i2c.txt binding in Linux
> kernel tree. The Cc list are the authors of i2c.txt.
> 
> Cc: Wolfram Sang <wsa+renesas@sang-engineering.com>
> Cc: Eugen Hristev <eugen.hristev@microchip.com>
> Cc: Dmitry Torokhov <dmitry.torokhov@gmail.com>
> Cc: Codrin Ciubotariu <codrin.ciubotariu@microchip.com>
> Cc: Jon Hunter <jonathanh@nvidia.com>
> Cc: Alain Volmat <alain.volmat@foss.st.com>
> Cc: Matt Johnston <matt@codeconstruct.com.au>
> Signed-off-by: Rob Herring <robh@kernel.org>
> ---
> Cc list, 
> 
> I need your or your company's permission to relicense i2c.txt contents 
> (used in 'description') to BSD-2-Clause. Please ack and provide a 
> copyright if desired.
> 
>  dtschema/schemas/i2c/i2c-controller.yaml | 143 +++++++++++++++++++++++
>  1 file changed, 143 insertions(+)
> 
> diff --git a/dtschema/schemas/i2c/i2c-controller.yaml b/dtschema/schemas/i2c/i2c-controller.yaml
> index 91eac62a6bc8..c2e803ebcc3f 100644
> --- a/dtschema/schemas/i2c/i2c-controller.yaml
> +++ b/dtschema/schemas/i2c/i2c-controller.yaml
> @@ -1,5 +1,6 @@
>  # SPDX-License-Identifier: BSD-2-Clause
>  # Copyright 2018 Linaro Ltd.
> +# Copyright 2022 Arm Ltd.
>  %YAML 1.2
>  ---
>  $id: http://devicetree.org/schemas/i2c/i2c-controller.yaml#
> @@ -28,6 +29,91 @@ properties:
>      minimum: 1000
>      maximum: 3000000
>  
> +  i2c-scl-falling-time-ns:
> +    description:
> +      Number of nanoseconds the SCL signal takes to fall; t(f) in the I2C
> +      specification.
> +
> +  i2c-scl-internal-delay-ns:
> +    description:
> +      Number of nanoseconds the IP core additionally needs to setup SCL.
> +
> +  i2c-scl-rising-time-ns:
> +    description:
> +      Number of nanoseconds the SCL signal takes to rise; t(r) in the I2C
> +      specification.
> +
> +  i2c-sda-falling-time-ns:
> +    description:
> +      Number of nanoseconds the SDA signal takes to fall; t(f) in the I2C
> +      specification.
> +
> +  i2c-analog-filter:
> +    type: boolean
> +    description:
> +      Enable analog filter for i2c lines.
> +
> +  i2c-digital-filter:
> +    type: boolean
> +    description:
> +      Enable digital filter for i2c lines.
> +
> +  i2c-digital-filter-width-ns:
> +    description:
> +      Width of spikes which can be filtered by digital filter
> +      (i2c-digital-filter). This width is specified in nanoseconds.
> +
> +  i2c-analog-filter-cutoff-frequency:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    description:
> +      Frequency that the analog filter (i2c-analog-filter) uses to distinguish
> +      which signal to filter. Signal with higher frequency than specified will
> +      be filtered out. Only lower frequency will pass (this is applicable to a
> +      low-pass analog filter). Typical value should be above the normal i2c bus
> +      clock frequency (clock-frequency). Specified in Hz.
> +
> +  mctp-controller:
> +    type: boolean
> +    description:
> +      Indicates that the system is accessible via this bus as an endpoint for
> +      MCTP over I2C transport.
> +
> +  multi-master:
> +    type: boolean
> +    description:
> +      States that there is another master active on this bus. The OS can use
> +      this information to adapt power management to keep the arbitration awake
> +      all the time, for example. Can not be combined with 'single-master'.
> +
> +  scl-gpios:
> +    maxItems: 1
> +    description:
> +      Specifies the GPIO related to SCL pin. Used for GPIO bus recovery.
> +
> +  sda-gpios:
> +    maxItems: 1
> +    description:
> +      Specifies the GPIO related to SDA pin. Optional for GPIO bus recovery.
> +
> +  single-master:
> +    type: boolean
> +    description:
> +      States that there is no other master active on this bus. The OS can use
> +      this information to detect a stalled bus more reliably, for example. Can
> +      not be combined with 'multi-master'.
> +
> +  smbus:
> +    type: boolean
> +    description:
> +      States that additional SMBus restrictions and features apply to this bus.
> +      An example of feature is SMBusHostNotify. Examples of restrictions are
> +      more reserved addresses and timeout definitions.
> +
> +  smbus-alert:
> +    type: boolean
> +    description:
> +      states that the optional SMBus-Alert feature apply to this bus.
> +
>    no-detect:
>      type: boolean
>      description:
> @@ -38,4 +124,61 @@ patternProperties:
>    '@[0-9a-f]+$':
>      type: object
>  
> +    properties:
> +      reg:
> +        items:
> +          items:
> +            - oneOf:
> +                - maximum: 0x7f
> +                - minimum: 0x40000000
> +                  maximum: 0x4000007f
> +                - minimum: 0x80000000
> +                  maximum: 0x800003ff
> +                - minimum: 0xc0000000
> +                  maximum: 0xc00003ff
> +        description: |
> +          One or many I2C slave addresses. These are usually a 7 bit addresses.
> +          However, flags can be attached to an address. I2C_TEN_BIT_ADDRESS is
> +          used to mark a 10 bit address. It is needed to avoid the ambiguity
> +          between e.g. a 7 bit address of 0x50 and a 10 bit address of 0x050
> +          which, in theory, can be on the same bus.
> +          Another flag is I2C_OWN_SLAVE_ADDRESS to mark addresses on which we
> +          listen to be devices ourselves.
> +
> +      host-notify:
> +        description:
> +          Device uses SMBus host notify protocol instead of interrupt line.
> +          Requires being connected to an adapter that supports this feature.
> +
> +      interrupts:
> +        description:
> +          I2C core will treat "irq" interrupt (or the very first interrupt if
> +          not using interrupt names) as primary interrupt for the slave.
> +
> +      interrupt-names:
> +        anyOf:
> +          - {} # Any name is allowed.
> +          - items:
> +              enum:
> +                - irq
> +                - wakeup
> +                - smbus_alert
> +            description:
> +              Names which are recognized by I2C core,	other names are	left to
> +              individual bindings.
> +
> +      wakeup-source:
> +        description:
> +          Device can be used as a wakeup source. The device should also have
> +          "wakeup" interrupt for the device. If "wakeup" interrupt name is not
> +          present in the binding, then primary interrupt will be used as wakeup
> +          interrupt.
> +
> +    required:
> +      - reg
> +
> +dependentRequired:
> +  i2c-analog-filter-cutoff-frequency: [ i2c-analog-filter ]
> +  i2c-digital-filter-width-ns: [ i2c-digital-filter ]
> +
>  additionalProperties: true
> -- 
> 2.34.1
>