cleanup: comments in i2c modules

No code changes; just update comments with bug links

BUG=none
BRANCH=none
TEST=build all platforms

Change-Id: I8b845f9c43315b7db5a746a16c6618c3ee96979d
Signed-off-by: Randall Spangler <rspangler@chromium.org>
Reviewed-on: https://chromium-review.googlesource.com/174614
Reviewed-by: Bill Richardson <wfrichar@chromium.org>

5 files changed, 27 insertions, 21 deletions

diff --git a/chip/stm32/i2c-stm32f.c b/chip/stm32/i2c-stm32f.c
index 1809b7cd3f..59f957279d 100644
--- a/chip/stm32/i2c-stm32f.c
+++ b/chip/stm32/i2c-stm32f.c
@@ -818,7 +818,7 @@ int i2c_xfer(int port, int slave_addr, const uint8_t *out, int out_bytes,
 {
 	int rv;
 
-	/* TODO: support start/stop flags */
+	/* TODO(crosbug.com/p/23569): support start/stop flags */
 
 	ASSERT(out || !out_bytes);
 	ASSERT(in || !in_bytes);
@@ -866,9 +866,9 @@ int i2c_read_string(int port, int slave_addr, int offset, uint8_t *data,
 	uint8_t reg, block_length;
 
 	/*
-	 * TODO: when i2c_xfer() supports start/stop bits, won't need a temp
-	 * buffer, and this code can merge with the LM4 implementation and
-	 * move to i2c_common.c.
+	 * TODO(crosbug.com/p/23569): when i2c_xfer() supports start/stop bits,
+	 * won't need a temp buffer, and this code can merge with the LM4
+	 * implementation and move to i2c_common.c.
 	 */
 	uint8_t buffer[SMBUS_MAX_BLOCK + 1];
 
diff --git a/chip/stm32/i2c-stm32l.c b/chip/stm32/i2c-stm32l.c
index 5b4f05fed5..27f6eb92bb 100644
--- a/chip/stm32/i2c-stm32l.c
+++ b/chip/stm32/i2c-stm32l.c
@@ -256,8 +256,6 @@ static void i2c_init_port(const struct i2c_port_t *p, int force_unwedge)
 
 	/* Set up initial bus frequencies */
 	i2c_set_freq_port(p);
-
-	/* TODO: enable interrupts using I2C_CR2 bits 8,9 */
 }
 
 /*****************************************************************************/
@@ -278,8 +276,8 @@ int i2c_xfer(int port, int slave_addr, const uint8_t *out, int out_bytes,
 	/*
 	 * Clear status
 	 *
-	 * TODO: should check for any leftover error status, and reset the
-	 * port if present.
+	 * TODO(crosbug.com/p/29314): should check for any leftover error
+	 * status, and reset the port if present.
 	 */
 	STM32_I2C_SR1(port) = 0;
 
@@ -457,9 +455,9 @@ int i2c_read_string(int port, int slave_addr, int offset, uint8_t *data,
 	uint8_t reg, block_length;
 
 	/*
-	 * TODO: when i2c_xfer() supports start/stop bits, won't need a temp
-	 * buffer, and this code can merge with the LM4 implementation and
-	 * move to i2c_common.c.
+	 * TODO(crosbug.com/p/23569): When i2c_xfer() supports start/stop bits
+	 * on all platforms, won't need a temp buffer, and this code can merge
+	 * with the LM4 implementation and move to i2c_common.c.
 	 */
 	uint8_t buffer[SMBUS_MAX_BLOCK + 1];
 
diff --git a/common/i2c.c b/common/i2c.c
index ed3a888872..2db40bdf21 100644
--- a/common/i2c.c
+++ b/common/i2c.c
@@ -114,7 +114,10 @@ int i2c_write8(int port, int slave_addr, int offset, int data)
 /*****************************************************************************/
 /* Host commands */
 
-/* TODO: replace with single I2C passthru command */
+/*
+ * TODO(crosbug.com/p/23570): remove separate read and write commands, as soon
+ * as ectool supports EC_CMD_I2C_PASSTHRU.
+ */
 
 static int i2c_command_read(struct host_cmd_handler_args *args)
 {
@@ -163,9 +166,8 @@ static int i2c_command_write(struct host_cmd_handler_args *args)
 }
 DECLARE_HOST_COMMAND(EC_CMD_I2C_WRITE, i2c_command_write, EC_VER_MASK(0));
 
-/* TODO: remove temporary extra debugging for help host-side debugging */
 #ifdef CONFIG_I2C_DEBUG_PASSTHRU
-#define PTHRUPRINTF(format, args...) cprintf(CC_I2C, format, ## args)
+#define PTHRUPRINTF(format, args...) CPRINTF(format, ## args)
 #else
 #define PTHRUPRINTF(format, args...)
 #endif
@@ -343,11 +345,10 @@ static void scan_bus(int port, const char *desc)
 
 #ifdef CHIP_FAMILY_stm32f
 		/*
-		 * Hope that address 0 exists, because the i2c_xfer()
-		 * implementation on STM32F can't read a byte without writing
-		 * one first.
-		 *
-		 * TODO: remove when that limitation is fixed.
+		 * TODO(crosbug.com/p/23569): The i2c_xfer() implementation on
+		 * STM32F can't read a byte without writing one first.  So
+		 * write a byte and hope nothing bad happens.  Remove this
+		 * workaround when STM32F is fixed.
 		 */
 		tmp = 0;
 		if (!i2c_xfer(port, a, &tmp, 1, &tmp, 1, I2C_XFER_SINGLE))
diff --git a/include/ec_commands.h b/include/ec_commands.h
index fb1f67c53d..9af502ca9a 100644
--- a/include/ec_commands.h
+++ b/include/ec_commands.h
@@ -1527,6 +1527,11 @@ struct ec_response_gpio_get {
 /*****************************************************************************/
 /* I2C commands. Only available when flash write protect is unlocked. */
 
+/*
+ * TODO(crosbug.com/p/23570): These commands are deprecated, and will be
+ * removed soon.  Use EC_CMD_I2C_XFER instead.
+ */
+
 /* Read I2C bus */
 #define EC_CMD_I2C_READ 0x94
 
diff --git a/util/ectool.c b/util/ectool.c
index 168068635f..382dd556a6 100644
--- a/util/ectool.c
+++ b/util/ectool.c
@@ -2359,7 +2359,8 @@ int cmd_i2c_read(int argc, char *argv[])
 	}
 
 	/*
-	 * TODO: use I2C_XFER command if supported, then fall back to I2C_READ
+	 * TODO(crosbug.com/p/23570): use I2C_XFER command if supported, then
+	 * fall back to I2C_READ.
 	 */
 
 	rv = ec_command(EC_CMD_I2C_READ, 0, &p, sizeof(p), &r, sizeof(r));
@@ -2417,7 +2418,8 @@ int cmd_i2c_write(int argc, char *argv[])
 	}
 
 	/*
-	 * TODO: use I2C_XFER command if supported, then fall back to I2C_WRITE
+	 * TODO(crosbug.com/p/23570): use I2C_XFER command if supported, then
+	 * fall back to I2C_WRITE.
 	 */
 
 	rv = ec_command(EC_CMD_I2C_WRITE, 0, &p, sizeof(p), NULL, 0);