440: I2c: simplify, expand docs, document shared bus usage. r=eldruin a=Dirbaio
~Depends on #441 -- check that one out first.~
This does some simplifications to the trait that I think we should do:
- Implement all methods in terms of `transaction`. This way HALs have to implement just that.
- Removed byte-wise-iteration methods: `write_iter` and `write_iter_read`. The reason is that they're quite inefficient, especially with DMA implementations. We've already removed these on other traits, so I think we should do as well here.
- Removed `transaction_iter`. I don't think it's much useful in practice, because the way iterators work all the yielded `Operation`s must have the same lifetime. This means that, even if the user can generate the `Operation`s on the fly, they can't allocate buffers for these on the fly, all buffers must be pre-allocated. So it's not useful for, say, streaming a large transfer by reusing some small buffer repeatedly. See #367
- Removed useless lifetimes
- Standardized buffer names on `read` and `write`, I think they're clearer.
It also specifies how i2c bus sharing is supposed to work. This is an alternative to #392 . After the discussions there, I don't think we should split I2C into Bus and Device anymore. For SPI it makes sense, because drivers want to enforce that there's a CS pin (`SpiDevice`) or not (`SpiBus`). This is not the case with I2C, the API is exactly the same in the shared and non-shared case. Drivers shouldn't care which case it is.
So all we have to do to "support" bus sharing is docs, This PR does:
- Document that it's allowed for implementations to be either shared or not.
- Document some guidelines for drivers and HALs on how to best use the traits, expand the examples.
Co-authored-by: Dario Nieuwenhuis <dirbaio@dirbaio.net>
All dirvers out there assume the traitsare for master mode. However, there are some HALs
out there that impl the traits for SPI in slave mode, which will break when used with drivers.
(stm32f1xx-hal, stm32f4xx-hal, stm32l4xx-hal, probably more).
If we add SPI slave traits in the future, they should be a separate set of traits because the
API would look quite different:
- you'd want the API to give extra extra info about the transaction lengths: if you start a transfer with 256-byte buffer but the master only sends 10 bytes (sets CS low, sends 10 bytes, sets CS high),
you'd want `transfer` to return, saying "I got only 10 bytes", instead of hanging waiting for the other 246 bytes.
- The bus/device split doesn't make sense in slave mode.
Also IMO the `spi, spi_slave` naming is fine even if inconsistent, since the vast majority
of uses are master mode. I wouldn't name the `spi` module `spi_master`.
It is annoying to get hard errors while developing, it prevents testing things out
without documenting them because it fails the build.
This changes it to warn, which has the same effect in CI (because it already has `RUSTFLAGS: '--deny warnings'`),
but still allows buildilng.
