| Message ID | 1426164123-8853-3-git-send-email-wsa@the-dreams.de (mailing list archive) |
|---|---|
| State | Superseded |
| Delegated to: | Geert Uytterhoeven |
| Headers | show |
On Thu, Mar 12, 2015 at 1:42 PM, Wolfram Sang <wsa@the-dreams.de> wrote: > --- /dev/null > +++ b/Documentation/i2c/slave-interface > @@ -0,0 +1,178 @@ > +Linux I2C slave interface description > +===================================== > + > +by Wolfram Sang <wsa@sang-engineering.com> in 2014-15 > + > +Finally, 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 EEPROM (to match [PATCH 3/3]) contents > +via sysfs and retrieve/provide information as needed. The software backend > +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 I2C specification is more loose on that. Most I2C controllers also the I2C specification > +automatically ACK when detecting its slave address, so there is no option to their slave addresses > +NACK it. For those reasons, this API does not support NACK in the address NACK them. > +phase. 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 -- To unsubscribe from this list: send the line "unsubscribe linux-sh" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Hello Wolfram, On Thu, Mar 12, 2015 at 01:42:02PM +0100, Wolfram Sang wrote: > From: Wolfram Sang <wsa+renesas@sang-engineering.com> > > Signed-off-by: Wolfram Sang <wsa+renesas@sang-engineering.com> > --- > Documentation/i2c/slave-interface | 178 ++++++++++++++++++++++++++++++++++++++ > Documentation/i2c/summary | 4 - > 2 files changed, 178 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..3df6c37191c86c > --- /dev/null > +++ b/Documentation/i2c/slave-interface > @@ -0,0 +1,178 @@ > +Linux I2C slave interface description > +===================================== > + > +by Wolfram Sang <wsa@sang-engineering.com> in 2014-15 > + > +Finally, Linux can also be an I2C slave in case I2C controllers have slave > +support. Besides this HW requirement, one also needs a software backend I wouldn't have written "Finally, ...". While it's great that we have slave support now, being enthusiastic here looks strange if someone reads it while slave support has become "normal". > +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, or use in-kernel mechanisms only, or something completely different: Or something self contained, so the userspace part is actually optional (but probably present most of the time). Another slave backend I have in mind is a bus-driver tester. That wouldn't necessarily need a userspace part. > + 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. s/this/the/ ? > + > + > +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. 'ret' is the return value from Does that mean that I have to pass a valid address, or can I use NULL, too? > +the backend. Mandatory events must be provided by the bus drivers and must be > +checked for by backend drivers. Currently all commands are mandatory. Does it make sense to mark the events accordingly already now? Do you expect the set of events to grow? > +* 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 or > +even has been put on the wires! Most hardware requests the next byte when the > +previous one is still to be shifted out to ensure seamless transmission. If the > +master stops reading after the previous byte, the next byte is never used. It > +probably needs to be sent again on the next I2C_SLAVE_READ_REQUEST, depending a > +bit on your backend. I didn't look into the actual implementation yet, but if I understand correctly a slave driver only sees I2C_SLAVE_READ_REQUESTED once and then only one I2C_SLAVE_READ_PROCESSED per byte, right? Does the slave driver gets noticed somehow if a previously requested byte doesn't make it on the wire? Otherwise you cannot correctly maintain e.g. the current read position of the eeprom driver, do you? (That's a bit like one of the problems with buffer support you pointed out further down.) > + > +* 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 to be able to receive new requests. While being obvious when you understood i2c, "reset its state" could be misleading. Only the transfer specific stuff should be reset. I expect the eeprom example to not reset the current position on STOP. Best regards Uwe
> > +Finally, Linux can also be an I2C slave in case I2C controllers have slave > > +support. Besides this HW requirement, one also needs a software backend > I wouldn't have written "Finally, ...". While it's great that we have > slave support now, being enthusiastic here looks strange if someone > reads it while slave support has become "normal". OK. > > +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, or use in-kernel mechanisms only, or something completely different: > Or something self contained, so the userspace part is actually optional > (but probably present most of the time). With "in-kernel mechanisms" I meant self-contained. Maybe "be in-kernel only"? > Another slave backend I have in mind is a bus-driver tester. That > wouldn't necessarily need a userspace part. Yes, I envisioned that, too. > > > + 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. > s/this/the/ ? Maybe. > > +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. 'ret' is the return value from > Does that mean that I have to pass a valid address, or can I use NULL, > too? Is NULL a valid pointer to val? > > +the backend. Mandatory events must be provided by the bus drivers and must be > > +checked for by backend drivers. > Currently all commands are mandatory. Does it make sense to mark the > events accordingly already now? Do you expect the set of events to > grow? Yes, support for general call address or device ids might be added somewhen. > > > +* 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 or > > +even has been put on the wires! Most hardware requests the next byte when the > > +previous one is still to be shifted out to ensure seamless transmission. If the > > +master stops reading after the previous byte, the next byte is never used. It > > +probably needs to be sent again on the next I2C_SLAVE_READ_REQUEST, depending a > > +bit on your backend. > I didn't look into the actual implementation yet, but if I understand > correctly a slave driver only sees I2C_SLAVE_READ_REQUESTED once and > then only one I2C_SLAVE_READ_PROCESSED per byte, right? Does the slave Right. > driver gets noticed somehow if a previously requested byte doesn't make > it on the wire? Otherwise you cannot correctly maintain e.g. the current Some HW can do this, but not all. That would maybe be another candidate for an optional event. Although, people should try hard to not need it. > read position of the eeprom driver, do you? (That's a bit like one of > the problems with buffer support you pointed out further down.) You need to assume that if the next byte is requested, the previous byte made it to the bus. So, you should do pre-increment in I2C_SLAVE_READ_PROCESSED, not post-increment. I didn't want to write this example so explicit because not all slave-backends will have a position pointer. And besides, it might make sense to extract the code for managing a position pointer from the slave-eeprom driver. Then, we'd have only one trusted implementation of EEPROM-alike behaviour and people can concentrate on reacting to reads/writes. > > +* 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 to be able to receive new requests. > While being obvious when you understood i2c, "reset its state" could be > misleading. Only the transfer specific stuff should be reset. I expect > the eeprom example to not reset the current position on STOP. OK. Being precise is better, I agree.
Hello Wolfram, On Fri, Mar 20, 2015 at 08:30:13AM +0100, Wolfram Sang wrote: > > > > +Finally, Linux can also be an I2C slave in case I2C controllers have slave > > > +support. Besides this HW requirement, one also needs a software backend > > I wouldn't have written "Finally, ...". While it's great that we have > > slave support now, being enthusiastic here looks strange if someone > > reads it while slave support has become "normal". > > OK. > > > > +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, or use in-kernel mechanisms only, or something completely different: > > Or something self contained, so the userspace part is actually optional > > (but probably present most of the time). > > With "in-kernel mechanisms" I meant self-contained. Maybe "be in-kernel > only"? I'm sure "in-kernel mechanisms" wasn't in the mail I replied to. (Hmm, or I must have missed that while reading.) > > Another slave backend I have in mind is a bus-driver tester. That > > wouldn't necessarily need a userspace part. > > Yes, I envisioned that, too. > > > > > > + 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. > > s/this/the/ ? > > Maybe. > > > > +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. 'ret' is the return value from > > Does that mean that I have to pass a valid address, or can I use NULL, > > too? > > Is NULL a valid pointer to val? NULL is a pointer and you didn't wrote about "valid" above. I just wondered if the necessity just comes from the fact that the function takes 3 parameters and so you have to give it 3 (this wouldn't needed to be pointed out IMHO) or if the value must be valid (then the wording isn't optimal). Is there a technical reason to require val to be valid? > > I didn't look into the actual implementation yet, but if I understand > > correctly a slave driver only sees I2C_SLAVE_READ_REQUESTED once and > > then only one I2C_SLAVE_READ_PROCESSED per byte, right? Does the slave > > Right. > > > driver gets noticed somehow if a previously requested byte doesn't make > > it on the wire? Otherwise you cannot correctly maintain e.g. the current > > Some HW can do this, but not all. That would maybe be another candidate > for an optional event. Although, people should try hard to not need it. > > > read position of the eeprom driver, do you? (That's a bit like one of > > the problems with buffer support you pointed out further down.) > > You need to assume that if the next byte is requested, the previous byte > made it to the bus. So, you should do pre-increment in > I2C_SLAVE_READ_PROCESSED, not post-increment. I didn't want to write This might be a correctness problem, right? If we cannot fix it (with the current slave abstraction) should this be pointed out somewhere; at least in the eeprom driver as this will probably be the reference for the next backend? > this example so explicit because not all slave-backends will have a > position pointer. And besides, it might make sense to extract the code for > managing a position pointer from the slave-eeprom driver. Then, we'd > have only one trusted implementation of EEPROM-alike behaviour and > people can concentrate on reacting to reads/writes. Best regards Uwe
On Fri, Mar 20, 2015 at 08:42:14AM +0100, Uwe Kleine-König wrote: > Hello Wolfram, > > On Fri, Mar 20, 2015 at 08:30:13AM +0100, Wolfram Sang wrote: > > > > > > +Finally, Linux can also be an I2C slave in case I2C controllers have slave > > > > +support. Besides this HW requirement, one also needs a software backend > > > I wouldn't have written "Finally, ...". While it's great that we have > > > slave support now, being enthusiastic here looks strange if someone > > > reads it while slave support has become "normal". > > > > OK. > > > > > > +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, or use in-kernel mechanisms only, or something completely different: > > > Or something self contained, so the userspace part is actually optional > > > (but probably present most of the time). > > > > With "in-kernel mechanisms" I meant self-contained. Maybe "be in-kernel > > only"? > I'm sure "in-kernel mechanisms" wasn't in the mail I replied to. (Hmm, > or I must have missed that while reading.) :) Still, I like "be in-kernel only" better, so I'll rephrase. > > > Does that mean that I have to pass a valid address, or can I use NULL, > > > too? > > > > Is NULL a valid pointer to val? > NULL is a pointer and you didn't wrote about "valid" above. I just But NULL is not a pointer to val. > wondered if the necessity just comes from the fact that the function > takes 3 parameters and so you have to give it 3 (this wouldn't needed to > be pointed out IMHO) or if the value must be valid (then the wording > isn't optimal). I'll try to rephrase. > Is there a technical reason to require val to be valid? Better be safe than sorry in case for future needs of 'val' I can't see now. > > You need to assume that if the next byte is requested, the previous byte > > made it to the bus. So, you should do pre-increment in > > I2C_SLAVE_READ_PROCESSED, not post-increment. I didn't want to write > This might be a correctness problem, right? If we cannot fix it (with > the current slave abstraction) should this be pointed out somewhere; at > least in the eeprom driver as this will probably be the reference for > the next backend? Adding some more info to the eeprom driver sounds good. Updating this paragraph with some infos from this discussion, too. Thanks, Wolfram
diff --git a/Documentation/i2c/slave-interface b/Documentation/i2c/slave-interface new file mode 100644 index 00000000000000..3df6c37191c86c --- /dev/null +++ b/Documentation/i2c/slave-interface @@ -0,0 +1,178 @@ +Linux I2C slave interface description +===================================== + +by Wolfram Sang <wsa@sang-engineering.com> in 2014-15 + +Finally, 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, or use in-kernel mechanisms 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. '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 or +even has been put on the wires! Most hardware requests the next byte when the +previous one is still to be shifted out to ensure seamless transmission. If the +master stops reading after the previous byte, the next byte is never used. It +probably needs to be sent again on the next I2C_SLAVE_READ_REQUEST, depending a +bit on your backend. + +* 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 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 I2C specification is more loose on that. Most I2C controllers also +automatically ACK when detecting its slave address, so there is no option to +NACK it. 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.