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 Operations must have the same lifetime. This means that, even if the user can generate the Operations 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.
~Depends on #441 -- check that one out first.~
This does some simplifications to the trait that I think we should do:
transaction
. This way HALs have to implement just that.write_iter
andwrite_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.transaction_iter
. I don't think it's much useful in practice, because the way iterators work all the yieldedOperation
s must have the same lifetime. This means that, even if the user can generate theOperation
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 #367read
andwrite
, 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: