search

rust-embedded / embedded-hal

A Hardware Abstraction Layer (HAL) for embedded systems
Apache License 2.0
2.01k stars 202 forks source link

Update the I2C documentation to use "controller/target" instead of "master/slave" #626

Open emshotton opened 2 months ago

emshotton commented 2 months ago

This brings the language in-line with Rev. 7.0 of the 2C-bus specification and user manual .

Dirbaio commented 2 months ago

I'm not convinced we should do this. As unfortunate as the master/slave names are, today the vast majority of microcontroller and i2c slave/target chips datasheets still use the master/slave terms. IMO the main goal of documentation is explaining to the user how to use the API, and making the user "mentally translate" between two sets of names when reading datasheets and our docs doesn't help that.

Also the controller/target names aren't universally agreed on either. There's also controller/peripheral (recommended by the OSHWA for SPI, but i've also seen it used for i2c), and I think I've also seen initiator/target somewhere too.

This was also discussed a bit in the weekly meeting when https://github.com/rust-embedded/embedded-hal/pull/396 was proposed, the conclusion was to keep master/slave names, since as long as it's in just docs (not trait/function/type name) we can easily change them to other names if/when other names become more widely used.

emshotton commented 2 months ago

Thank you for the thoughtful reply and I want to acknowledge that naming things is a hard problem.

Interestingly the rp2040_hal uses a mix of language. It appears to use controller/peripheral when referring to the physical devices, and master/slave when referring to the devices addresses. The rp2040_pac uses master/slave when refering to the registers of the internal I2C device, but then the DW_apb_i2c IP block from Synopsys which appears to be the hardware implementation of i2c the rp2040 uses internally uses controller/target in it's public descriptions.

We are currently in a situation where there is already a range of competing terminology and confusion, and given that situation I'd argue that moving towards the language in the specification documentation that is being adopted by the hardware IP providers is a sensible move.

Personally I think it's important to move towards standardizing around this new terminology and the place individuals have agency to effect this change is in open source libraries such as this. I expect that the terminology used by IC manufactures will lag furthest behind, but will ultimately follow once changes to the spec and software libraries are made.

This change dosent include changes to the SPI terminology as I'm unfamiliar with the current state of naming conventions for that.

amanjeev commented 2 months ago

Personally I think it's important to move towards standardizing around this new terminology and the place individuals have agency to effect this change is in open source libraries such as this.

I second this. It will be nice to lead in this effort.