First step on SPI documentation #2725
Conversation
SpiMasterDevice differ, but as this PR is supposed to be just about comments, keep the inconsistency.
|
|
||
| ```rust | ||
| pub trait ControllerBus<'a>: ControllerDevice<'a> + ChipSelect { | ||
| fn init(&self) -> Result<(), ErrorCode>; |
There was a problem hiding this comment.
I know we had this discussion just last Friday, but it might make sense to be pedantic about it if we're formalizing it now: wouldn't we want to rather have this be enable and disable, such that one can switch between modes of underlying hardware? That's commonly supported and so I think we should expose it through this API for the advanced users.
The logic would be that a shared HW-device would need to have spi::ControllerBus::disable be called before something like uart::ControllerBus::enable can be called.
For HW which doesn't support deinitialization, we could just return an error on disable.
I'd like to avoid being able to "convert" a shared-HW device to a specific mode implicitly by calling init, without the need to uninitialize the old operating mode explicitly first.
There was a problem hiding this comment.
I'd argue that the case you're describing would be neither of these APIs: it would be an API which supports moving between controller and peripheral mode. init is intended to be a one-time operation that's done at boot. These traits are intended for a SPI bus being in dedicated controller mode or dedicated peripheral mode. The fact that there's a syscall driver capsule that uses both is a bit of a historical artifact (and as far as I can tell, almost never used).
There was a problem hiding this comment.
Okay, that's one way of looking at the problem. I was hoping if we were to have an enable/disable API we could have our cake and eat it too: it could allow us to both support switching device modes as in the USART example, as well as selectively power down components when they are not used. It'd both just be a disable away.
There was a problem hiding this comment.
You want to separate enable/disable from power; some components can have significant power-up times (generally for things like oscillators to settle), such that you want to distinguish power state transitions from functional capabilities.
|
One issue that came up while I was writing the UART TRD #2756 : SPI and the UART have different behavior when the passed length is longer than the buffer. The UART returns |
It used to be that the transfer length is the minimum of the buffer sizes and the len parameter. This changes it so if the len parameter is longer than one of the buffers, the call to read_write_bytes returns an `Err(SIZE)`. This is consistent with what the UART does.
|
I've updated the TRD based on the call today, so now |
|
@bradjc -- Let me know if these SPI comments are sufficient. If so, then I think this is ready. The TRD will involve further work after 2.0, this just starts to sketch what the APIs look like. |
|
bors r+ |
Pull Request Overview
This pull request updates the comments on
kernel::hil::spito document the current interface. It also adds a first draft for a SPI TRD, which has some significant changes to the interface. The first draft of the TRD is intended for starting the discussion towards defining a solid SPI API that follows modern Tock API design principles.Testing Strategy
This pull request was tested by compiling.
TODO or Help Wanted
This pull request needs feedback on the SPI comments and a start of discussion around the SPI TRD.
Documentation Updated
/docs, or no updates are required.Formatting
make prepush.