drivers: i2c: document "slave" API #27996
Conversation
pabigot
requested review from
albertofloyd,
franciscomunoz,
galak,
kgugala,
pgielda and
scottwcpg
as code owners
|
I don't think the "leader" and "follower" terminology makes sense in the i2c context -- the i2c target/device isn't "following" the leader in the same way that a main/replica database would do, for example. "i2c controller" or "i2c host" or "i2c initiator" and "i2c device" or "i2c target" seem like more appropriate terminology here, unless leader/follower has already gained significant use elsewhere. I think this is also consistent with some of the feedback on #27033. |
|
@olofj I've added #27033 (comment) to further explain why I'm using these terms. Please provide further feedback on the name selection in that PR. |
doc/reference/peripherals/i2c.rst
Outdated
| I2C | ||
| #### | ||
|
|
||
| Overview | ||
| ******** | ||
|
|
||
| .. note:: | ||
|
|
||
| Zephyr recognizes the need to change the racially-charged terms |
There was a problem hiding this comment.
IMO this type of note should be done in one place in the Zephyr documentation and not per peripheral.
We should probably consider splitting this PR and not mix a documentation bug fix with inclusive language changes that still being discussed. |
|
The documentation requires use of three distinguishing terms, currently "controller", "leader", and "follower". We can remove the explanation of why those terms are used if necessary. I would not be happy about being forced to change the documentation to continue to use "master" and "slave". |
making this change here and leaving i2c with slave/master usage especially in with the APIs still using slave/master in their function names is not going to make anyone happy. Once we know and agree on what terms we should be using this should be done across the tree, not only for the "slave". |
|
At this time no changes have been requested, just comments that express opinions about the use of "leader" and "follower". My opinion differs, or I'd have done something else. My detailed responses are at/around #27033 (comment). Here I would still like reviews related to the technical content, so we can move forward on documenting this API. |
|
Can we move this forward based on the discussion we had 2 weeks ago re inclusive language please? |
|
Waiting on this action item for the decision on how Zephyr will be addressing non-inclusive language.
|
@MaureenHelm any updates? |
Working on a PR now. |
pabigot
force-pushed
the
nordic/20200902d
branch
from
c5640f2
to
c4279aa
Compare
github-actions
bot
added
the
area: Tests
pabigot
removed
platform: Microchip MEC
pabigot
dismissed stale reviews from scottwcpg, franciscomunoz, and carlescufi
content changed to conform to current Zephyr coding guidelines
pabigot
changed the title
Documentation for subsystems that use offensive terms by standard may need to reference this section as justification for their continued and new use. Signed-off-by: Peter Bigot <[email protected]>
Status of addressing inclusive language concerns is embedded into the coding guidelines. Add a link to the corresponding issue for I2C. Signed-off-by: Peter Bigot <[email protected]>
Zephyr does not currently allow deviation from standard terminology for a technology even if it is non-inclusive, until the corresponding standards body has confirmed intent to change that terminology. The terms used in a previous attempt to be inclusive do not match the expected forthcoming standard terms. Revert to standard terms until the new ones have been announced and the switch made throughout Zephyr. Signed-off-by: Peter Bigot <[email protected]>
The callback pointers for uninitiated operations are implicitly null; making them explicit only confuses maintainers searching for drivers that implement the API. Signed-off-by: Peter Bigot <[email protected]>
The I2C slave API has been present since 1.12 but lacked documentation on the behavior of its functions. Provide that, and revise existing documentation to make clear the type and mode of the device passed to each API call. Documented behavior is derived primarily from the LPC11U6X implementation, as the STM32 implementation generally ignores return values. Signed-off-by: Peter Bigot <[email protected]>
Although the master API is stable, the slave API has never been documented and has only two in-tree implementations with no uses outside of a single test application. It is marked experimental in this commit. Signed-off-by: Peter Bigot <[email protected]>
pabigot
force-pushed
the
nordic/20200902d
branch
from
c4279aa
to
b4e4e88
Compare
|
isnt this a documentation change? Why should this not go into 2.5? |
|
If you want it there, sure. I was cleaning up the PRs I'd wanted to get in to this version, and this wasn't specifically one of them because of the delay in getting the policy in place. Feel free to add it back if you intend to merge it. |
|
Ah, my mistake, I thought this was a milestone I'd assigned. Back now. |
Document the API used for I2C slave devices. Fill out the peripheral documentation with a reference to the I2C specification, a short summary of the roles of I2C devices, and a note on language used. Remove some stubs from drivers that don't implement the slave API. The focus of the PR is documenting the existing following API, not documenting the I2C subsystem as a whole.
The PR includes a change that distinguishes the slave API as Experimental in the API stability table, as it is not satisfactory and has limited support. See also #27675.
The documented behavior is derived primarily from the LPC11U6X implementation, as the STM32 implementation generally ignores return values. There may be errors in the description, and there are certainly gaps in the existing driver implementations.
Updated 2021-02-06 to revert to "master/slave" terminology in conformance to the coding guidelines.
Fixes #27879
References #27033