SPI API is too cleverly complex for its own good

Currently the SPI API sports read, write, and exchange operations. The exchange operation reads from one buffer and writes to another. It currently allows those buffers to be different lengths, kind of, sometimes -- I think the written buffer can be shorter than the read buffer but not necessarily vice versa? And the fact that read and write can technically be described in terms of exchange means that clever programmers (mostly me) have tried to implement the former in terms of the latter?

Anyway, long story short, the resulting driver state machine is too complex for my liking and I want to rewrite it. We've found and fixed a number of subtle bugs, and created new subtle bugs in the process.

I am totally open to changing the API during this process.

Start by tracing the SPI API's read, write, and exchange operations through the driver state machine described in the issue. Clarify the intended buffer-length rules and revised API, then verify that the redesign addresses the subtle state-machine bugs without relying on exchange to implement read or write.