Add typestate-based control over the PIO RX buffer access

[horazont]

Fixes #935.

Open Questions:

• StateMachine::clear_fifos is probably not sound with a non-FIFO RX buffer. It is not fully clear according to the reference manual though.

  The reference manual states that enabling the PUT/GET modes will cause the joining (which clear_fifos uses) to be disabled, but it doesn't say what happens if you enable joining while in non-FIFO mode.

  My proposal to fix this is to move the clear_fifos method onto the Rx<_> struct and constrain it to only be available in RxFifo mode.

  The other option would be to actually carry the RxFifoConfig type state through to the StateMachine to hide the clear_fifos method in such cases. That can probably be done, but has implications on the state machine groups (which will also have to carry that typestate).

  I can do either variant, but I'd like a judgement call from the maintainers on which way to go here.

TODOs:

• I will add an example which uses this feature later, as well as fix the existing example. Fixed example and added my original LED matrix code as another example.

[jannic]

StateMachine::clear_fifos is probably not sound with a non-FIFO RX buffer. It is not fully clear according to the reference manual though.

I propose to find out what actually happens in that case. Either experimentally or by asking the Raspberry engineers.
My guess would be that clear_fifos only clears the FIFO pointers, and not the memory cells. Rationale: When used as FIFO, the actually memory contents are irrelevant when the FIFO pointers say that the FIFO is empty. And the datasheet states "the data returned by reading from an empty FIFO is undefined". Therefore, why waste hardware resources to clear the memory cells?

If that's true, then our clear_fifos method is not unsound in PUT/GET modes. Instead, it just has no observable effect. In that case, I would not change the code at all. Maybe add an explanation to the docs.