463: embedded-hal: digital: add #[inline] hints for PinState functions r=Dirbaio a=luojia65
Add inline hints for:
- `<PinState as Not>::not`
- `<PinState as From<bool>>::from`
- `<bool as From<PinState>>::from`
Those hints would allow further optimizations if PinState structure functions is used on embedded-hal projects.
Co-authored-by: Luo Jia / Zhouqi Jiang <luojia@hust.edu.cn>
Add inline hints for:
- <PinState as Not>::not
- <PinState as From<bool>>::from
- <bool as From<PinState>>::from
Those hints would allow further optimizations if PinState structure functions is used on embedded-hal projects.
Signed-off-by: Zhouqi Jiang <luojia@hust.edu.cn>
461: spi: remove write-only and read-only traits. r=Dirbaio a=Dirbaio
When introducing the Bus/Device split in #351, I kept the ability to represent "read-only" and "write-only" buses, with separate `SpiBusRead`, `SpiBusWrite` buses. This didn't have much discussion, as it was the logical consequence of keeping the separation in the already existing traits (`Read`, `Write`, `Transfer`, ...).
Later, in #443, when switching from the closure-based API to the operation-slice-based API, this required adding `SpiDeviceRead`, `SpiDeviceWrite` as well, because you can no longer put a bound on the underlying bus with the new API.
This means we now have *seven* traits, which we can reduce to *two* if we drop the distinction. So, is the distinction worth it?
I've always been on the fence about it, now I'm sort of leaning towards no.
First, using write-only or read-only SPI is rare.
- write-only SPI: for SPI displays you don't want to read from, or to abuse it to bitbang stuff like ws2812b,
- read-only SPI: some ADCs that can't be configured at all, you just clock out bits. Or even weirder abuses, like to build a logic analyzer
Second, for it to be useful HALs have to track "read-onlyness / write-onlyness" in the type signature, so a read-only SPI really only implements `SpiBusRead` and not `SpiBus`. HALs already have enough generics. For example, Embassy HALs don't implement the distinction (you can create MOSI-only or MISO-only SPIs, but they all impl the full `SpiBus`, because I didn't want to make the types carry pin information).
Third, it makes the API easier to use. Simpler, users only have to import one trait, docs have all the methods in one place. Much less boilerplate to impl the traits (look at how shorter `embedded-hal-bus` gets!).
So I think we should remove them.
Co-authored-by: Dario Nieuwenhuis <dirbaio@dirbaio.net>
458: bus: Add a doc example for i2c::RefCellDevice r=Dirbaio a=tomgilligan
`embedded-hal-bus` is turning out to be very useful for something I'm working on. It wasn't too hard to work out how to use it but it feels like an example would still be helpful here. Not sure:
- is this the best place to put such an example?
- how much of the example should be hidden with `#`?
Co-authored-by: Thomas Gilligan <thomas.gilligan@icloud.com>
448: Misc doc fixes. r=eldruin a=Dirbaio
- Switch from GAT to AFIT has already happened.
- We're no longer planning to integrate EHA into EH
- Fix all broken links.
Co-authored-by: Dario Nieuwenhuis <dirbaio@dirbaio.net>
445: bus/i2c: add RefCell, CriticalSection and Mutex shared bus implementations. r=eldruin a=Dirbaio
Requires #440
Same as #443 but for I2C.
This adds a few bus sharing implementations, with varying tradeoffs:
- `RefCellDevice`: single thread only
- `CriticalSectionDevice`: thread-safe, coarse locking, nostd.
- `MutexDevice`: thread-safe, fine-grained locking, std only.
Co-authored-by: Dario Nieuwenhuis <dirbaio@dirbaio.net>
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>
442: async/serial: add Write. r=eldruin a=Dirbaio
Extracted out of #349
This is just `Write`, mirroring the blocking version. so it should hopefully be uncontroversial.
Co-authored-by: Dario Nieuwenhuis <dirbaio@dirbaio.net>
430: Add PWM SetDuty trait. r=therealprof a=Dirbaio
This adds back a version of the 0.2 trait `PwmPin`.
cc #358
WG meeting [chatlog](https://matrix.to/#/!BHcierreUuwCMxVqOf:matrix.org/$_4DVnptWkGRjvW7-5Y6qCQZvj8oi9t4tbt8v4hXxJak?via=matrix.org&via=psion.agg.io&via=tchncs.de)
Differences to 0.2:
- `enable()` and `disable()` are gone. I think they were underspecified (for example, is the pin high or low when disabled?), and not very useful in practice. Disabling can be achieved already by setting duty to 0% or 100%. If the HAL cares about power consumption, it can transparently disable the timer and set the pin to fixed high/low when duty is 0% or 100%.
- Duty is no longer an unconstrained associated type. `u16` has been chosen because it gives enough dynamic range without being too big. `u8` might give too little dynamic range for some applications, `u32` might be annoyingly big for smaller archs like AVR/MSP430.
- Range is `0..u16::MAX` instead of `0..get_max_duty()`. This makes the HAL instead of the user responsible for the scaling, which makes using the trait easier. Also, if the HAL wants to optimize for performance, it can set the hardware period to be a power of 2, so scaling is just a bit shift.
- Name is `SetDuty` instead of `PwmPin`, because we might have a `SetFrequency` or similar in the future.
- I haven't included `get_duty()`, because I think in practice most drivers don't need it, and implementing it in HALs is annoying. They either have to read it back from hardware and unscaling it (losing precision), or storing the unscaled value in `self` (wasting RAM). We could add a `GetDuty` or `StatefulSetDuty` in the future if it turns out this is wanted, but I hope it won't be.
Co-authored-by: Dario Nieuwenhuis <dirbaio@dirbaio.net>
Co-authored-by: Grant Miller <GrantM11235@gmail.com>
432: delay: make infallible. r=therealprof a=Dirbaio
1.0 alphas have been out for a while, some HALs out there implement it. I haven't seen one with an actual fallible delay.
I know the decision was made to make Delay fallible for consistency, but I think we should make one exception for just this one trait.
Co-authored-by: Dario Nieuwenhuis <dirbaio@dirbaio.net>
439: Use github action dtolnay/rust-toolchain@master instead of actions-rs r=Dirbaio a=jannic
actions-rs/toolchain@v1 uses deprecated features and has not been updated for years
Co-authored-by: Jan Niehusmann <jan@gondor.com>
431: gpio: add ErrorKind. r=Dirbaio a=Dirbaio
This adds an `ErrorKind` to the GPIO `Error` associated type, just like all the other drivers. It has just a single `Other` variant for now.
The reason to have it is future-proofness: Even if we don't have ideas for ErrorKind variants for now, we might have them in the future.
- If we have `ErrorKind`, we can add more variants in the future backwards-compatibly after the 1.0 launch, thanks to `ErrorKind` being marked `#[non_exhaustive]`.
- If we *don't* have `ErrorKind`, adding it in the future would be a breaking change, because HALs would have to add support for it.
Co-authored-by: Dario Nieuwenhuis <dirbaio@dirbaio.net>
438: Bump MSRV to 1.59, switch to Edition 2021. Fix CI. r=therealprof a=Dirbaio
Bump MSRV to 1.59, switch to Edition 2021.
Fixes CI, It broke due to yanking `cortex-m-rt 0.71` due to the stack align bug.
~~I don't think the MSRV should matter for `dev-dependencies`? They're only required for running tests, bumping it doesn't affect crates using `embedded-hal` as a regular dep.~~ of course *out* CI requires it, duh.
Co-authored-by: Dario Nieuwenhuis <dirbaio@dirbaio.net>
