Re: [PATCH v5 1/3] i2c: mux: Add i2c-arb-gpio-challenge 'mux' driver

[Stephen Warren <swarren@wwwdotorg.org>]

On 04/16/2013 03:36 AM, Wolfram Sang wrote:
> Doug,
> 
> On Tue, Apr 09, 2013 at 02:34:28PM -0700, Doug Anderson wrote:
>> The i2c-arb-gpio-challenge driver implements an I2C arbitration scheme
>> where masters need to claim the bus with a GPIO before they can start
>> a transcation.  This should generally only be used when standard I2C
>> multimaster isn't appropriate for some reason (errata/bugs).
>>
>> This driver is based on code that Simon Glass added to the i2c-s3c2410
>> driver in the Chrome OS kernel 3.4 tree.  The current incarnation as a
>> mux driver is as suggested by Grant Likely.  See
>> <https://patchwork.kernel.org/patch/1877311/> for some history.

>> diff --git a/Documentation/devicetree/bindings/i2c/i2c-arb-gpio-challenge.txt b/Documentation/devicetree/bindings/i2c/i2c-arb-gpio-challenge.txt

>> +GPIO-based I2C Arbitration
>> +==========================
>> +This uses GPIO lines to arbitrate who is the master of an I2C bus in a
>> +multimaster situation.
> 
> "uses GPIO lines and a challange & response mechanism" or something like
> that. There might be other GPIO based arbitrations in the future (though
> I hope there won't).

The existing text appears clearer to me; this document should spell out
the exact details of the protocol in later paragraphs, so there's no
need to try and spell it out here.

>> +- their-claim-gpios: The GPIOs that the other sides use the claim the bus.
>> +  Note that some implementations may only support a single other master.
> 
> Stronger? "Currently, only one other master is supported"?

The DT binding documentation, which should be OS-/driver-agnostic,
should describe the binding, not the implementation. The limitation that
Linux imposes is OS-specific and hence should not be mentioned here as
an absolute, or perhaps even at all.