[PATCH v2 0/4] i2c: slave: API updates

[PATCH v2 0/4] i2c: slave: API updates

[Wolfram Sang]

So, after some more thoughts and people using the slave framework, some API
updates seemed in place. Also, the documentation is now here. Please read the
patch description for details. Thanks to all people joining the discussion,
especially Uwe and Geert!

Changes since V1:

* added acks, except for patch 2 which has too many changes to keep them IMO
* reworded/updated the issues found in patch 2
* added patch 4

Wolfram Sang (4):
  i2c: slave: rework the slave API
  Documentation: i2c: describe the new slave mode
  i2c: slave: add documentation for i2c-slave-eeprom
  i2c: slave-eeprom: add more info when to increase the pointer

 Documentation/i2c/slave-eeprom-backend |  14 +++
 Documentation/i2c/slave-interface      | 179 +++++++++++++++++++++++++++++++++
 Documentation/i2c/summary              |   4 -
 drivers/i2c/busses/i2c-rcar.c          |  10 +-
 drivers/i2c/i2c-slave-eeprom.c         |  18 ++--
 include/linux/i2c.h                    |   8 +-
 6 files changed, 213 insertions(+), 20 deletions(-)
 create mode 100644 Documentation/i2c/slave-eeprom-backend
 create mode 100644 Documentation/i2c/slave-interface

-- 
2.1.4

[PATCH v2 0/4] i2c: slave: API updates

[Wolfram Sang]

So, after some more thoughts and people using the slave framework, some API
updates seemed in place. Also, the documentation is now here. Please read the
patch description for details. Thanks to all people joining the discussion,
especially Uwe and Geert!

Changes since V1:

* added acks, except for patch 2 which has too many changes to keep them IMO
* reworded/updated the issues found in patch 2
* added patch 4

Wolfram Sang (4):
  i2c: slave: rework the slave API
  Documentation: i2c: describe the new slave mode
  i2c: slave: add documentation for i2c-slave-eeprom
  i2c: slave-eeprom: add more info when to increase the pointer

 Documentation/i2c/slave-eeprom-backend |  14 +++
 Documentation/i2c/slave-interface      | 179 +++++++++++++++++++++++++++++++++
 Documentation/i2c/summary              |   4 -
 drivers/i2c/busses/i2c-rcar.c          |  10 +-
 drivers/i2c/i2c-slave-eeprom.c         |  18 ++--
 include/linux/i2c.h                    |   8 +-
 6 files changed, 213 insertions(+), 20 deletions(-)
 create mode 100644 Documentation/i2c/slave-eeprom-backend
 create mode 100644 Documentation/i2c/slave-interface

-- 
2.1.4

[PATCH v2 1/4] i2c: slave: rework the slave API

[Wolfram Sang]

From: Wolfram Sang <wsa+renesas@sang-engineering.com>

After more discussion, brave users, and additional datasheet evaluation,
some API updates for the new I2C slave framework became imminent. The
slave events now get some easier to understand naming. Also, the event
handling has been simplified to only need a single call to the slave
callback when an action by the backend is required.

Reported-by: Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
Signed-off-by: Wolfram Sang <wsa+renesas@sang-engineering.com>
Acked-by: Geert Uytterhoeven <geert+renesas@glider.be>
Acked-by: Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
---

Changes since V1: added acks

 drivers/i2c/busses/i2c-rcar.c  | 10 ++++------
 drivers/i2c/i2c-slave-eeprom.c | 12 ++++++------
 include/linux/i2c.h            |  8 ++++----
 3 files changed, 14 insertions(+), 16 deletions(-)

diff --git a/drivers/i2c/busses/i2c-rcar.c b/drivers/i2c/busses/i2c-rcar.c
index 71a6e07eb7ab7c..5a84bea5b84514 100644
--- a/drivers/i2c/busses/i2c-rcar.c
+++ b/drivers/i2c/busses/i2c-rcar.c
@@ -382,11 +382,11 @@ static bool rcar_i2c_slave_irq(struct rcar_i2c_priv *priv)
 	if (ssr_filtered & SAR) {
 		/* read or write request */
 		if (ssr_raw & STM) {
-			i2c_slave_event(priv->slave, I2C_SLAVE_REQ_READ_START, &value);
+			i2c_slave_event(priv->slave, I2C_SLAVE_READ_REQUESTED, &value);
 			rcar_i2c_write(priv, ICRXTX, value);
 			rcar_i2c_write(priv, ICSIER, SDE | SSR | SAR);
 		} else {
-			i2c_slave_event(priv->slave, I2C_SLAVE_REQ_WRITE_START, &value);
+			i2c_slave_event(priv->slave, I2C_SLAVE_WRITE_REQUESTED, &value);
 			rcar_i2c_read(priv, ICRXTX);	/* dummy read */
 			rcar_i2c_write(priv, ICSIER, SDR | SSR | SAR);
 		}
@@ -406,17 +406,15 @@ static bool rcar_i2c_slave_irq(struct rcar_i2c_priv *priv)
 		int ret;
 
 		value = rcar_i2c_read(priv, ICRXTX);
-		ret = i2c_slave_event(priv->slave, I2C_SLAVE_REQ_WRITE_END, &value);
+		ret = i2c_slave_event(priv->slave, I2C_SLAVE_WRITE_RECEIVED, &value);
 		/* Send NACK in case of error */
 		rcar_i2c_write(priv, ICSCR, SIE | SDBS | (ret < 0 ? FNA : 0));
-		i2c_slave_event(priv->slave, I2C_SLAVE_REQ_WRITE_START, &value);
 		rcar_i2c_write(priv, ICSSR, ~SDR & 0xff);
 	}
 
 	/* master wants to read from us */
 	if (ssr_filtered & SDE) {
-		i2c_slave_event(priv->slave, I2C_SLAVE_REQ_READ_END, &value);
-		i2c_slave_event(priv->slave, I2C_SLAVE_REQ_READ_START, &value);
+		i2c_slave_event(priv->slave, I2C_SLAVE_READ_PROCESSED, &value);
 		rcar_i2c_write(priv, ICRXTX, value);
 		rcar_i2c_write(priv, ICSSR, ~SDE & 0xff);
 	}
diff --git a/drivers/i2c/i2c-slave-eeprom.c b/drivers/i2c/i2c-slave-eeprom.c
index cf9b09db092f4e..3fb45d894d8072 100644
--- a/drivers/i2c/i2c-slave-eeprom.c
+++ b/drivers/i2c/i2c-slave-eeprom.c
@@ -36,7 +36,7 @@ static int i2c_slave_eeprom_slave_cb(struct i2c_client *client,
 	struct eeprom_data *eeprom = i2c_get_clientdata(client);
 
 	switch (event) {
-	case I2C_SLAVE_REQ_WRITE_END:
+	case I2C_SLAVE_WRITE_RECEIVED:
 		if (eeprom->first_write) {
 			eeprom->buffer_idx = *val;
 			eeprom->first_write = false;
@@ -47,17 +47,17 @@ static int i2c_slave_eeprom_slave_cb(struct i2c_client *client,
 		}
 		break;
 
-	case I2C_SLAVE_REQ_READ_START:
+	case I2C_SLAVE_READ_PROCESSED:
+		eeprom->buffer_idx++;
+		/* fallthrough */
+	case I2C_SLAVE_READ_REQUESTED:
 		spin_lock(&eeprom->buffer_lock);
 		*val = eeprom->buffer[eeprom->buffer_idx];
 		spin_unlock(&eeprom->buffer_lock);
 		break;
 
-	case I2C_SLAVE_REQ_READ_END:
-		eeprom->buffer_idx++;
-		break;
-
 	case I2C_SLAVE_STOP:
+	case I2C_SLAVE_WRITE_REQUESTED:
 		eeprom->first_write = true;
 		break;
 
diff --git a/include/linux/i2c.h b/include/linux/i2c.h
index f17da50402a4da..f76031608cb723 100644
--- a/include/linux/i2c.h
+++ b/include/linux/i2c.h
@@ -253,10 +253,10 @@ static inline void i2c_set_clientdata(struct i2c_client *dev, void *data)
 
 #if IS_ENABLED(CONFIG_I2C_SLAVE)
 enum i2c_slave_event {
-	I2C_SLAVE_REQ_READ_START,
-	I2C_SLAVE_REQ_READ_END,
-	I2C_SLAVE_REQ_WRITE_START,
-	I2C_SLAVE_REQ_WRITE_END,
+	I2C_SLAVE_READ_REQUESTED,
+	I2C_SLAVE_WRITE_REQUESTED,
+	I2C_SLAVE_READ_PROCESSED,
+	I2C_SLAVE_WRITE_RECEIVED,
 	I2C_SLAVE_STOP,
 };
 
-- 
2.1.4

[PATCH v2 1/4] i2c: slave: rework the slave API

[Wolfram Sang]

From: Wolfram Sang <wsa+renesas@sang-engineering.com>

After more discussion, brave users, and additional datasheet evaluation,
some API updates for the new I2C slave framework became imminent. The
slave events now get some easier to understand naming. Also, the event
handling has been simplified to only need a single call to the slave
callback when an action by the backend is required.

Reported-by: Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
Signed-off-by: Wolfram Sang <wsa+renesas@sang-engineering.com>
Acked-by: Geert Uytterhoeven <geert+renesas@glider.be>
Acked-by: Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
---

Changes since V1: added acks

 drivers/i2c/busses/i2c-rcar.c  | 10 ++++------
 drivers/i2c/i2c-slave-eeprom.c | 12 ++++++------
 include/linux/i2c.h            |  8 ++++----
 3 files changed, 14 insertions(+), 16 deletions(-)

diff --git a/drivers/i2c/busses/i2c-rcar.c b/drivers/i2c/busses/i2c-rcar.c
index 71a6e07eb7ab7c..5a84bea5b84514 100644
--- a/drivers/i2c/busses/i2c-rcar.c
+++ b/drivers/i2c/busses/i2c-rcar.c
@@ -382,11 +382,11 @@ static bool rcar_i2c_slave_irq(struct rcar_i2c_priv *priv)
 	if (ssr_filtered & SAR) {
 		/* read or write request */
 		if (ssr_raw & STM) {
-			i2c_slave_event(priv->slave, I2C_SLAVE_REQ_READ_START, &value);
+			i2c_slave_event(priv->slave, I2C_SLAVE_READ_REQUESTED, &value);
 			rcar_i2c_write(priv, ICRXTX, value);
 			rcar_i2c_write(priv, ICSIER, SDE | SSR | SAR);
 		} else {
-			i2c_slave_event(priv->slave, I2C_SLAVE_REQ_WRITE_START, &value);
+			i2c_slave_event(priv->slave, I2C_SLAVE_WRITE_REQUESTED, &value);
 			rcar_i2c_read(priv, ICRXTX);	/* dummy read */
 			rcar_i2c_write(priv, ICSIER, SDR | SSR | SAR);
 		}
@@ -406,17 +406,15 @@ static bool rcar_i2c_slave_irq(struct rcar_i2c_priv *priv)
 		int ret;
 
 		value = rcar_i2c_read(priv, ICRXTX);
-		ret = i2c_slave_event(priv->slave, I2C_SLAVE_REQ_WRITE_END, &value);
+		ret = i2c_slave_event(priv->slave, I2C_SLAVE_WRITE_RECEIVED, &value);
 		/* Send NACK in case of error */
 		rcar_i2c_write(priv, ICSCR, SIE | SDBS | (ret < 0 ? FNA : 0));
-		i2c_slave_event(priv->slave, I2C_SLAVE_REQ_WRITE_START, &value);
 		rcar_i2c_write(priv, ICSSR, ~SDR & 0xff);
 	}
 
 	/* master wants to read from us */
 	if (ssr_filtered & SDE) {
-		i2c_slave_event(priv->slave, I2C_SLAVE_REQ_READ_END, &value);
-		i2c_slave_event(priv->slave, I2C_SLAVE_REQ_READ_START, &value);
+		i2c_slave_event(priv->slave, I2C_SLAVE_READ_PROCESSED, &value);
 		rcar_i2c_write(priv, ICRXTX, value);
 		rcar_i2c_write(priv, ICSSR, ~SDE & 0xff);
 	}
diff --git a/drivers/i2c/i2c-slave-eeprom.c b/drivers/i2c/i2c-slave-eeprom.c
index cf9b09db092f4e..3fb45d894d8072 100644
--- a/drivers/i2c/i2c-slave-eeprom.c
+++ b/drivers/i2c/i2c-slave-eeprom.c
@@ -36,7 +36,7 @@ static int i2c_slave_eeprom_slave_cb(struct i2c_client *client,
 	struct eeprom_data *eeprom = i2c_get_clientdata(client);
 
 	switch (event) {
-	case I2C_SLAVE_REQ_WRITE_END:
+	case I2C_SLAVE_WRITE_RECEIVED:
 		if (eeprom->first_write) {
 			eeprom->buffer_idx = *val;
 			eeprom->first_write = false;
@@ -47,17 +47,17 @@ static int i2c_slave_eeprom_slave_cb(struct i2c_client *client,
 		}
 		break;
 
-	case I2C_SLAVE_REQ_READ_START:
+	case I2C_SLAVE_READ_PROCESSED:
+		eeprom->buffer_idx++;
+		/* fallthrough */
+	case I2C_SLAVE_READ_REQUESTED:
 		spin_lock(&eeprom->buffer_lock);
 		*val = eeprom->buffer[eeprom->buffer_idx];
 		spin_unlock(&eeprom->buffer_lock);
 		break;
 
-	case I2C_SLAVE_REQ_READ_END:
-		eeprom->buffer_idx++;
-		break;
-
 	case I2C_SLAVE_STOP:
+	case I2C_SLAVE_WRITE_REQUESTED:
 		eeprom->first_write = true;
 		break;
 
diff --git a/include/linux/i2c.h b/include/linux/i2c.h
index f17da50402a4da..f76031608cb723 100644
--- a/include/linux/i2c.h
+++ b/include/linux/i2c.h
@@ -253,10 +253,10 @@ static inline void i2c_set_clientdata(struct i2c_client *dev, void *data)
 
 #if IS_ENABLED(CONFIG_I2C_SLAVE)
 enum i2c_slave_event {
-	I2C_SLAVE_REQ_READ_START,
-	I2C_SLAVE_REQ_READ_END,
-	I2C_SLAVE_REQ_WRITE_START,
-	I2C_SLAVE_REQ_WRITE_END,
+	I2C_SLAVE_READ_REQUESTED,
+	I2C_SLAVE_WRITE_REQUESTED,
+	I2C_SLAVE_READ_PROCESSED,
+	I2C_SLAVE_WRITE_RECEIVED,
 	I2C_SLAVE_STOP,
 };
 
-- 
2.1.4

[PATCH v2 2/4] Documentation: i2c: describe the new slave mode

[Wolfram Sang]

From: Wolfram Sang <wsa+renesas@sang-engineering.com>

Signed-off-by: Wolfram Sang <wsa+renesas@sang-engineering.com>
---

Changes since V1:
* fixed all minor issues found by Geert
* fixed all minor issues found by Uwe
* made clear that NULL is not allowed as third parameter
* reworded the paragraph about I2C_SLAVE_READ_REQUESTED

 Documentation/i2c/slave-interface | 179 ++++++++++++++++++++++++++++++++++++++
 Documentation/i2c/summary         |   4 -
 2 files changed, 179 insertions(+), 4 deletions(-)
 create mode 100644 Documentation/i2c/slave-interface

diff --git a/Documentation/i2c/slave-interface b/Documentation/i2c/slave-interface
new file mode 100644
index 00000000000000..389bb5d618549e
--- /dev/null
+++ b/Documentation/i2c/slave-interface
@@ -0,0 +1,179 @@
+Linux I2C slave interface description
+==================+
+by Wolfram Sang <wsa@sang-engineering.com> in 2014-15
+
+Linux can also be an I2C slave in case I2C controllers have slave support.
+Besides this HW requirement, one also needs a software backend providing the
+actual functionality. An example for this is the slave-eeprom driver, which
+acts as a dual memory driver. While another I2C master on the bus can access it
+like a regular EEPROM, the Linux I2C slave can access the content via sysfs and
+retrieve/provide information as needed. The software backend driver and the I2C
+bus driver communicate via events. Here is a small graph visualizing the data
+flow and the means by which data is transported. The dotted line marks only one
+example. The backend could also use e.g. a character device, be in-kernel
+only, or something completely different:
+
+
+              e.g. sysfs        I2C slave events        I/O registers
+  +-----------+   v    +---------+     v     +--------+  v  +------------+
+  | Userspace +........+ Backend +-----------+ Driver +-----+ Controller |
+  +-----------+        +---------+           +--------+     +------------+
+                                                                | |
+  ----------------------------------------------------------------+--  I2C
+  --------------------------------------------------------------+----  Bus
+
+Note: Technically, there is also the I2C core between the backend and the
+driver. However, at this time of writing, the layer is transparent.
+
+
+User manual
+=====+
+I2C slave backends behave like standard I2C clients. So, you can instantiate
+them like described in the document 'instantiating-devices'. A quick example
+for instantiating the slave-eeprom driver from userspace:
+
+  # echo 0-0064 > /sys/bus/i2c/drivers/i2c-slave-eeprom/bind
+
+Each backend should come with separate documentation to describe its specific
+behaviour and setup.
+
+
+Developer manual
+========
+
+I2C slave events
+----------------
+
+The bus driver sends an event to the backend using the following function:
+
+	ret = i2c_slave_event(client, event, &val)
+
+'client' describes the i2c slave device. 'event' is one of the special event
+types described hereafter. 'val' holds an u8 value for the data byte to be
+read/written and is thus bidirectional. The pointer to val must always be
+provided even if val is not used for an event, i.e. don't use NULL here. 'ret'
+is the return value from the backend. Mandatory events must be provided by the
+bus drivers and must be checked for by backend drivers.
+
+Event types:
+
+* I2C_SLAVE_WRITE_REQUESTED (mandatory)
+
+'val': unused
+'ret': always 0
+
+Another I2C master wants to write data to us. This event should be sent once
+our own address and the write bit was detected. The data did not arrive yet, so
+there is nothing to process or return. Wakeup or initialization probably needs
+to be done, though.
+
+* I2C_SLAVE_READ_REQUESTED (mandatory)
+
+'val': backend returns first byte to be sent
+'ret': always 0
+
+Another I2C master wants to read data from us. This event should be sent once
+our own address and the read bit was detected. After returning, the bus driver
+should transmit the first byte.
+
+* I2C_SLAVE_WRITE_RECEIVED (mandatory)
+
+'val': bus driver delivers received byte
+'ret': 0 if the byte should be acked, some errno if the byte should be nacked
+
+Another I2C master has sent a byte to us which needs to be set in 'val'. If 'ret'
+is zero, the bus driver should ack this byte. If 'ret' is an errno, then the byte
+should be nacked.
+
+* I2C_SLAVE_READ_PROCESSED (mandatory)
+
+'val': backend returns next byte to be sent
+'ret': always 0
+
+The bus driver requests the next byte to be sent to another I2C master in
+'val'. Important: This does not mean that the previous byte has been acked, it
+only means that the previous byte is shifted out to the bus! To ensure seamless
+transmission, most hardware requests the next byte when the previous one is
+still shifted out. If the master sends NACK and stops reading after the byte
+currently shifted out, this byte requested here is never used. It very likely
+needs to be sent again on the next I2C_SLAVE_READ_REQUEST, depending a bit on
+your backend, though.
+
+* I2C_SLAVE_STOP (mandatory)
+
+'val': unused
+'ret': always 0
+
+A stop condition was received. This can happen anytime and the backend should
+reset its state machine for I2C transfers to be able to receive new requests.
+
+
+Software backends
+-----------------
+
+If you want to write a software backend:
+
+* use a standard i2c_driver and its matching mechanisms
+* write the slave_callback which handles the above slave events
+  (best using a state machine)
+* register this callback via i2c_slave_register()
+
+Check the i2c-slave-eeprom driver as an example.
+
+
+Bus driver support
+------------------
+
+If you want to add slave support to the bus driver:
+
+* implement calls to register/unregister the slave and add those to the
+  struct i2c_algorithm. When registering, you probably need to set the i2c
+  slave address and enable slave specific interrupts. If you use runtime pm, you
+  should use pm_runtime_forbid() because your device usually needs to be powered
+  on always to be able to detect its slave address. When unregistering, do the
+  inverse of the above.
+
+* Catch the slave interrupts and send appropriate i2c_slave_events to the backend.
+
+Check the i2c-rcar driver as an example.
+
+
+About ACK/NACK
+--------------
+
+It is good behaviour to always ACK the address phase, so the master knows if a
+device is basically present or if it mysteriously disappeared. Using NACK to
+state being busy is troublesome. SMBus demands to always ACK the address phase,
+while the I2C specification is more loose on that. Most I2C controllers also
+automatically ACK when detecting their slave addresses, so there is no option
+to NACK them. For those reasons, this API does not support NACK in the address
+phase.
+
+Currently, there is no slave event to report if the master did ACK or NACK a
+byte when it reads from us. We could make this an optional event if the need
+arises. However, cases should be extremely rare because the master is expected
+to send STOP after that and we have an event for that. Also, keep in mind not
+all I2C controllers have the possibility to report that event.
+
+
+About buffers
+-------------
+
+During development of this API, the question of using buffers instead of just
+bytes came up. Such an extension might be possible, usefulness is unclear at
+this time of writing. Some points to keep in mind when using buffers:
+
+* Buffers should be opt-in and slave drivers will always have to support
+  byte-based transactions as the ultimate fallback because this is how the
+  majority of HW works.
+
+* For backends simulating hardware registers, buffers are not helpful because
+  on writes an action should be immediately triggered. For reads, the data in
+  the buffer might get stale.
+
+* A master can send STOP at any time. For partially transferred buffers, this
+  means additional code to handle this exception. Such code tends to be
+  error-prone.
+
diff --git a/Documentation/i2c/summary b/Documentation/i2c/summary
index 13ab076dcd9248..809541ab352f03 100644
--- a/Documentation/i2c/summary
+++ b/Documentation/i2c/summary
@@ -41,7 +41,3 @@ integrated than Algorithm and Adapter.
 
 For a given configuration, you will need a driver for your I2C bus, and
 drivers for your I2C devices (usually one driver for each device).
-
-At this time, Linux only operates I2C (or SMBus) in master mode; you can't
-use these APIs to make a Linux system behave as a slave/device, either to
-speak a custom protocol or to emulate some other device.
-- 
2.1.4

[PATCH v2 2/4] Documentation: i2c: describe the new slave mode

[Wolfram Sang]

From: Wolfram Sang <wsa+renesas-jBu1N2QxHDJrcw3mvpCnnVaTQe2KTcn/@public.gmane.org>

Signed-off-by: Wolfram Sang <wsa+renesas-jBu1N2QxHDJrcw3mvpCnnVaTQe2KTcn/@public.gmane.org>
---

Changes since V1:
* fixed all minor issues found by Geert
* fixed all minor issues found by Uwe
* made clear that NULL is not allowed as third parameter
* reworded the paragraph about I2C_SLAVE_READ_REQUESTED

 Documentation/i2c/slave-interface | 179 ++++++++++++++++++++++++++++++++++++++
 Documentation/i2c/summary         |   4 -
 2 files changed, 179 insertions(+), 4 deletions(-)
 create mode 100644 Documentation/i2c/slave-interface

diff --git a/Documentation/i2c/slave-interface b/Documentation/i2c/slave-interface
new file mode 100644
index 00000000000000..389bb5d618549e
--- /dev/null
+++ b/Documentation/i2c/slave-interface
@@ -0,0 +1,179 @@
+Linux I2C slave interface description
+=====================================
+
+by Wolfram Sang <wsa-jBu1N2QxHDJrcw3mvpCnnVaTQe2KTcn/@public.gmane.org> in 2014-15
+
+Linux can also be an I2C slave in case I2C controllers have slave support.
+Besides this HW requirement, one also needs a software backend providing the
+actual functionality. An example for this is the slave-eeprom driver, which
+acts as a dual memory driver. While another I2C master on the bus can access it
+like a regular EEPROM, the Linux I2C slave can access the content via sysfs and
+retrieve/provide information as needed. The software backend driver and the I2C
+bus driver communicate via events. Here is a small graph visualizing the data
+flow and the means by which data is transported. The dotted line marks only one
+example. The backend could also use e.g. a character device, be in-kernel
+only, or something completely different:
+
+
+              e.g. sysfs        I2C slave events        I/O registers
+  +-----------+   v    +---------+     v     +--------+  v  +------------+
+  | Userspace +........+ Backend +-----------+ Driver +-----+ Controller |
+  +-----------+        +---------+           +--------+     +------------+
+                                                                | |
+  ----------------------------------------------------------------+--  I2C
+  --------------------------------------------------------------+----  Bus
+
+Note: Technically, there is also the I2C core between the backend and the
+driver. However, at this time of writing, the layer is transparent.
+
+
+User manual
+===========
+
+I2C slave backends behave like standard I2C clients. So, you can instantiate
+them like described in the document 'instantiating-devices'. A quick example
+for instantiating the slave-eeprom driver from userspace:
+
+  # echo 0-0064 > /sys/bus/i2c/drivers/i2c-slave-eeprom/bind
+
+Each backend should come with separate documentation to describe its specific
+behaviour and setup.
+
+
+Developer manual
+================
+
+I2C slave events
+----------------
+
+The bus driver sends an event to the backend using the following function:
+
+	ret = i2c_slave_event(client, event, &val)
+
+'client' describes the i2c slave device. 'event' is one of the special event
+types described hereafter. 'val' holds an u8 value for the data byte to be
+read/written and is thus bidirectional. The pointer to val must always be
+provided even if val is not used for an event, i.e. don't use NULL here. 'ret'
+is the return value from the backend. Mandatory events must be provided by the
+bus drivers and must be checked for by backend drivers.
+
+Event types:
+
+* I2C_SLAVE_WRITE_REQUESTED (mandatory)
+
+'val': unused
+'ret': always 0
+
+Another I2C master wants to write data to us. This event should be sent once
+our own address and the write bit was detected. The data did not arrive yet, so
+there is nothing to process or return. Wakeup or initialization probably needs
+to be done, though.
+
+* I2C_SLAVE_READ_REQUESTED (mandatory)
+
+'val': backend returns first byte to be sent
+'ret': always 0
+
+Another I2C master wants to read data from us. This event should be sent once
+our own address and the read bit was detected. After returning, the bus driver
+should transmit the first byte.
+
+* I2C_SLAVE_WRITE_RECEIVED (mandatory)
+
+'val': bus driver delivers received byte
+'ret': 0 if the byte should be acked, some errno if the byte should be nacked
+
+Another I2C master has sent a byte to us which needs to be set in 'val'. If 'ret'
+is zero, the bus driver should ack this byte. If 'ret' is an errno, then the byte
+should be nacked.
+
+* I2C_SLAVE_READ_PROCESSED (mandatory)
+
+'val': backend returns next byte to be sent
+'ret': always 0
+
+The bus driver requests the next byte to be sent to another I2C master in
+'val'. Important: This does not mean that the previous byte has been acked, it
+only means that the previous byte is shifted out to the bus! To ensure seamless
+transmission, most hardware requests the next byte when the previous one is
+still shifted out. If the master sends NACK and stops reading after the byte
+currently shifted out, this byte requested here is never used. It very likely
+needs to be sent again on the next I2C_SLAVE_READ_REQUEST, depending a bit on
+your backend, though.
+
+* I2C_SLAVE_STOP (mandatory)
+
+'val': unused
+'ret': always 0
+
+A stop condition was received. This can happen anytime and the backend should
+reset its state machine for I2C transfers to be able to receive new requests.
+
+
+Software backends
+-----------------
+
+If you want to write a software backend:
+
+* use a standard i2c_driver and its matching mechanisms
+* write the slave_callback which handles the above slave events
+  (best using a state machine)
+* register this callback via i2c_slave_register()
+
+Check the i2c-slave-eeprom driver as an example.
+
+
+Bus driver support
+------------------
+
+If you want to add slave support to the bus driver:
+
+* implement calls to register/unregister the slave and add those to the
+  struct i2c_algorithm. When registering, you probably need to set the i2c
+  slave address and enable slave specific interrupts. If you use runtime pm, you
+  should use pm_runtime_forbid() because your device usually needs to be powered
+  on always to be able to detect its slave address. When unregistering, do the
+  inverse of the above.
+
+* Catch the slave interrupts and send appropriate i2c_slave_events to the backend.
+
+Check the i2c-rcar driver as an example.
+
+
+About ACK/NACK
+--------------
+
+It is good behaviour to always ACK the address phase, so the master knows if a
+device is basically present or if it mysteriously disappeared. Using NACK to
+state being busy is troublesome. SMBus demands to always ACK the address phase,
+while the I2C specification is more loose on that. Most I2C controllers also
+automatically ACK when detecting their slave addresses, so there is no option
+to NACK them. For those reasons, this API does not support NACK in the address
+phase.
+
+Currently, there is no slave event to report if the master did ACK or NACK a
+byte when it reads from us. We could make this an optional event if the need
+arises. However, cases should be extremely rare because the master is expected
+to send STOP after that and we have an event for that. Also, keep in mind not
+all I2C controllers have the possibility to report that event.
+
+
+About buffers
+-------------
+
+During development of this API, the question of using buffers instead of just
+bytes came up. Such an extension might be possible, usefulness is unclear at
+this time of writing. Some points to keep in mind when using buffers:
+
+* Buffers should be opt-in and slave drivers will always have to support
+  byte-based transactions as the ultimate fallback because this is how the
+  majority of HW works.
+
+* For backends simulating hardware registers, buffers are not helpful because
+  on writes an action should be immediately triggered. For reads, the data in
+  the buffer might get stale.
+
+* A master can send STOP at any time. For partially transferred buffers, this
+  means additional code to handle this exception. Such code tends to be
+  error-prone.
+
diff --git a/Documentation/i2c/summary b/Documentation/i2c/summary
index 13ab076dcd9248..809541ab352f03 100644
--- a/Documentation/i2c/summary
+++ b/Documentation/i2c/summary
@@ -41,7 +41,3 @@ integrated than Algorithm and Adapter.
 
 For a given configuration, you will need a driver for your I2C bus, and
 drivers for your I2C devices (usually one driver for each device).
-
-At this time, Linux only operates I2C (or SMBus) in master mode; you can't
-use these APIs to make a Linux system behave as a slave/device, either to
-speak a custom protocol or to emulate some other device.
-- 
2.1.4

[PATCH v2 3/4] i2c: slave: add documentation for i2c-slave-eeprom

From: Wolfram Sang <wsa+renesas@sang-engineering.com>

Signed-off-by: Wolfram Sang <wsa+renesas@sang-engineering.com>
Acked-by: Geert Uytterhoeven <geert+renesas@glider.be>
---

Changes since V1: added acks

 Documentation/i2c/slave-eeprom-backend | 14 ++++++++++++++
 1 file changed, 14 insertions(+)
 create mode 100644 Documentation/i2c/slave-eeprom-backend

diff --git a/Documentation/i2c/slave-eeprom-backend b/Documentation/i2c/slave-eeprom-backend
new file mode 100644
index 00000000000000..c8444ef82acfa3
--- /dev/null
+++ b/Documentation/i2c/slave-eeprom-backend
@@ -0,0 +1,14 @@
+Linux I2C slave eeprom backend
+===============
+
+by Wolfram Sang <wsa@sang-engineering.com> in 2014-15
+
+This is a proof-of-concept backend which acts like an EEPROM on the connected
+I2C bus. The memory contents can be modified from userspace via this file
+located in sysfs:
+
+	/sys/bus/i2c/devices/<device-direcory>/slave-eeprom
+
+As of 2015, Linux doesn't support poll on binary sysfs files, so there is no
+notfication when another master changed the content.
+
-- 
2.1.4

[PATCH v2 3/4] i2c: slave: add documentation for i2c-slave-eeprom

[Wolfram Sang]

From: Wolfram Sang <wsa+renesas-jBu1N2QxHDJrcw3mvpCnnVaTQe2KTcn/@public.gmane.org>

Signed-off-by: Wolfram Sang <wsa+renesas-jBu1N2QxHDJrcw3mvpCnnVaTQe2KTcn/@public.gmane.org>
Acked-by: Geert Uytterhoeven <geert+renesas-gXvu3+zWzMSzQB+pC5nmwQ@public.gmane.org>
---

Changes since V1: added acks

 Documentation/i2c/slave-eeprom-backend | 14 ++++++++++++++
 1 file changed, 14 insertions(+)
 create mode 100644 Documentation/i2c/slave-eeprom-backend

diff --git a/Documentation/i2c/slave-eeprom-backend b/Documentation/i2c/slave-eeprom-backend
new file mode 100644
index 00000000000000..c8444ef82acfa3
--- /dev/null
+++ b/Documentation/i2c/slave-eeprom-backend
@@ -0,0 +1,14 @@
+Linux I2C slave eeprom backend
+==============================
+
+by Wolfram Sang <wsa-jBu1N2QxHDJrcw3mvpCnnVaTQe2KTcn/@public.gmane.org> in 2014-15
+
+This is a proof-of-concept backend which acts like an EEPROM on the connected
+I2C bus. The memory contents can be modified from userspace via this file
+located in sysfs:
+
+	/sys/bus/i2c/devices/<device-direcory>/slave-eeprom
+
+As of 2015, Linux doesn't support poll on binary sysfs files, so there is no
+notfication when another master changed the content.
+
-- 
2.1.4

[PATCH v2 4/4] i2c: slave-eeprom: add more info when to increase the pointer

[Wolfram Sang]

From: Wolfram Sang <wsa+renesas@sang-engineering.com>

It is a bit subtle when to correctly increase the buffer index when
reading. Make this clearer by adding some more comments and pointers to
the docs.

Signed-off-by: Wolfram Sang <wsa+renesas@sang-engineering.com>
---

Changes since V1: new patch

 drivers/i2c/i2c-slave-eeprom.c | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/drivers/i2c/i2c-slave-eeprom.c b/drivers/i2c/i2c-slave-eeprom.c
index 3fb45d894d8072..8223746546093c 100644
--- a/drivers/i2c/i2c-slave-eeprom.c
+++ b/drivers/i2c/i2c-slave-eeprom.c
@@ -48,12 +48,18 @@ static int i2c_slave_eeprom_slave_cb(struct i2c_client *client,
 		break;
 
 	case I2C_SLAVE_READ_PROCESSED:
+		/* The previous byte made it to the bus, get next one */
 		eeprom->buffer_idx++;
 		/* fallthrough */
 	case I2C_SLAVE_READ_REQUESTED:
 		spin_lock(&eeprom->buffer_lock);
 		*val = eeprom->buffer[eeprom->buffer_idx];
 		spin_unlock(&eeprom->buffer_lock);
+		/*
+		 * Do not increment buffer_idx here, because we don't know if
+		 * this byte will be actually used. Read Linux I2C slave docs
+		 * for details.
+		 */
 		break;
 
 	case I2C_SLAVE_STOP:
-- 
2.1.4

[PATCH v2 4/4] i2c: slave-eeprom: add more info when to increase the pointer

[Wolfram Sang]

From: Wolfram Sang <wsa+renesas-jBu1N2QxHDJrcw3mvpCnnVaTQe2KTcn/@public.gmane.org>

It is a bit subtle when to correctly increase the buffer index when
reading. Make this clearer by adding some more comments and pointers to
the docs.

Signed-off-by: Wolfram Sang <wsa+renesas-jBu1N2QxHDJrcw3mvpCnnVaTQe2KTcn/@public.gmane.org>
---

Changes since V1: new patch

 drivers/i2c/i2c-slave-eeprom.c | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/drivers/i2c/i2c-slave-eeprom.c b/drivers/i2c/i2c-slave-eeprom.c
index 3fb45d894d8072..8223746546093c 100644
--- a/drivers/i2c/i2c-slave-eeprom.c
+++ b/drivers/i2c/i2c-slave-eeprom.c
@@ -48,12 +48,18 @@ static int i2c_slave_eeprom_slave_cb(struct i2c_client *client,
 		break;
 
 	case I2C_SLAVE_READ_PROCESSED:
+		/* The previous byte made it to the bus, get next one */
 		eeprom->buffer_idx++;
 		/* fallthrough */
 	case I2C_SLAVE_READ_REQUESTED:
 		spin_lock(&eeprom->buffer_lock);
 		*val = eeprom->buffer[eeprom->buffer_idx];
 		spin_unlock(&eeprom->buffer_lock);
+		/*
+		 * Do not increment buffer_idx here, because we don't know if
+		 * this byte will be actually used. Read Linux I2C slave docs
+		 * for details.
+		 */
 		break;
 
 	case I2C_SLAVE_STOP:
-- 
2.1.4

Re: [PATCH v2 4/4] i2c: slave-eeprom: add more info when to increase the pointer

[Uwe Kleine-König]

On Mon, Mar 23, 2015 at 09:26:39AM +0100, Wolfram Sang wrote:
> From: Wolfram Sang <wsa+renesas@sang-engineering.com>
> 
> It is a bit subtle when to correctly increase the buffer index when
> reading. Make this clearer by adding some more comments and pointers to
> the docs.
> 
> Signed-off-by: Wolfram Sang <wsa+renesas@sang-engineering.com>
Acked-by: Uwe Kleine-König <u.kleine-koenig@pengutronix.de>

-- 
Pengutronix e.K.                           | Uwe Kleine-König            |
Industrial Linux Solutions                 | http://www.pengutronix.de/  |

Re: [PATCH v2 4/4] i2c: slave-eeprom: add more info when to increase the pointer

[Uwe Kleine-König]

On Mon, Mar 23, 2015 at 09:26:39AM +0100, Wolfram Sang wrote:
> From: Wolfram Sang <wsa+renesas-jBu1N2QxHDJrcw3mvpCnnVaTQe2KTcn/@public.gmane.org>
> 
> It is a bit subtle when to correctly increase the buffer index when
> reading. Make this clearer by adding some more comments and pointers to
> the docs.
> 
> Signed-off-by: Wolfram Sang <wsa+renesas-jBu1N2QxHDJrcw3mvpCnnVaTQe2KTcn/@public.gmane.org>
Acked-by: Uwe Kleine-König <u.kleine-koenig-bIcnvbaLZ9MEGnE8C9+IrQ@public.gmane.org>

-- 
Pengutronix e.K.                           | Uwe Kleine-König            |
Industrial Linux Solutions                 | http://www.pengutronix.de/  |

Re: [PATCH v2 2/4] Documentation: i2c: describe the new slave mode

[Uwe Kleine-König]

Hello Wolfram,

On Mon, Mar 23, 2015 at 09:26:37AM +0100, Wolfram Sang wrote:
> +Developer manual
> +========
> +
> +I2C slave events
> +----------------
> +
> +The bus driver sends an event to the backend using the following function:
> +
> +	ret = i2c_slave_event(client, event, &val)
> +
> +'client' describes the i2c slave device. 'event' is one of the special event
> +types described hereafter. 'val' holds an u8 value for the data byte to be
> +read/written and is thus bidirectional. The pointer to val must always be
> +provided even if val is not used for an event, i.e. don't use NULL here. 'ret'
> +is the return value from the backend. Mandatory events must be provided by the
I don't understand why you want to force a valid pointer here. According
to my sense of defensive programming I'd say: If the bus driver doesn't
expect the slave to consume/provide a value, let's pass NULL to notice
the assumption being wrong. The wording is fine, now.

> diff --git a/Documentation/i2c/summary b/Documentation/i2c/summary
> index 13ab076dcd9248..809541ab352f03 100644
> --- a/Documentation/i2c/summary
> +++ b/Documentation/i2c/summary
> @@ -41,7 +41,3 @@ integrated than Algorithm and Adapter.
>  
>  For a given configuration, you will need a driver for your I2C bus, and
>  drivers for your I2C devices (usually one driver for each device).
> -
> -At this time, Linux only operates I2C (or SMBus) in master mode; you can't
> -use these APIs to make a Linux system behave as a slave/device, either to
> -speak a custom protocol or to emulate some other device.
\o/

Best regards
Uwe

-- 
Pengutronix e.K.                           | Uwe Kleine-König            |
Industrial Linux Solutions                 | http://www.pengutronix.de/  |

Re: [PATCH v2 2/4] Documentation: i2c: describe the new slave mode

[Uwe Kleine-König]

Hello Wolfram,

On Mon, Mar 23, 2015 at 09:26:37AM +0100, Wolfram Sang wrote:
> +Developer manual
> +================
> +
> +I2C slave events
> +----------------
> +
> +The bus driver sends an event to the backend using the following function:
> +
> +	ret = i2c_slave_event(client, event, &val)
> +
> +'client' describes the i2c slave device. 'event' is one of the special event
> +types described hereafter. 'val' holds an u8 value for the data byte to be
> +read/written and is thus bidirectional. The pointer to val must always be
> +provided even if val is not used for an event, i.e. don't use NULL here. 'ret'
> +is the return value from the backend. Mandatory events must be provided by the
I don't understand why you want to force a valid pointer here. According
to my sense of defensive programming I'd say: If the bus driver doesn't
expect the slave to consume/provide a value, let's pass NULL to notice
the assumption being wrong. The wording is fine, now.

> diff --git a/Documentation/i2c/summary b/Documentation/i2c/summary
> index 13ab076dcd9248..809541ab352f03 100644
> --- a/Documentation/i2c/summary
> +++ b/Documentation/i2c/summary
> @@ -41,7 +41,3 @@ integrated than Algorithm and Adapter.
>  
>  For a given configuration, you will need a driver for your I2C bus, and
>  drivers for your I2C devices (usually one driver for each device).
> -
> -At this time, Linux only operates I2C (or SMBus) in master mode; you can't
> -use these APIs to make a Linux system behave as a slave/device, either to
> -speak a custom protocol or to emulate some other device.
\o/

Best regards
Uwe

-- 
Pengutronix e.K.                           | Uwe Kleine-König            |
Industrial Linux Solutions                 | http://www.pengutronix.de/  |

Re: [PATCH v2 2/4] Documentation: i2c: describe the new slave mode

[Wolfram Sang]

[-- Attachment #1: Type: text/plain, Size: 557 bytes --]


> I don't understand why you want to force a valid pointer here. According
> to my sense of defensive programming I'd say: If the bus driver doesn't
> expect the slave to consume/provide a value, let's pass NULL to notice
> the assumption being wrong. The wording is fine, now.

For me, an OOPS is quite much of a "notice". I assume there will be
non-upstream backends. I am not keen to see devices in the field to OOPS
because the implementation missed a case how to handle the pointer
correctly. Now, the rule of thumb is easy: Always pass the pointer.


[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 819 bytes --]

Re: [PATCH v2 2/4] Documentation: i2c: describe the new slave mode

[Wolfram Sang]

[-- Attachment #1: Type: text/plain, Size: 557 bytes --]


> I don't understand why you want to force a valid pointer here. According
> to my sense of defensive programming I'd say: If the bus driver doesn't
> expect the slave to consume/provide a value, let's pass NULL to notice
> the assumption being wrong. The wording is fine, now.

For me, an OOPS is quite much of a "notice". I assume there will be
non-upstream backends. I am not keen to see devices in the field to OOPS
because the implementation missed a case how to handle the pointer
correctly. Now, the rule of thumb is easy: Always pass the pointer.


[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 819 bytes --]

Re: [PATCH v2 0/4] i2c: slave: API updates

[Wolfram Sang]

[-- Attachment #1: Type: text/plain, Size: 782 bytes --]

On Mon, Mar 23, 2015 at 09:26:35AM +0100, Wolfram Sang wrote:
> So, after some more thoughts and people using the slave framework, some API
> updates seemed in place. Also, the documentation is now here. Please read the
> patch description for details. Thanks to all people joining the discussion,
> especially Uwe and Geert!
> 
> Changes since V1:
> 
> * added acks, except for patch 2 which has too many changes to keep them IMO
> * reworded/updated the issues found in patch 2
> * added patch 4
> 
> Wolfram Sang (4):
>   i2c: slave: rework the slave API
>   Documentation: i2c: describe the new slave mode
>   i2c: slave: add documentation for i2c-slave-eeprom
>   i2c: slave-eeprom: add more info when to increase the pointer

Applied to for-next, thanks!


[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 819 bytes --]

Re: [PATCH v2 0/4] i2c: slave: API updates

[Wolfram Sang]

[-- Attachment #1: Type: text/plain, Size: 782 bytes --]

On Mon, Mar 23, 2015 at 09:26:35AM +0100, Wolfram Sang wrote:
> So, after some more thoughts and people using the slave framework, some API
> updates seemed in place. Also, the documentation is now here. Please read the
> patch description for details. Thanks to all people joining the discussion,
> especially Uwe and Geert!
> 
> Changes since V1:
> 
> * added acks, except for patch 2 which has too many changes to keep them IMO
> * reworded/updated the issues found in patch 2
> * added patch 4
> 
> Wolfram Sang (4):
>   i2c: slave: rework the slave API
>   Documentation: i2c: describe the new slave mode
>   i2c: slave: add documentation for i2c-slave-eeprom
>   i2c: slave-eeprom: add more info when to increase the pointer

Applied to for-next, thanks!


[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 819 bytes --]

Re: [PATCH v2 2/4] Documentation: i2c: describe the new slave mode

[Geert Uytterhoeven]

Hi Wolfram,

On Mon, Mar 23, 2015 at 9:26 AM, Wolfram Sang <wsa@the-dreams.de> wrote:
> --- /dev/null
> +++ b/Documentation/i2c/slave-interface

> +I2C slave events
> +----------------
> +
> +The bus driver sends an event to the backend using the following function:
> +
> +       ret = i2c_slave_event(client, event, &val)
> +
> +'client' describes the i2c slave device. 'event' is one of the special event
> +types described hereafter. 'val' holds an u8 value for the data byte to be
> +read/written and is thus bidirectional. The pointer to val must always be
> +provided even if val is not used for an event, i.e. don't use NULL here. 'ret'
> +is the return value from the backend. Mandatory events must be provided by the
> +bus drivers and must be checked for by backend drivers.
> +
> +Event types:
> +
> +* I2C_SLAVE_WRITE_REQUESTED (mandatory)
> +
> +'val': unused
> +'ret': always 0
> +
> +Another I2C master wants to write data to us. This event should be sent once
> +our own address and the write bit was detected. The data did not arrive yet, so
> +there is nothing to process or return. Wakeup or initialization probably needs
> +to be done, though.
> +
> +* I2C_SLAVE_READ_REQUESTED (mandatory)

I'm wondering whether these should be called I2C_SLAVE_READ_FIRST...

> +'val': backend returns first byte to be sent
> +'ret': always 0
> +
> +Another I2C master wants to read data from us. This event should be sent once
> +our own address and the read bit was detected. After returning, the bus driver
> +should transmit the first byte.
> +
> +* I2C_SLAVE_WRITE_RECEIVED (mandatory)
> +
> +'val': bus driver delivers received byte
> +'ret': 0 if the byte should be acked, some errno if the byte should be nacked
> +
> +Another I2C master has sent a byte to us which needs to be set in 'val'. If 'ret'
> +is zero, the bus driver should ack this byte. If 'ret' is an errno, then the byte
> +should be nacked.
> +
> +* I2C_SLAVE_READ_PROCESSED (mandatory)

... and I2C_SLAVE_READ_NEXT?

I don't have good alternative names for the write operation, as it's not
symmetric.

> +'val': backend returns next byte to be sent
> +'ret': always 0
> +
> +The bus driver requests the next byte to be sent to another I2C master in
> +'val'. Important: This does not mean that the previous byte has been acked, it
> +only means that the previous byte is shifted out to the bus! To ensure seamless
> +transmission, most hardware requests the next byte when the previous one is
> +still shifted out. If the master sends NACK and stops reading after the byte
> +currently shifted out, this byte requested here is never used. It very likely
> +needs to be sent again on the next I2C_SLAVE_READ_REQUEST, depending a bit on
> +your backend, though.

Gr{oetje,eeting}s,

                        Geert

--
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- geert@linux-m68k.org

In personal conversations with technical people, I call myself a hacker. But
when I'm talking to journalists I just say "programmer" or something like that.
                                -- Linus Torvalds

Re: [PATCH v2 2/4] Documentation: i2c: describe the new slave mode

[Geert Uytterhoeven]

Hi Wolfram,

On Mon, Mar 23, 2015 at 9:26 AM, Wolfram Sang <wsa-z923LK4zBo2bacvFa/9K2g@public.gmane.org> wrote:
> --- /dev/null
> +++ b/Documentation/i2c/slave-interface

> +I2C slave events
> +----------------
> +
> +The bus driver sends an event to the backend using the following function:
> +
> +       ret = i2c_slave_event(client, event, &val)
> +
> +'client' describes the i2c slave device. 'event' is one of the special event
> +types described hereafter. 'val' holds an u8 value for the data byte to be
> +read/written and is thus bidirectional. The pointer to val must always be
> +provided even if val is not used for an event, i.e. don't use NULL here. 'ret'
> +is the return value from the backend. Mandatory events must be provided by the
> +bus drivers and must be checked for by backend drivers.
> +
> +Event types:
> +
> +* I2C_SLAVE_WRITE_REQUESTED (mandatory)
> +
> +'val': unused
> +'ret': always 0
> +
> +Another I2C master wants to write data to us. This event should be sent once
> +our own address and the write bit was detected. The data did not arrive yet, so
> +there is nothing to process or return. Wakeup or initialization probably needs
> +to be done, though.
> +
> +* I2C_SLAVE_READ_REQUESTED (mandatory)

I'm wondering whether these should be called I2C_SLAVE_READ_FIRST...

> +'val': backend returns first byte to be sent
> +'ret': always 0
> +
> +Another I2C master wants to read data from us. This event should be sent once
> +our own address and the read bit was detected. After returning, the bus driver
> +should transmit the first byte.
> +
> +* I2C_SLAVE_WRITE_RECEIVED (mandatory)
> +
> +'val': bus driver delivers received byte
> +'ret': 0 if the byte should be acked, some errno if the byte should be nacked
> +
> +Another I2C master has sent a byte to us which needs to be set in 'val'. If 'ret'
> +is zero, the bus driver should ack this byte. If 'ret' is an errno, then the byte
> +should be nacked.
> +
> +* I2C_SLAVE_READ_PROCESSED (mandatory)

... and I2C_SLAVE_READ_NEXT?

I don't have good alternative names for the write operation, as it's not
symmetric.

> +'val': backend returns next byte to be sent
> +'ret': always 0
> +
> +The bus driver requests the next byte to be sent to another I2C master in
> +'val'. Important: This does not mean that the previous byte has been acked, it
> +only means that the previous byte is shifted out to the bus! To ensure seamless
> +transmission, most hardware requests the next byte when the previous one is
> +still shifted out. If the master sends NACK and stops reading after the byte
> +currently shifted out, this byte requested here is never used. It very likely
> +needs to be sent again on the next I2C_SLAVE_READ_REQUEST, depending a bit on
> +your backend, though.

Gr{oetje,eeting}s,

                        Geert

--
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- geert-Td1EMuHUCqxL1ZNQvxDV9g@public.gmane.org

In personal conversations with technical people, I call myself a hacker. But
when I'm talking to journalists I just say "programmer" or something like that.
                                -- Linus Torvalds

Re: [PATCH v2 2/4] Documentation: i2c: describe the new slave mode

[Wolfram Sang]

[-- Attachment #1: Type: text/plain, Size: 1649 bytes --]

On Wed, Apr 01, 2015 at 02:17:47PM +0200, Geert Uytterhoeven wrote:
> Hi Wolfram,
> 
> On Mon, Mar 23, 2015 at 9:26 AM, Wolfram Sang <wsa@the-dreams.de> wrote:
> > --- /dev/null
> > +++ b/Documentation/i2c/slave-interface
> 
> > +I2C slave events
> > +----------------
> > +
> > +The bus driver sends an event to the backend using the following function:
> > +
> > +       ret = i2c_slave_event(client, event, &val)
> > +
> > +'client' describes the i2c slave device. 'event' is one of the special event
> > +types described hereafter. 'val' holds an u8 value for the data byte to be
> > +read/written and is thus bidirectional. The pointer to val must always be
> > +provided even if val is not used for an event, i.e. don't use NULL here. 'ret'
> > +is the return value from the backend. Mandatory events must be provided by the
> > +bus drivers and must be checked for by backend drivers.
> > +
> > +Event types:
> > +
> > +* I2C_SLAVE_WRITE_REQUESTED (mandatory)
> > +
> > +'val': unused
> > +'ret': always 0
> > +
> > +Another I2C master wants to write data to us. This event should be sent once
> > +our own address and the write bit was detected. The data did not arrive yet, so
> > +there is nothing to process or return. Wakeup or initialization probably needs
> > +to be done, though.
> > +
> > +* I2C_SLAVE_READ_REQUESTED (mandatory)
> 
> I'm wondering whether these should be called I2C_SLAVE_READ_FIRST...

I considered that but decided against it. The difference to WRITE was
one reason. I think there was another I found when implementing the
update, but that one I can't recall right now :(


[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 819 bytes --]

Re: [PATCH v2 2/4] Documentation: i2c: describe the new slave mode

[Wolfram Sang]

[-- Attachment #1: Type: text/plain, Size: 1649 bytes --]

On Wed, Apr 01, 2015 at 02:17:47PM +0200, Geert Uytterhoeven wrote:
> Hi Wolfram,
> 
> On Mon, Mar 23, 2015 at 9:26 AM, Wolfram Sang <wsa@the-dreams.de> wrote:
> > --- /dev/null
> > +++ b/Documentation/i2c/slave-interface
> 
> > +I2C slave events
> > +----------------
> > +
> > +The bus driver sends an event to the backend using the following function:
> > +
> > +       ret = i2c_slave_event(client, event, &val)
> > +
> > +'client' describes the i2c slave device. 'event' is one of the special event
> > +types described hereafter. 'val' holds an u8 value for the data byte to be
> > +read/written and is thus bidirectional. The pointer to val must always be
> > +provided even if val is not used for an event, i.e. don't use NULL here. 'ret'
> > +is the return value from the backend. Mandatory events must be provided by the
> > +bus drivers and must be checked for by backend drivers.
> > +
> > +Event types:
> > +
> > +* I2C_SLAVE_WRITE_REQUESTED (mandatory)
> > +
> > +'val': unused
> > +'ret': always 0
> > +
> > +Another I2C master wants to write data to us. This event should be sent once
> > +our own address and the write bit was detected. The data did not arrive yet, so
> > +there is nothing to process or return. Wakeup or initialization probably needs
> > +to be done, though.
> > +
> > +* I2C_SLAVE_READ_REQUESTED (mandatory)
> 
> I'm wondering whether these should be called I2C_SLAVE_READ_FIRST...

I considered that but decided against it. The difference to WRITE was
one reason. I think there was another I found when implementing the
update, but that one I can't recall right now :(


[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 819 bytes --]