Documentation/devicetree/bindings/i2c/i2c-arb-gpio-challenge.yaml

Source file repositories/reference/linux-study-clean/Documentation/devicetree/bindings/i2c/i2c-arb-gpio-challenge.yaml

File Facts

System
Linux kernel
Corpus path
Documentation/devicetree/bindings/i2c/i2c-arb-gpio-challenge.yaml
Extension
.yaml
Size
4218 bytes
Lines
136
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: configuration, schema, or hardware description
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
%YAML 1.2
---
$id: http://devicetree.org/schemas/i2c/i2c-arb-gpio-challenge.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: GPIO-based I2C Arbitration Using a Challenge & Response Mechanism

maintainers:
  - Doug Anderson <dianders@chromium.org>
  - Peter Rosin <peda@axentia.se>

description: |
  This uses GPIO lines and a challenge & response mechanism to arbitrate who is
  the master of an I2C bus in a multimaster situation.

  In many cases using GPIOs to arbitrate is not needed and a design can use the
  standard I2C multi-master rules.  Using GPIOs is generally useful in the case
  where there is a device on the bus that has errata and/or bugs that makes
  standard multimaster mode not feasible.

  Note that this scheme works well enough but has some downsides:
   * It is nonstandard (not using standard I2C multimaster)
   * Having two masters on a bus in general makes it relatively hard to debug
     problems (hard to tell if i2c issues were caused by one master, another,
     or some device on the bus).

  Algorithm:
  All masters on the bus have a 'bus claim' line which is an output that the
  others can see. These are all active low with pull-ups enabled.  We'll
  describe these lines as:
   * OUR_CLAIM: output from us signaling to other hosts that we want the bus
   * THEIR_CLAIMS: output from others signaling that they want the bus

  The basic algorithm is to assert your line when you want the bus, then make
  sure that the other side doesn't want it also.  A detailed explanation is
  best done with an example.

  Let's say we want to claim the bus.  We:
  1. Assert OUR_CLAIM.
  2. Waits a little bit for the other sides to notice (slew time, say 10
     microseconds).
  3. Check THEIR_CLAIMS.  If none are asserted then the we have the bus and we
     are done.
  4. Otherwise, wait for a few milliseconds and see if THEIR_CLAIMS are released.
  5. If not, back off, release the claim and wait for a few more milliseconds.
  6. Go back to 1 (until retry time has expired).

properties:
  compatible:
    const: i2c-arb-gpio-challenge

  i2c-parent:
    $ref: /schemas/types.yaml#/definitions/phandle
    description:
      The I2C bus that this multiplexer's master-side port is connected to.

  our-claim-gpios:
    maxItems: 1
    description:
      The GPIO that we use to claim the bus.

  slew-delay-us:
    default: 10
    description:
      Time to wait for a GPIO to go high.

  their-claim-gpios:
    minItems: 1
    maxItems: 8

Annotation

Implementation Notes