i2c/adapter: Add bus recovery infrastructure

Add i2c bus recovery infrastructure to i2c adapters as specified in the i2c protocol Rev. 03 section 3.1.16 titled "Bus clear".

http://www.nxp.com/documents/user_manual/UM10204.pdf

Sometimes during operation i2c bus hangs and we need to give dummy clocks to slave device to start the transfer again. Now we may have capability in the bus controller to generate these clocks or platform may have gpio pins which can be toggled to generate dummy clocks. This patch supports both.

This patch also adds in generic bus recovery routines gpio or scl line based which can be used by bus controller. In addition controller driver may provide its own version of the bus recovery routine.

This doesn't support multi-master recovery for now.

Add i2c bus recovery infrastructure to i2c adapters as specified in the i2c protocol Rev. 03 section 3.1.16 titled "Bus clear".

http://www.nxp.com/documents/user_manual/UM10204.pdf

Sometimes during operation i2c bus hangs and we need to give dummy clocks to slave device to start the transfer again. Now we may have capability in the bus controller to generate these clocks or platform may have gpio pins which can be toggled to generate dummy clocks. This patch supports both.

This patch also adds in generic bus recovery routines gpio or scl line based which can be used by bus controller. In addition controller driver may provide its own version of the bus recovery routine.

This doesn't support multi-master recovery for now.

Signed-off-by Viresh Kumar <[email protected]>

---
V5 Resend:
- Fixed my email-id, removed st.com and added linaro.org V4->V5:
- section name corrected to 3.1.16
- merged gpio and non-gpio recovery routines to remove code redundancy
- Changed types of gpio and gpio-flags to unsigned and unsigned long
- Checking return value of get_gpio() now
- using DIV_ROUND_UP for calculating delay, to get more correct value

 drivers/i2c/i2c-core.c | 153 +++++++++++++++++++++++++++++++++++++++++++++++++
 include/linux/i2c.h    |  52 +++++++++++++++++
 2 files changed, 205 insertions(+)

drivers/i2c/i2c-core.c +2 -0

index a7edf98..bdc249a 100644
@@ -27,7 +27,9 @@
 
 #include <linux/module.h>
 #include <linux/kernel.h>
+#include <linux/delay.h>
 #include <linux/errno.h>
+#include <linux/gpio.h>
 #include <linux/slab.h>
 #include <linux/i2c.h>
 #include <linux/init.h>

@@ -104,6 +106,116 @@ static int i2c_device_uevent(struct device *dev, struct kobj_uevent_env *env)
 #define i2c_device_uevent	NULL
 #endif	/* CONFIG_HOTPLUG */

drivers/i2c/i2c-core.c +84 -0

+}
+
+static inline int get_sda_value(struct i2c_adapter *adap)
+{
+	struct i2c_bus_recovery_info *bri = adap->bus_recovery_info;
+
+	if (bri->is_gpio_recovery)
+		return gpio_get_value(bri->sda_gpio);
+	else
+		return bri->get_sda(adap);
+}
+
+static int i2c_get_gpios_for_recovery(struct i2c_adapter *adap)
+{
+	struct i2c_bus_recovery_info *bri = adap->bus_recovery_info;
+	struct device *dev = &adap->dev;
+	int ret = 0;
+
+	if (bri->get_gpio) {
+		ret = bri->get_gpio(bri->scl_gpio);
+		if (ret) {
+			dev_warn(dev, "scl get_gpio: %d\n", bri->scl_gpio);
+			return ret;
+		}
+	}
+
+	ret = gpio_request_one(bri->scl_gpio, bri->scl_gpio_flags, "i2c-scl");
+	if (ret) {
+		dev_warn(dev, "gpio request fail: %d\n", bri->scl_gpio);
+		goto scl_put_gpio;
+	}
+
+	if (!bri->skip_sda_polling) {
+		if (bri->get_gpio)
+			ret = bri->get_gpio(bri->sda_gpio);
+
+		if (unlikely(ret ||
+			gpio_request_one(bri->sda_gpio, bri->sda_gpio_flags,
+				"i2c-sda"))) {
+			/* work without sda polling */
+			dev_warn(dev, "can't get sda: %d. Skip sda polling\n",
+					bri->sda_gpio);
+			bri->skip_sda_polling = true;
+			if (!ret && bri->put_gpio)
+				bri->put_gpio(bri->sda_gpio);
+
+			ret = 0;
+		}
+	}
+
+scl_put_gpio:
+	if (bri->put_gpio)
+		bri->put_gpio(bri->scl_gpio);
+
+	return ret;
+}
+
+static void i2c_put_gpios_for_recovery(struct i2c_adapter *adap)
+{
+	struct i2c_bus_recovery_info *bri = adap->bus_recovery_info;
+
+	gpio_free(bri->scl_gpio);
+
+	if (!bri->skip_sda_polling) {
+		gpio_free(bri->sda_gpio);
+
+		if (bri->put_gpio)
+			bri->put_gpio(bri->sda_gpio);
+	}
+}
+
+static int i2c_recover_bus(struct i2c_adapter *adap)
+{
+	struct i2c_bus_recovery_info *bri = adap->bus_recovery_info;
+	unsigned long delay = 1000000;
+	int i, ret, val = 1;
+
+	if (bri->is_gpio_recovery) {
+		ret = i2c_get_gpios_for_recovery(adap);
+		if (ret)
+			return ret;
+	}
+
+	delay = DIV_ROUND_UP(delay, bri->clock_rate_khz * 2);

drivers/i2c/i2c-core.c +48 -0

+
+	if (bri->is_gpio_recovery)
+		i2c_put_gpios_for_recovery(adap);
+
+	return 0;
+}
+
 static int i2c_device_probe(struct device *dev)
 {
 	struct i2c_client	*client = i2c_verify_client(dev);

@@ -896,6 +1008,47 @@ static int i2c_register_adapter(struct i2c_adapter *adap)
 			 "Failed to create compatibility class link\n");
 #endif
 
+	/* bus recovery specific initialization */
+	if (adap->bus_recovery_info) {
+		struct i2c_bus_recovery_info *bri = adap->bus_recovery_info;
+
+		if (bri->recover_bus) {
+			dev_info(&adap->dev,
+				"registered for non-generic bus recovery\n");
+		} else {
+			/* Use generic recovery routines */
+			if (!bri->clock_rate_khz) {
+				dev_warn(&adap->dev,
+					"doesn't have valid recovery clock rate\n");
+				goto exit_recovery;
+			}
+
+			/* Most controller need 9 clocks at max */
+			if (!bri->clock_cnt)
+				bri->clock_cnt = 9;
+
+			bri->recover_bus = i2c_recover_bus;
+
+			if (bri->is_gpio_recovery) {
+				dev_info(&adap->dev,
+					"registered for gpio bus recovery\n");
+			} else if (bri->set_scl) {
+				if (!bri->skip_sda_polling && !bri->get_sda) {
+					dev_warn(&adap->dev,
+						"!get_sda. skip sda polling\n");
+					bri->skip_sda_polling = true;
+				}
+
+				dev_info(&adap->dev,
+					"registered for scl bus recovery\n");
+			} else {
+				dev_warn(&adap->dev,
+					"doesn't have valid recovery type\n");
+			}
+		}
+	}
+
+exit_recovery:
 	/* create pre-declared device nodes */
 	if (adap->nr < __i2c_first_dynamic_bus_num)
 		i2c_scan_static_board_info(adap);

include/linux/i2c.h +18 -0

index 5970266..c43e5c4 100644
@@ -370,6 +370,55 @@ struct i2c_algorithm {
 	u32 (*functionality) (struct i2c_adapter *);
 };
 
+/**
+ * struct i2c_bus_recovery_info - I2c bus recovery information
+ * @recover_bus: Recover routine. Either pass driver's recover_bus() routine, or
+ *	pass it NULL to use generic ones, i.e. gpio or scl based.
+ * @skip_sda_polling: if true, bus recovery will not poll sda line to check if
+ *	it became high or not. Only required if recover_bus == NULL.
+ * @is_gpio_recovery: true, select gpio type else scl type. Only required if
+ *	recover_bus == NULL.
+ * @clock_rate_khz: clock rate of dummy clock in khz. Required for both gpio and
+ *	scl type recovery.
+ * @clock_cnt: count of max clocks to be generated. Required for both gpio and
+ *	scl type recovery.
+ * @set_scl: controller specific scl configuration routine. Only required if
+ *	is_gpio_recovery == false
+ * @get_sda: controller specific sda read routine. Only required if
+ *	is_gpio_recovery == false and skip_sda_polling == false.
+ * @get_gpio: called before recover_bus() to get padmux configured for scl line.
+ *	as gpio. Only required if is_gpio_recovery == true. Return 0 on success.

Quoted 1 line · Viresh Kumar

drivers/i2c/i2c-core.c +0 -0

drivers/i2c/i2c-core.c static int i2c_device_uevent(struct device *dev, struct kobj_uevent_env *env) · line 117

Quoted 8 lines

drivers/i2c/i2c-core.c +8 -0

+static inline void set_scl_value(struct i2c_adapter *adap, int val)
+{
+     struct i2c_bus_recovery_info *bri = adap->bus_recovery_info;
+
+     if (bri->is_gpio_recovery)
+             gpio_set_value(bri->scl_gpio, val);
+     else
+             bri->set_scl(adap, val);

I would have done this in a different way (with function pointers instead of an if for each bang). Well, I don't care much.

Quoted 13 lines

drivers/i2c/i2c-core.c +13 -0

+static int i2c_recover_bus(struct i2c_adapter *adap)
+{
+     struct i2c_bus_recovery_info *bri = adap->bus_recovery_info;
+     unsigned long delay = 1000000;
+     int i, ret, val = 1;
+
+     if (bri->is_gpio_recovery) {
+             ret = i2c_get_gpios_for_recovery(adap);
+             if (ret)
+                     return ret;
+     }
+
+     delay = DIV_ROUND_UP(delay, bri->clock_rate_khz * 2);

drivers/i2c/i2c-core.c static int i2c_device_uevent(struct device *dev, struct kobj_uevent_env *env) · line 211

Quoted 10 lines

drivers/i2c/i2c-core.c +10 -0

+
+     for (i = 0; i < bri->clock_cnt * 2; i++, val = !val) {
+             set_scl_value(adap, val);
+             ndelay(delay);
+
+             /* break if sda got high, check only when scl line is high */
+             if (!bri->skip_sda_polling && val)
+                     if (unlikely(get_sda_value(adap)))
+                             break;
+     }

With clock_cnt usually being 9 (and skipping sda polling) assume a device pulls down SDA because it was just addressed but the last clock pulse to release SDA didn't occur:

        SDAout ¯\_/¯¯¯\___/¯¯¯\___________________/¯¯¯¯¯¯
        SCL    ¯¯\_/¯\_/¯\_/¯\_/¯\_/¯\_/¯\_/¯\_/¯\_/¯¯¯¯¯
                S   1   2   3   4   5   6   7   8   9

This adresses an eeprom with address 0x50. When SCL is released for the 9th clock the eeprom pulls down SDA to ack being addressed. After that the eeprom expects the master to write a byte.

Now you do write 0xff:

         i      0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
        SDAin  ___/¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯\______
        SCL    ¯¯\_/¯\_/¯\_/¯\_/¯\_/¯¯\__/¯¯\__/¯¯\__/¯¯\______/
                9   1   2   3   4    5     6     7     8

(assuming the SCL line goes up some time later to its idle state). That is you leave the bus in exactly the same state as before: The 9th clock isn't complete and the eeprom asserts SDA low to ack the byte just written. So the bus is still stalled. The problem is BTW the exact same one I introduced first in my bus clear routine (for barebox though). Even though you count to 2*9 you only do 8 real clock pulses because you have a half cycle at both the start and the end.

Quoted 4 lines

+ * @scl_gpio_flags: flag for gpio_request_one of scl_gpio. 0 implies
+ * GPIOF_OUT_INIT_LOW.
+ * @sda_gpio_flags: flag for gpio_request_one of sda_gpio. 0 implies
+ * GPIOF_OUT_INIT_LOW.

Didn't you want to change this to GPIOF_OUT_INIT_HIGH | GPIOF_OPEN_DRAIN? Hmm, I just wonder how to distinguish GPIOF_OUT_INIT_LOW from unset. Hmm, maybe assume unset because _LOW is wrong?

Quoted 28 lines

drivers/i2c/i2c-core.c static int i2c_device_uevent(struct device *dev, struct kobj_uevent_env *env) · line 211

Quoted 9 lines

drivers/i2c/i2c-core.c +9 -0

+     for (i = 0; i < bri->clock_cnt * 2; i++, val = !val) {
+             set_scl_value(adap, val);
+             ndelay(delay);
+
+             /* break if sda got high, check only when scl line is high */
+             if (!bri->skip_sda_polling && val)
+                     if (unlikely(get_sda_value(adap)))
+                             break;
+     }

With clock_cnt usually being 9 (and skipping sda polling) assume a device pulls down SDA because it was just addressed but the last clock pulse to release SDA didn't occur:

        SDAout ¯\_/¯¯¯\___/¯¯¯\___________________/¯¯¯¯¯¯
        SCL    ¯¯\_/¯\_/¯\_/¯\_/¯\_/¯\_/¯\_/¯\_/¯\_/¯¯¯¯¯
                S   1   2   3   4   5   6   7   8   9

This adresses an eeprom with address 0x50. When SCL is released for the 9th clock the eeprom pulls down SDA to ack being addressed. After that the eeprom expects the master to write a byte.

Now you do write 0xff:

         i      0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
        SDAin  ___/¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯\______
        SCL    ¯¯\_/¯\_/¯\_/¯\_/¯\_/¯¯\__/¯¯\__/¯¯\__/¯¯\______/
                9   1   2   3   4    5     6     7     8

Quoted 7 lines

(assuming the SCL line goes up some time later to its idle state). That is you leave the bus in exactly the same state as before: The 9th clock isn't complete and the eeprom asserts SDA low to ack the byte just written. So the bus is still stalled. The problem is BTW the exact same one I introduced first in my bus clear routine (for barebox though). Even though you count to 2*9 you only do 8 real clock pulses because you have a half cycle at both the start and the end.

Fantastic explanation!!

So, we actually need to do "Low-High" 9 times instead of "High-Low". So, initializing val to 0 should fix it?

Quoted 9 lines

Quoted 4 lines

+ * @scl_gpio_flags: flag for gpio_request_one of scl_gpio. 0 implies
+ * GPIOF_OUT_INIT_LOW.
+ * @sda_gpio_flags: flag for gpio_request_one of sda_gpio. 0 implies
+ * GPIOF_OUT_INIT_LOW.

Didn't you want to change this to GPIOF_OUT_INIT_HIGH | GPIOF_OPEN_DRAIN? Hmm, I just wonder how to distinguish GPIOF_OUT_INIT_LOW from unset. Hmm, maybe assume unset because _LOW is wrong?

Hmmm.... Hmmmm... Hmmm... :)
Two things:
- Why should we default it to GPIOF_OPEN_DRAIN? Open drain would mean, gpio_set_value() will not write one for it, but would put it in input mode. I don't think that would be correct, as an generic case.

Quoted 2 lines

So, we actually need to do "Low-High" 9 times instead of "High-Low". So, initializing val to 0 should fix it?

I don't think this is enough. If you cut off the last half clock of the first sequence above doing 9 times low-high isn't enough. So you have to do high + 9x low-high to assert 9 full cycles.

Quoted 10 lines

Quoted 9 lines

Quoted 4 lines

+ * @scl_gpio_flags: flag for gpio_request_one of scl_gpio. 0 implies
+ * GPIOF_OUT_INIT_LOW.
+ * @sda_gpio_flags: flag for gpio_request_one of sda_gpio. 0 implies
+ * GPIOF_OUT_INIT_LOW.

Didn't you want to change this to GPIOF_OUT_INIT_HIGH | GPIOF_OPEN_DRAIN? Hmm, I just wonder how to distinguish GPIOF_OUT_INIT_LOW from unset. Hmm, maybe assume unset because _LOW is wrong?

Quoted 5 lines

Hmmm.... Hmmmm... Hmmm... :)
Two things:
- Why should we default it to GPIOF_OPEN_DRAIN? Open drain would mean, gpio_set_value() will not write one for it, but would put it in input mode. I don't think that would be correct, as an generic case.

As the i2c-bus is open drain and multi-master capable it's wrong to pull it to 1 because this can result in a short circuit. Even in a single-master scenario (where you can pull SCL in both directions) you must not drive SDA to 1.

Quoted 2 lines · Uwe Kleine-König

Quoted 2 lines

So, we actually need to do "Low-High" 9 times instead of "High-Low". So, initializing val to 0 should fix it?

Quoted 3 lines

I don't think this is enough. If you cut off the last half clock of the first sequence above doing 9 times low-high isn't enough. So you have to do high + 9x low-high to assert 9 full cycles.

I am not cutting the last half clock. val is the variable which keeps track of value to be
set on the line. I am asking to start from zero.

You mean, we should do a high first and then 9 low-high? But this line was high initially.. what difference will it make by making it high again?

Sorry, i am not a I2C expert, so need some help :)

Quoted 15 lines

Quoted 10 lines

Quoted 9 lines

Quoted 4 lines

+ * @scl_gpio_flags: flag for gpio_request_one of scl_gpio. 0 implies
+ * GPIOF_OUT_INIT_LOW.
+ * @sda_gpio_flags: flag for gpio_request_one of sda_gpio. 0 implies
+ * GPIOF_OUT_INIT_LOW.

Didn't you want to change this to GPIOF_OUT_INIT_HIGH | GPIOF_OPEN_DRAIN? Hmm, I just wonder how to distinguish GPIOF_OUT_INIT_LOW from unset. Hmm, maybe assume unset because _LOW is wrong?

Quoted 5 lines

Hmmm.... Hmmmm... Hmmm... :)
Two things:
- Why should we default it to GPIOF_OPEN_DRAIN? Open drain would mean, gpio_set_value() will not write one for it, but would put it in input mode. I don't think that would be correct, as an generic case.

Quoted 4 lines

As the i2c-bus is open drain and multi-master capable it's wrong to pull it to 1 because this can result in a short circuit. Even in a single-master scenario (where you can pull SCL in both directions) you must not drive SDA to 1.

Hmm... Hopefully i understood it well this time.
- We actually don't need these flags then.

Always pass:
- scl_flags: GPIOF_OPEN_DRAIN | GPIOF_OUT_INIT_HIGH
- sda_flags: GPIOF_IN

Why would anybody else require something different for any SoC?

Quoted 9 lines · Viresh Kumar

Quoted 5 lines · Uwe Kleine-König

Quoted 2 lines

So, we actually need to do "Low-High" 9 times instead of "High-Low". So, initializing val to 0 should fix it?

I don't think this is enough. If you cut off the last half clock of the first sequence above doing 9 times low-high isn't enough. So you have to do high + 9x low-high to assert 9 full cycles.

Quoted 3 lines

I am not cutting the last half clock. val is the variable which keeps track of value to be
set on the line. I am asking to start from zero.

I meant the sequence that created the stall, not the one intending to clear it. If you remove the last rising edge from that the SCL line is initially low.