Skip to contentSkip to conversation

dtschema: i2c: messy situation about timeouts

DISCUSSION Wolfram Sang 4 participants 8 messages Feb 26, 2024 – Feb 27, 2024 I2C subsystem host drivers

lore
Share & tools
lore
#0 lore raw

Hey guys,

we have quite a messy situation regarding I2C timeouts in the dtschema. Partly because I was too busy to pay detailed attention, partly because reviewing dtschema changes happen on Github which I totally missed. No complaining, though, here are my observations and suggestions to get it straight. Comments are more than welcome.

- "i2c-transfer-timeout-us"

Description says "Number of microseconds to wait before considering an I2C transfer has failed."

To me, this binding is very descriptive and makes sense. We should keep it. Sadly, it is the newest one and we already have others.

- "i2c-scl-has-clk-low-timeout"

AFAIU this binding tells that the controller can do clock stretching. But what for? I don't see why this is important for clients. If anything, then it would be interesting if the *client* can do clock stretching and if the controller can actually handle that. But no need to describe it in DT, we have this as an adapter quirk already 'I2C_AQ_NO_CLK_STRETCH'. Two controllers use it, but no client checks for it so far. Coming back to this binding, it is also unused in the kernel.

Suggestion: let's remove it

- "i2c-scl-clk-low-timeout-us"

The description says "Number of microseconds the clock line needs to be pulled down in order to force a waiting state." What does "forcing a waiting state" mean here? I don't understand this description.

It is used in the i2c-mpc driver. The use case is simply to put it into the 'struct i2c_adapter.timeout' member. That timeout is used to determine if a transfer failed. So, to me, "i2c-transfer-timeout-us" makes a lot more sense to use here.

Suggestion: let's remove this binding and conver i2c-mpc to "i2c-transfer-timeout-us". Yes, not nice to have two deprecated bindings, but things happened.

So, these are my thoughts about the current situation. I might have missed something, so if you have anything to add, I am all ears. Comments really welcome!

Happy hacking,

Wolfram

#1 lore raw
Quoted 29 lines · Wolfram Sang

Hey guys,

we have quite a messy situation regarding I2C timeouts in the dtschema. Partly because I was too busy to pay detailed attention, partly because reviewing dtschema changes happen on Github which I totally missed. No complaining, though, here are my observations and suggestions to get it straight. Comments are more than welcome.

- "i2c-transfer-timeout-us"

Description says "Number of microseconds to wait before considering an I2C transfer has failed."

To me, this binding is very descriptive and makes sense. We should keep it. Sadly, it is the newest one and we already have others.

- "i2c-scl-has-clk-low-timeout"

AFAIU this binding tells that the controller can do clock stretching. But what for? I don't see why this is important for clients. If anything, then it would be interesting if the *client* can do clock stretching and if the controller can actually handle that. But no need to describe it in DT, we have this as an adapter quirk already 'I2C_AQ_NO_CLK_STRETCH'. Two controllers use it, but no client checks for it so far. Coming back to this binding, it is also unused in the kernel.

Quoted 1 line

Suggestion: let's remove it

Seems like it can be implied by compatible... I'll defer to Andi.

Quoted 7 lines

- "i2c-scl-clk-low-timeout-us"

The description says "Number of microseconds the clock line needs to be pulled down in order to force a waiting state." What does "forcing a waiting state" mean here? I don't understand this description.

Does the commit msg or PR help?:
https://github.com/devicetree-org/dt-schema/pull/103

Quoted 9 lines

It is used in the i2c-mpc driver. The use case is simply to put it into the 'struct i2c_adapter.timeout' member. That timeout is used to determine if a transfer failed. So, to me, "i2c-transfer-timeout-us" makes a lot more sense to use here.

Suggestion: let's remove this binding and conver i2c-mpc to "i2c-transfer-timeout-us". Yes, not nice to have two deprecated bindings, but things happened.

Maybe the core code should read it instead?

I think we should mark as deprecated rather than remove unless we can just remove the properties from the kernel. The reason being that every property the kernel accesses should be documented. I might start actually checking that. That's already done for compatible strings, but those are mostly defined by a common pattern we can extract while properties are less so.

Rob

#2 lore raw

Hi Rob,

Quoted 8 lines
Quoted 5 lines

- "i2c-scl-clk-low-timeout-us"

The description says "Number of microseconds the clock line needs to be pulled down in order to force a waiting state." What does "forcing a waiting state" mean here? I don't understand this description.

Does the commit msg or PR help?:
https://github.com/devicetree-org/dt-schema/pull/103

I checked it beforehand. Sadly, it didn't help me.

Quoted 10 lines
Quoted 8 lines

It is used in the i2c-mpc driver. The use case is simply to put it into the 'struct i2c_adapter.timeout' member. That timeout is used to determine if a transfer failed. So, to me, "i2c-transfer-timeout-us" makes a lot more sense to use here.

Suggestion: let's remove this binding and conver i2c-mpc to "i2c-transfer-timeout-us". Yes, not nice to have two deprecated bindings, but things happened.

Maybe the core code should read it instead?

That's an interesting idea. I'll try to implement this tomorrow.

Quoted 2 lines

I think we should mark as deprecated rather than remove unless we can just remove the properties from the kernel. The reason being that

You are right. I should have said "depreacte" instead of remove here.

All the best,

Wolfram

#3 lore raw
In reply to Wolfram Sang
Quoted 17 lines · Wolfram Sang

Hey guys,

we have quite a messy situation regarding I2C timeouts in the dtschema. Partly because I was too busy to pay detailed attention, partly because reviewing dtschema changes happen on Github which I totally missed. No complaining, though, here are my observations and suggestions to get it straight. Comments are more than welcome.

- "i2c-transfer-timeout-us"

Description says "Number of microseconds to wait before considering an I2C transfer has failed."

To me, this binding is very descriptive and makes sense. We should keep it. Sadly, it is the newest one and we already have others.

Quoted 8 lines

- "i2c-scl-has-clk-low-timeout"

AFAIU this binding tells that the controller can do clock stretching. But what for? I don't see why this is important for clients. If anything, then it would be interesting if the *client* can do clock stretching and if the controller can actually handle that. But no need to describe it in DT, we have this as an adapter quirk already 'I2C_AQ_NO_CLK_STRETCH'.

Hmm I know of a few adapters that should probably set I2C_AQ_NO_CLK_STRETCH based on some Errata. Probably just a documentation exercise. It would be nice to reject clients that need to do clock stretching but often it happens as a side effect rather than being intentional (I've seen this with i2c clients implemented in microcontrollers).

Quoted 13 lines

Two controllers use it, but no client checks
for it so far. Coming back to this binding, it is also unused in the kernel.

Suggestion: let's remove it

- "i2c-scl-clk-low-timeout-us"

The description says "Number of microseconds the clock line needs to be pulled down in order to force a waiting state." What does "forcing a waiting state" mean here? I don't understand this description.

Quoted 8 lines

It is used in the i2c-mpc driver. The use case is simply to put it into the 'struct i2c_adapter.timeout' member. That timeout is used to determine if a transfer failed. So, to me, "i2c-transfer-timeout-us" makes a lot more sense to use here.

Suggestion: let's remove this binding and conver i2c-mpc to "i2c-transfer-timeout-us". Yes, not nice to have two deprecated bindings, but things happened.

Sounds like a good idea. We'd obviously need to keep support for the existing property but it wouldn't be hard to add "i2c-transfer-timeout-us". I'll try to whip up a patch for that sometime this week, just need to dust off my Freescale boards.

Quoted 8 lines

So, these are my thoughts about the current situation. I might have missed something, so if you have anything to add, I am all ears. Comments really welcome!

Happy hacking,

Wolfram

#4 lore raw

Hi Chris,

Quoted 11 lines
Quoted 8 lines

- "i2c-scl-has-clk-low-timeout"

AFAIU this binding tells that the controller can do clock stretching. But what for? I don't see why this is important for clients. If anything, then it would be interesting if the *client* can do clock stretching and if the controller can actually handle that. But no need to describe it in DT, we have this as an adapter quirk already 'I2C_AQ_NO_CLK_STRETCH'.

Hmm I know of a few adapters that should probably set I2C_AQ_NO_CLK_STRETCH based on some Errata. Probably just a

That would be helpful if you could add that. I always guessed there should be more controllers needing the flag but never encountered them personally.

Quoted 4 lines

documentation exercise. It would be nice to reject clients that need to do clock stretching but often it happens as a side effect rather than being intentional (I've seen this with i2c clients implemented in microcontrollers).

I guess the way forward with that is we add a flag like I2C_CLIENT_CLK_STRETCH and let the core figure out if controller and client are compatible. Dunno what to do if not, though. Reject? Throw a warning that there might be problems? Probably reject by default unless overridden by something-meaning-i-know-the-risks.

Quoted 8 lines
Quoted 3 lines

Suggestion: let's remove this binding and conver i2c-mpc to "i2c-transfer-timeout-us". Yes, not nice to have two deprecated bindings, but things happened.

Sounds like a good idea. We'd obviously need to keep support for the existing property but it wouldn't be hard to add "i2c-transfer-timeout-us". I'll try to whip up a patch for that sometime this week, just need to dust off my Freescale boards.

Please wait a little with the implementation. I want to try Rob's idea to let the core set the timeout flag initially. Dusting off the boards for testing would be awesome, though :)

Happy hacking,

Wolfram

maintainer
#5 lore raw
In reply to Wolfram Sang

Hi Wolfram,

Quoted 13 lines · Wolfram Sang

Hey guys,

we have quite a messy situation regarding I2C timeouts in the dtschema. Partly because I was too busy to pay detailed attention, partly because reviewing dtschema changes happen on Github which I totally missed. No complaining, though, here are my observations and suggestions to get it straight. Comments are more than welcome.

- "i2c-transfer-timeout-us"

Description says "Number of microseconds to wait before considering an I2C transfer has failed."

Quoted 8 lines

To me, this binding is very descriptive and makes sense. We should keep it. Sadly, it is the newest one and we already have others.

- "i2c-scl-has-clk-low-timeout"

AFAIU this binding tells that the controller can do clock stretching. But what for?

One of the controllers that was sent a while back required some hardware description because, in some versions, clock stretching was supported in the hardware.

Depending on this, the driver could either use it or force the clock GPIO value down.

That's why I made this change.

The naming is a bit fancy, but it depends on the spec used as a reference; smbus, i2c or specific drivers often call it in a different way.

The naming is a bit fancy, but it depends on the specification used as a reference; SMBus, I2C, or specific drivers often refer to it differently.

Quoted 8 lines

I don't see why this is important for clients. If
anything, then it would be interesting if the *client* can do clock stretching and if the controller can actually handle that. But no need to describe it in DT, we have this as an adapter quirk already 'I2C_AQ_NO_CLK_STRETCH'. Two controllers use it, but no client checks for it so far. Coming back to this binding, it is also unused in the kernel.

Quoted 8 lines

Suggestion: let's remove it

- "i2c-scl-clk-low-timeout-us"

The description says "Number of microseconds the clock line needs to be pulled down in order to force a waiting state." What does "forcing a waiting state" mean here? I don't understand this description.

It comes from the specification. The clock stretching is given as an interval that can be tweaked depending on the hardware.

So far I haven't seen anyone using it, though.

Andi

Quoted 18 lines

It is used in the i2c-mpc driver. The use case is simply to put it into the 'struct i2c_adapter.timeout' member. That timeout is used to determine if a transfer failed. So, to me, "i2c-transfer-timeout-us" makes a lot more sense to use here.

Suggestion: let's remove this binding and conver i2c-mpc to "i2c-transfer-timeout-us". Yes, not nice to have two deprecated bindings, but things happened.

So, these are my thoughts about the current situation. I might have missed something, so if you have anything to add, I am all ears. Comments really welcome!

Happy hacking,

Wolfram

#6 lore raw

Hi Andi,

Quoted 8 lines
Quoted 4 lines

- "i2c-scl-has-clk-low-timeout"

AFAIU this binding tells that the controller can do clock stretching. But what for?

One of the controllers that was sent a while back required some hardware description because, in some versions, clock stretching was supported in the hardware.

I see. Still, I think this can (and should be handled) with I2C_AQ_NO_CLK_STRETCH.

Quoted 3 lines

The naming is a bit fancy, but it depends on the specification used as a reference; SMBus, I2C, or specific drivers often refer to it differently.

Yes. I'd give I2C specs most importance, controller documentation least. And probably a salt of personal preference :)

Quoted 8 lines
Quoted 5 lines

- "i2c-scl-clk-low-timeout-us"

The description says "Number of microseconds the clock line needs to be pulled down in order to force a waiting state." What does "forcing a waiting state" mean here? I don't understand this description.

It comes from the specification. The clock stretching is given as an interval that can be tweaked depending on the hardware.

You mean the maximum clock stretching is tweakable? That, in deed, could be a binding in the future, in theory. Yet, it would need support in the client drivers. Like a touchscreen driver which assumes a reset after a certain time of inactivity.

Quoted 1 line

So far I haven't seen anyone using it, though.

The MPC driver used it, just for a different purpose. It was used for a timeout of the total transfer. That's a different thing. So, I suggested the conversion.

Happy hacking,

Wolfram

#7 lore raw
Quoted 7 lines
Quoted 7 lines
Quoted 6 lines

- "i2c-scl-clk-low-timeout-us"

The description says "Number of microseconds the clock line needs to be pulled down in order to force a waiting state." What does "forcing a waiting state" mean here? I don't understand this description.

Quoted 7 lines
Quoted 2 lines

It comes from the specification. The clock stretching is given as an interval that can be tweaked depending on the hardware.

You mean the maximum clock stretching is tweakable? That, in deed, could be a binding in the future, in theory. Yet, it would need support in the client drivers. Like a touchscreen driver which assumes a reset after a certain time of inactivity.

To sum it up: a binding defining the maximum time for clock stretching makes sense in theory. I am currently not aware of a controller where this could be used (but I surely don't know them all). Most of them keep SCL low as long as they are busy internally. Not tweakable. So, we defer this until there is a usecase.

If we ever add it, the above name of the binding cannot be used anymore because i2c-mpc used it with a different purpose. Not so bad IMO because "scl-clk" is a pleonasm anyway. I'd suggest "i2c-scl-max-stretch-us" but am open for suggestions then.

This one can just be deprecated, I'd say.

Happy hacking!