Implement digital module

[eggroll-bot]

Create a digital module in the HAL to provide a GPIO interface.

[MelonShooter]

GPIO Design:

We have 4 GPIO ports labelled GPIO0-GPIO3. GPIO3 is different from the rest of the GPIO ports b/c it has very limited configurations and is located in a different register block. Additionally, each GPIO port has a certain number of pins they control. Start reading from page 109 of the chip user guide for details.

On a high level, our goals are

• pins should only be able to be accessed by 1 thing at a time to ensure coherency of GPIO pin state
• create an API that uses Rust's type system to prevent misuse, such as attempting to write to the pin's value when the pin is in one of the input modes.

To meet these goals, the API will be designed as such:

Each GPIO port will be modelled with a struct called GpioPort<Metadata: GpioPortMetadata + ?Sized, const PIN_CT: usize>. This struct will be responsible for handing out handles to GPIO pins within the port through a function called get_pin_handle in such a way where only one handle can be acquired for a GPIO pin at a time, ensuring that only one portion of code can read or modify the pin state at a time. When a handle is dropped, get_pin_handle can be used again to acquire the pin. If the pin already has a handle taken for it, the function errors.

The first generic parameter of GpioPort is a type that implements GpioPortMetadata. The GpioPortMetadata trait contains associated types that are used in implementing the handle system. Two such structs implement these traits: CommonGpio and LowPowerGpio, defining the types to use when creating new handles and what type allows access to the GPIO registers. CommonGpio is the metadata struct used for GPIO0-GPIO2 while LowPowerGpio is the one used for GPIO3 because the registers available on this port are different from the rest, necessitating a different handle type.

The second generic parameter is a constant representing how many pins are on the port.

The above solves the first goal listed above. To meet the second goal, we will be using the embedded_hal crate's traits listed here to create a strong pin API.

Our handle for GPIO0-GPIO2 is called CommonPinHandle and for GPIO3 it's LowPowerPinHandle. These handles will implement IoPin from embedded HAL, where the input pin and output pins will be newtypes (see this for what a newtype is) carrying the same fields as the pin handle, each with their own functions based on the allowed operations.

For the CommonPin API, we're looking to implement the following

• input/output mode setting (be able to get and modify this),
• input pin reading,
• output pin reading/writing
• weak/strong pullup/pulldown resistor configuration (in input mode),
• drive strength and power supply (in output mode)
• limited interrupt support (only input mode, see below)
• alternate function support (see 6.4.4 in the chip user guide -- this is too complex to make type-safe on compile time, if the pin is not in the right mode, we can throw an error on runtime instead, so this should be fallible -- in the future we can make this a compile-time check which will require a breaking API change b/c of pin index becoming compile time)

For the LowPowerPin API, we just need

• input/output mode setting (be able to get and modify this),
• input pin reading,
• output pin reading/writing
• pullup resistor configuration (in input mode?),
• alternate functions

We will implement limited interrupt support for now with the ability to set a listener on state change per pin (for GPIO0-2) -- see 6.5.1 of the chip user guide for details -- note that this function would be unsafe where the safety contract is that the listener is interrupt safe. Interrupts only apply when pin is in input mode.

We will ignore wakeup registers for now.

TODO after PeripheralManager is done:
Implement Peripheral trait along with applicable Toggleable* traits on GPIO0-3 structs

[MelonShooter]

TODO actions after #21:

• Further unify pin handle interfaces by making PinHandle require IoPin. Will require a decent amount of work to refactor this.
• Add more tests
• Add better documentation, needs more examples, especially with alternate functions
• Add interrupt support GPIO