i2c: Move to Linux like `struct i2c_msg`

Our current struct for I2C segments `i2c_seg` was close to being compa-
tible to the Linux version `i2c_msg`, close to being compatible to SMBus
and close to being readable (e.g. what was `chip` supposed to mean?) but
turned out to be hard to fix.

Instead of extending it in a backwards compatible way (and not touching
current controller drivers), replace it with a Linux source compatible
`struct i2c_msg` and patch all the drivers and users with Coccinelle.

The new `struct i2c_msg` should ease porting drivers from Linux and help
to write SMBus compatible controller drivers.

Beside integer type changes, the field `read` is replaced with a generic
field `flags` and `chip` is renamed to `slave`.

Patched with Coccinelle using the clumsy spatch below and some manual
changes:

* Nested struct initializers and one field access skipped by Coccinelle.
* Removed assumption in the code that I2C_M_RD is 1.
* In `i2c.h`, changed all occurences of `chip` to `slave`.

    @@ @@
    -struct i2c_seg
    +struct i2c_msg

    @@ identifier msg; expression e; @@
    (
     struct i2c_msg msg = {
    -    .read = 0,
    +    .flags = 0,
     };
    |
     struct i2c_msg msg = {
    -    .read = 1,
    +    .flags = I2C_M_RD,
     };
    |
     struct i2c_msg msg = {
    -    .chip = e,
    +    .slave = e,
     };
    )

    @@ struct i2c_msg msg; statement S1, S2; @@
    (
    -if (msg.read)
    +if (msg.flags & I2C_M_RD)
     S1 else S2
    |
    -if (msg.read)
    +if (msg.flags & I2C_M_RD)
     S1
    )

    @@ struct i2c_msg *msg; statement S1, S2; @@
    (
    -if (msg->read)
    +if (msg->flags & I2C_M_RD)
     S1 else S2
    |
    -if (msg->read)
    +if (msg->flags & I2C_M_RD)
     S1
    )

    @@ struct i2c_msg msg; expression e; @@
    (
    -msg.read = 0;
    +msg.flags = 0;
    |
    -msg.read = 1;
    +msg.flags = I2C_M_RD;
    |
    -msg.read = e;
    +msg.flags = e ? I2C_M_RD : 0;
    |
    -!!(msg.read)
    +(msg.flags & I2C_M_RD)
    |
    -(msg.read)
    +(msg.flags & I2C_M_RD)
    )

    @@ struct i2c_msg *msg; expression e; @@
    (
    -msg->read = 0;
    +msg->flags = 0;
    |
    -msg->read = 1;
    +msg->flags = I2C_M_RD;
    |
    -msg->read = e;
    +msg->flags = e ? I2C_M_RD : 0;
    |
    -!!(msg->read)
    +(msg->flags & I2C_M_RD)
    |
    -(msg->read)
    +(msg->flags & I2C_M_RD)
    )

    @@ struct i2c_msg msg; @@
    -msg.chip
    +msg.slave

    @@ struct i2c_msg *msg; expression e; @@
    -msg[e].chip
    +msg[e].slave

    @ slave disable ptr_to_array @ struct i2c_msg *msg; @@
    -msg->chip
    +msg->slave

Change-Id: Ifd7cabf0a18ffd7a1def25d1d7059b713d0b7ea9
Signed-off-by: Nico Huber <nico.huber@secunet.com>
Reviewed-on: https://review.coreboot.org/20542
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Aaron Durbin <adurbin@chromium.org>
Reviewed-by: Werner Zeh <werner.zeh@siemens.com>
Reviewed-by: Kyösti Mälkki <kyosti.malkki@gmail.com>
Reviewed-by: Paul Menzel <paulepanter@users.sourceforge.net>

1 files changed, 79 insertions, 49 deletions

diff --git a/src/include/device/i2c.h b/src/include/device/i2c.h
index 6115bd15e855..9939bc60bf3e 100644
--- a/src/include/device/i2c.h
+++ b/src/include/device/i2c.h
@@ -19,6 +19,41 @@
 #include <stdint.h>
 #include <stdlib.h>
 
+/**
+ * struct i2c_msg - an I2C transaction segment beginning with START
+ * @addr: Slave address, either seven or ten bits.  When this is a ten
+ *	bit address, I2C_M_TEN must be set in @flags.
+ * @flags: I2C_M_RD is handled by all adapters.
+ * @len: Number of data bytes in @buf being read from or written to the
+ *	I2C slave address.  For read transactions where I2C_M_RECV_LEN
+ *	is set, the caller guarantees that this buffer can hold up to
+ *	32 bytes in addition to the initial length byte sent by the
+ *	slave (plus, if used, the SMBus PEC).
+ * @buf: The buffer into which data is read, or from which it's written.
+ *
+ * An i2c_msg is the low level representation of one segment of an I2C
+ * transaction.  It is visible to drivers in the @i2c_transfer() procedure.
+ *
+ * All I2C adapters implement the standard rules for I2C transactions. Each
+ * transaction begins with a START.  That is followed by the slave address,
+ * and a bit encoding read versus write.  Then follow all the data bytes,
+ * possibly including a byte with SMBus PEC.  The transfer terminates with
+ * a NAK, or when all those bytes have been transferred and ACKed.  If this
+ * is the last message in a group, it is followed by a STOP.  Otherwise it
+ * is followed by the next @i2c_msg transaction segment, beginning with a
+ * (repeated) START.
+ */
+struct i2c_msg {
+	uint16_t flags;
+#define I2C_M_RD		0x0001	/* read data, from slave to master */
+#define I2C_M_TEN		0x0010	/* this is a ten bit chip address */
+#define I2C_M_RECV_LEN		0x0400	/* length will be first received byte */
+#define I2C_M_NOSTART		0x4000	/* don't send a repeated START */
+	uint16_t slave;		/* slave address			*/
+	uint16_t len;		/* msg length				*/
+	uint8_t *buf;		/* pointer to msg data			*/
+};
+
 enum i2c_speed {
 	I2C_SPEED_STANDARD	= 100000,
 	I2C_SPEED_FAST		= 400000,
@@ -32,15 +67,9 @@ enum i2c_address_mode {
 	I2C_MODE_10_BIT
 };
 
-struct i2c_seg {
-	int read;
-	uint8_t chip;
-	uint8_t *buf;
-	int len;
-};
 
-int platform_i2c_transfer(unsigned int bus, struct i2c_seg *segments,
-	int count);
+int platform_i2c_transfer(unsigned int bus, struct i2c_msg *segments,
+			  int count);
 
 #define SOFTWARE_I2C_MAX_BUS 10		/* increase as necessary */
 
@@ -53,15 +82,16 @@ struct software_i2c_ops {
 
 extern struct software_i2c_ops *software_i2c[];
 
-int software_i2c_transfer(unsigned int bus, struct i2c_seg *segments,
-	int count);
-void software_i2c_wedge_ack(unsigned int bus, u8 chip);
-void software_i2c_wedge_read(unsigned int bus, u8 chip, u8 reg, int bit_count);
-void software_i2c_wedge_write(unsigned int bus, u8 chip, u8 reg, int bit_count);
+int software_i2c_transfer(unsigned int bus, struct i2c_msg *segments,
+			  int count);
+void software_i2c_wedge_ack(unsigned int bus, u8 slave);
+void software_i2c_wedge_read(unsigned int bus, u8 slave, u8 reg, int bit_count);
+void software_i2c_wedge_write(unsigned int bus, u8 slave, u8 reg,
+			      int bit_count);
 
-int i2c_read_field(unsigned int bus, uint8_t chip, uint8_t reg, uint8_t *data,
+int i2c_read_field(unsigned int bus, uint8_t slave, uint8_t reg, uint8_t *data,
 		   uint8_t mask, uint8_t shift);
-int i2c_write_field(unsigned int bus, uint8_t chip, uint8_t reg, uint8_t data,
+int i2c_write_field(unsigned int bus, uint8_t slave, uint8_t reg, uint8_t data,
 		    uint8_t mask, uint8_t shift);
 
 /*
@@ -70,7 +100,7 @@ int i2c_write_field(unsigned int bus, uint8_t chip, uint8_t reg, uint8_t data,
  * Need this ugly stub to arbitrate since I2C device drivers hardcode
  * 'i2c_transfer()' as their entry point.
  */
-static inline int i2c_transfer(unsigned int bus, struct i2c_seg *segments,
+static inline int i2c_transfer(unsigned int bus, struct i2c_msg *segments,
 			       int count)
 {
 	if (CONFIG_SOFTWARE_I2C)
@@ -85,11 +115,11 @@ static inline int i2c_transfer(unsigned int bus, struct i2c_seg *segments,
  *
  * [start][slave addr][r][data][stop]
  */
-static inline int i2c_read_raw(unsigned int bus, uint8_t chip, uint8_t *data,
+static inline int i2c_read_raw(unsigned int bus, uint8_t slave, uint8_t *data,
 			       int len)
 {
-	struct i2c_seg seg = {
-		.read = 1, .chip = chip, .buf = data, .len = len
+	struct i2c_msg seg = {
+		.flags = I2C_M_RD, .slave = slave, .buf = data, .len = len
 	};
 
 	return i2c_transfer(bus, &seg, 1);
@@ -100,11 +130,11 @@ static inline int i2c_read_raw(unsigned int bus, uint8_t chip, uint8_t *data,
  *
  * [start][slave addr][w][data][stop]
  */
-static inline int i2c_write_raw(unsigned int bus, uint8_t chip, uint8_t *data,
+static inline int i2c_write_raw(unsigned int bus, uint8_t slave, uint8_t *data,
 				int len)
 {
-	struct i2c_seg seg = {
-		.read = 0, .chip = chip, .buf = data, .len = len
+	struct i2c_msg seg = {
+		.flags = 0, .slave = slave, .buf = data, .len = len
 	};
 
 	return i2c_transfer(bus, &seg, 1);
@@ -115,19 +145,19 @@ static inline int i2c_write_raw(unsigned int bus, uint8_t chip, uint8_t *data,
  *
  * [start][slave addr][w][register addr][start][slave addr][r][data...][stop]
  */
-static inline int i2c_read_bytes(unsigned int bus, uint8_t chip, uint8_t reg,
+static inline int i2c_read_bytes(unsigned int bus, uint8_t slave, uint8_t reg,
 				 uint8_t *data, int len)
 {
-	struct i2c_seg seg[2];
+	struct i2c_msg seg[2];
 
-	seg[0].read = 0;
-	seg[0].chip = chip;
-	seg[0].buf  = &reg;
-	seg[0].len  = 1;
-	seg[1].read = 1;
-	seg[1].chip = chip;
-	seg[1].buf  = data;
-	seg[1].len  = len;
+	seg[0].flags = 0;
+	seg[0].slave = slave;
+	seg[0].buf   = &reg;
+	seg[0].len   = 1;
+	seg[1].flags = I2C_M_RD;
+	seg[1].slave = slave;
+	seg[1].buf   = data;
+	seg[1].len   = len;
 
 	return i2c_transfer(bus, seg, ARRAY_SIZE(seg));
 }
@@ -137,19 +167,19 @@ static inline int i2c_read_bytes(unsigned int bus, uint8_t chip, uint8_t reg,
  *
  * [start][slave addr][w][register addr][start][slave addr][r][data][stop]
  */
-static inline int i2c_readb(unsigned int bus, uint8_t chip, uint8_t reg,
+static inline int i2c_readb(unsigned int bus, uint8_t slave, uint8_t reg,
 			    uint8_t *data)
 {
-	struct i2c_seg seg[2];
+	struct i2c_msg seg[2];
 
-	seg[0].read = 0;
-	seg[0].chip = chip;
-	seg[0].buf = &reg;
-	seg[0].len = 1;
-	seg[1].read = 1;
-	seg[1].chip = chip;
-	seg[1].buf = data;
-	seg[1].len = 1;
+	seg[0].flags = 0;
+	seg[0].slave = slave;
+	seg[0].buf   = &reg;
+	seg[0].len   = 1;
+	seg[1].flags = I2C_M_RD;
+	seg[1].slave = slave;
+	seg[1].buf   = data;
+	seg[1].len   = 1;
 
 	return i2c_transfer(bus, seg, ARRAY_SIZE(seg));
 }
@@ -159,16 +189,16 @@ static inline int i2c_readb(unsigned int bus, uint8_t chip, uint8_t reg,
  *
  * [start][slave addr][w][register addr][data][stop]
  */
-static inline int i2c_writeb(unsigned int bus, uint8_t chip, uint8_t reg,
+static inline int i2c_writeb(unsigned int bus, uint8_t slave, uint8_t reg,
 			     uint8_t data)
 {
-	struct i2c_seg seg;
+	struct i2c_msg seg;
 	uint8_t buf[] = {reg, data};
 
-	seg.read = 0;
-	seg.chip = chip;
-	seg.buf = buf;
-	seg.len = ARRAY_SIZE(buf);
+	seg.flags = 0;
+	seg.slave = slave;
+	seg.buf   = buf;
+	seg.len   = ARRAY_SIZE(buf);
 
 	return i2c_transfer(bus, &seg, 1);
 }
@@ -188,7 +218,7 @@ struct i2c_bus_operations {
 int i2c_dev_find_bus(struct device *dev);
 
 /* Variants of I2C helper functions that take a device instead of bus number */
-int i2c_dev_transfer(struct device *dev, struct i2c_seg *segments, int count);
+int i2c_dev_transfer(struct device *dev, struct i2c_msg *segments, int count);
 int i2c_dev_readb(struct device *dev, uint8_t reg, uint8_t *data);
 int i2c_dev_writeb(struct device *dev, uint8_t reg, uint8_t data);
 int i2c_dev_read_bytes(struct device *dev, uint8_t reg, uint8_t *data, int len);