Add dummy GPIO pins

[eldruin]

This is an implementation of #141 to get the ball rolling.
I put everything into a single DummyPin since the level can be put into a typestate for zero cost and then it can be used for cases where the requirement is InputPin + OutputPin.
Alternatives:

• Separate DummyOutputPin, DummyInputPin, DummyStatefulOutputPin.
• Accept a bool on creation time for a DummyInputPin and DummyStatefulOutputPin.

[rust-highfive]

r? @therealprof

(rust_highfive has picked a reviewer for you, use r? to override)

[therealprof]

As usual is missing a CHANGELOG entry.

I think this is nice addition in general which we should take in.

[eldruin]

I added a changelog entry now, albeit quite short.

[therealprof]

Works for me. Let's wait a bit whether @ryankurte has any concerns.

[eldruin]

I mentioned that it is zero-cost and improved the documentation a bit now. Sorry for the re-review.

[therealprof]

No worries, looks even better now. 🎉

[ryankurte]

hmm i am not so convinced by this approach, it would seem to me to introduce ambiguity that is better expressed via the type system (which does perhaps require more exploration and documentation).

as an example, if a driver can use a pin but does not require it, i believe it should be implemented over both conditions in the manner that is correct for the device, rather than via a dummy pin that the driver cannot be aware of. i have an example of this planned, but, haven’t yet had a chance to implement it...

for the mentioned SPI case i believe further work is required to accurately represent and abstract over transactions and busses with managed or unmanaged CS pins (#180).

[therealprof]

rather than via a dummy pin that the driver cannot be aware of

Why would the application need to be aware of a dummy pin? In the end it's always the user who needs to decide how to wire the hardware and how to configure it.

We do have dummy pins of the required type/implementing the required traits pretty in pretty much any HAL impl which is okay but not great. The larger issue here is that in generic drivers you cannot make use those so either you require the user to provide the correct types or implement the dummy pin themselves. I think having these here provides a nice and coherent addition to the traits which might also be useful to write tests, etc.

[dbrgn]

Looks useful to me. Some docs-only nitpicking below.

[ryankurte]

i wrote a whole thing but i don't have the time / energy to edit it and the majority of the issues are already raised by the author in #141. the cliff-notes follow, i apologise if it comes off as brisk but it's what i can manage at the moment 🙃

• optional pins should be represented in the driver API
  • providing an unexpected dummypin to a driver violates the driver type constraints
  • designing drivers in this manner precludes compile or run-time decisions about pin availability (eg. use of optional IRQs if they are available)
  • in pretty much all existing drivers, an application providing a dummy pin would break the driver in unpredictable and difficult to debug ways, especially where the CS pin is involved
• this stated issue already be expressed in a type-safe manner
  • via Option<T> (as detailed in Add built-in no-op implementations for GPIO #141, though still requiring a dummy type)
  • via trait defaults and specialisation over type constraints
  • both approaches (as with all the driver-author-tricks) really need to be documented

i am uncomfortable with the current PR as it would appear to me that the issues with this approach raised in #141 are not adequately addressed, and that there are better mechanisms to represent this without providing a blessed approach to functionally violate the driver type constraints. i would really like to see more discussion of the possible approaches and limitations of each in #141 before landing this (or similar), but my current feeling is:

• if the issue is providing a type for use instantiating drivers that take an Option<T> there is no need for the dummy pin type to be instantiable and calling any methods could cause a panic
  • this seems to me to address Add built-in no-op implementations for GPIO #141, be less surprising, and brings the scope back to application use rather than impacting driver authors (who see only Some or None)
  • i think this would be a good candidate for inclusion here
• if there is a clear reason to need this to be instantiable, then it is expressly being provided to violate type constraints which imo should be justified and treated as such
  • construction should be marked as unsafe, documentation should be full of warnings and should not suggest use as except for very specific situations this will break the driver
  • this is unfortunately incompatible with causing a fault if it were used in an Option<T> then actually called :-(
  • i am unsure whether this would be better located here or in a third party crate

[therealprof]

We discussed this controversely in todays meeting and opinons are wildly varying. It doesn't seem like we can easily find a solution which pleases everyone. Unnominating for now but we need to find a good way to resolve such deadlocks in the future.

[eldruin]

Alright, I put this implementation into its own crate: dummy-pin so that people that are interested can use it (compatible with embedded-hal 0.2 as of version 0.1).
I would suggest moving the discussion about a "blessed" approach back to #141. Sorry for the annoyance.
@ryankurte Would you be able to put your thoughts there as well?