Peripheral drivers utilizing multiple GPIO need to be updated for consistency.

[jessebraham]

We are using a pin structs for UART, the builder pattern for SPI, and just taking raw pins for other peripherals. We really should be more consistent with our APIs so that things aren't confusing.

[AnthonyGrondin]

I also think there should be a way to easily use optional GPIO, without being required to put a type when using the None variant.

CC #814 (comment)

[bugadani]

I think there are two simultaneous issues here:

• how do we make multiple GPIO arguments easier to use? i.e. make it obvious which argument represents which signal
• how do we represent optional pins

I'm not entirely sure if everything needs to be covered with the same pattern, but I do agree that we have right now as many options as there are peripherals which isn't ideal. Below is a short summary of what I think of the two potential construction styles:

Builder pattern

• they can make a peripheral unbuildable until all required signals are set
• optional GPIOs don't show up as nondescript None values with dummy generics, at least not written by the user
• but: Using a builder, we either include required pins in the builder's constructor and go full circle when there are multiple required pins, or we use setter functions which don't make it obvious which pins are required.

Pin struct

Pin structs with optional fields also work but the user has to know about NO_PIN, which kind of defeats the purpose of the None variant of the enum IMO. On the other hand, it's obvious which pins are required (they aren't Options).

Hybrid option

There's the option to treat the "pin struct" as the initial value of the builder object. This is a bit complicated to implement, but:

• The struct could contain all required configuration
• Additional methods could transform it into a proper builder type for the optional setup options
• but: the code may look a bit weird compared to other Rust code. For example, this is how a hypothetical SPI construct may look like, where calling methods on an inline value object hurts my eyes a bit:

let spi = Spi {
   sclk: SomeSclkPin,
   mode: SpiMode::Mode0,
   clock_frequency: 50_u32.Mhz(),
}
.with_cs(ChipSelectPin)
.with_mosi(MosiPin)
.with_dma(...)
.build();

[bjoernQ]

There should be a way to exploit the type system to make sure non-optional pins are set 🤔 probably need some prototyping to find the best solution we want to go for. (Which is probably none of the pattern we currently have. Also e.g. PARL_IO is a bit special IIRC)

[bugadani]

There is a way to use the type system: a marker trait for "real" pins, then the builder method or whatever initializes the peripheral should only be implemented when the config struct's required pins are all marked with that trait.

PARL_IO has no required pins in the generic case, and should emulate the other interfaces (SPI, UART) via specialized constructors (and wrappers to make sure embedded-hal traits can be implemented for it)

[bjoernQ]

What I meant with special about PARL_IO is how the valid-signal pin is selected

Valid Signal Output of TX Unit
The TX unit can generate a valid signal aligned with TXD. Configure PARL_IO_TX_HW_VALID_EN to choose
whether to output it to TXD. The polarity of the valid signal is fixed to active high.
The valid output function is disabled by default. When enabled, the output valid signal occupies the MSB of the
TXD, which means that no matter what the original value is, the 15th bit of TXD remains high and is output as the
valid signal. However, the valid signal pin does not affect the bus width configuration. For example, if user
configures data bus width as 1 bit, the valid output function can still be enabled with a fixed pin as TXD[15] while
the data pin is TXD[0].

[MabezDev]

I believe all the APIs have been updated now? Please re-open if I am mistaken.