- Feature Name: new_peripheral_communication
- Start Date: 2018-10-14
- RFC PR: (leave this empty)
- Rust Issue: (leave this empty)
Here we propose a new interface which allows thread-safe sharing of a single I2C or SPI bus by moving ownership and control of this bus from device driver to a bus master. This includes device selection (address or enable line) and bus frequency. This keeps driver implementation simple, removing the need to select/deselect devices in the driver code.
This propoisition allows both forward and backward compatibility while the ecosystem transitions to the new interface. It also outlines where implementation responsibility lays.
This does not handle DMA or Interrupt-driven communication.
Currently, Rust Embedded's i2c and spi interfaces do now allow sharing those busses between different drivers as the bus' ownership is passed into the driver. As these busses are designed for mutliple client devices this limits the HAL's usefulness in real-world designs. Also, the lack of agreement on how device selection should be done with regard to SPI enable lines has created a fracture in the driver space for those who believe the device should control its enable line and those who believe the driver should handle this.
With the proposed design, we should be able to track and control usage of any multi-client bus across multiple threads, drivers, and baud rates. Ideally a 20 year old EEPROM operating at 100Kbps and temperature sensor operating at 400KHz should be able to use the same i2c bus without making concessions for one another. Also, device drivers and consumers will have a standard interface to implement against regarless of the bus in use.
Explain the proposal as if it was already included in the language and you were teaching it to another Rust programmer. That generally means:
- Introducing new named concepts.
- Explaining the feature largely in terms of examples.
- Explaining how Rust programmers should think about the feature, and how it should impact the way they use Rust. It should explain the impact as concretely as possible.
- If applicable, provide sample error messages, deprecation warnings, or migration guidance.
- If applicable, describe the differences between teaching this to existing Rust programmers and new Rust programmers.
For implementation-oriented RFCs (e.g. for compiler internals), this section should focus on how compiler contributors should think about the change, and give examples of its concrete impact. For policy RFCs, this section should provide an example-driven introduction to the policy, and explain its impact in concrete terms.
This is the technical portion of the RFC. Explain the design in sufficient detail that:
- Its interaction with other features is clear.
- It is reasonably clear how the feature would be implemented.
- Corner cases are dissected by example.
The section should return to the examples given in the previous section, and explain more fully how the detailed proposal makes those examples work.
/// Allows abstracting away how users reference the bus. Ex: Linux uses dev tree or ACPI
trait Bus {
};
/// Sends messages, provides a mutex for safety.
trait BusMaster<T> {
fn new<T>(Bus) -> Result<BusProxy<T>, BusError>;
};
trait BusProxy<T> {
/// Transfer a collection of transactions
fn transfer(&[[Message]]) -> Result<(), BusError>;
};
/// Represents what we want to do with buffers to send to device. These
/// are collected into an array considered a transaction.
trait Message<T> {
fn send(&[u8]); // Half-duplex
fn recv(&mut [u8]); // Half-duplex
fn tx(&[u8], &mut [u8]); // Full-duplex
// Sizes much match or one must be `None`. If full duplex, `None` will create
// an empty backing buffer. If half duplex with two `Some`s, compile time error.
fn custom(Option<&[u8]>, Option<&mut [u8]>, Params)
};
/// Implemented on a per-bus basis. Does this need to be bus-specific?
trait Params {
no_start() -> bool;
no_end() -> bool;
};
/// What could possibly go wrong?!
trait BusError<T> {
reason() -> ErrorReason,
message() -> &core::str
}
/// Different possible problems
enum ErrorReason {
Access
}- Why is this design the best in the space of possible designs?
- What other designs have been considered and what is the rationale for not choosing them?
- What is the impact of not doing this?
Discuss prior art, both the good and the bad, in relation to this proposal. A few examples of what this can include are:
- For language, library, cargo, tools, and compiler proposals: Does this feature exist in other programming languages and what experience have their community had?
- For community proposals: Is this done by some other community and what were their experiences with it?
- For other teams: What lessons can we learn from what other communities have done here?
- Papers: Are there any published papers or great posts that discuss this? If you have some relevant papers to refer to, this can serve as a more detailed theoretical background.
This section is intended to encourage you as an author to think about the lessons from other languages, provide readers of your RFC with a fuller picture. If there is no prior art, that is fine - your ideas are interesting to us whether they are brand new or if it is an adaptation from other languages.
Note that while precedent set by other languages is some motivation, it does not on its own motivate an RFC. Please also take into consideration that rust sometimes intentionally diverges from common language features.
- What parts of the design do you expect to resolve through the RFC process before this gets merged?
- What parts of the design do you expect to resolve through the implementation of this feature before stabilization?
- What related issues do you consider out of scope for this RFC that could be addressed in the future independently of the solution that comes out of this RFC?