GPIO Drive Strength Constants

[BrentK-ADI]

There looks to be discrepancies between different part datasheets as well as within code of what the values for GPIO drive strength represents.

The PBU support team confirmed the MAX32672 datasheet is correct, in that the drive strength is not a linear mapping between the bitfield and the actual current value.

It is recommended that the mxc_gpio_drvstr_t enum names be more in line with the actual values. From this:

typedef enum {
    MXC_GPIO_DRVSTR_0 = 0, /**< Drive Strength 0 */
    MXC_GPIO_DRVSTR_1, /**< Drive Strength 1 */
    MXC_GPIO_DRVSTR_2, /**< Drive Strength 2 */
    MXC_GPIO_DRVSTR_3, /**< Drive Strength 3 */
} mxc_gpio_drvstr_t;

To something like this:

typedef enum {
    MXC_GPIO_DRVSTR_1MA = 0, /**< Drive Strength 0 */
    MXC_GPIO_DRVSTR_4MA, /**< Drive Strength 1 */
    MXC_GPIO_DRVSTR_2MA, /**< Drive Strength 2 */
    MXC_GPIO_DRVSTR_6MA, /**< Drive Strength 3 */
} mxc_gpio_drvstr_t;

Other parts in the MAX32 family should be checked against the hardware implementation and against the datasheet. For example, the MAX32690 has this, which is 2mA and 4mA flipped from the MAX32672. Are both datasheets correct and the values are different, or is one erroneous?

[sihyung-maxim]

Yes, unfortunately, the naming for the GPIO Drive strengths is non-trivial and confusing with all the possible configurations.

TLDR >>: The current mxc_gpio_drvstr_t enum names represent what the GPIO_DS[2] registers are set to, not the increasing level of drive strength. The documentation will be fixed. <<

The 15 MCUs in the MSDK do not support the same set of drive strength values - such as cases like this. Even certain pins of an MCU won't follow the same set of drive strengths as the other pins on that same MCU. Not only that, the drive strengths of certain MCUs could also be inconsistent when the GPIO pin is in VDDIO or VDDIOH voltage setting (GPIO_VSSEL).

In short, there are many possible drive strength values that a pin can be set to (1mA,2mA,4mA,6mA,8mA,10mA), and each could need to set a different GPIO_DS[2] register value depending on the condition of the GPIO.

    MXC_GPIO_DRVSTR_1MA = 0,  // DS[2] = 0b00
    MXC_GPIO_DRVSTR_2MA,  // DS[2] = 0b01, or DS[2] = 0b00 for AF: I2C operation 
    MXC_GPIO_DRVSTR_4MA,  // DS[2] = 0b10, or this will be 8mA if pin is set to VDDIOH in some MCUs
    MXC_GPIO_DRVSTR_6MA,  // DS[2] = 0b11
    MXC_GPIO_DRVSTR_8MA,  // DS[2] = 0b11, or DS[2] = 0b10 if pin is set to VDDIOH in some MCUs, or DS[2] = 0b01 for AF: I2C operation
    MXC_GPIO_DRVSTR_10MA // DS[2] = 0b11, or DS[2] = 0b01 for AF: I2C operation

This is just an all-encompassing example of possible register configurations if we use the drive strength values for the enum names.

Ultimately, we settled with MXC_GPIO_DRVSTR_0, ... , MXC_GPIO_DRVSTR_3 to 1) prevent any confusion with setting the drive strength when you have more than 4 available options in the enum, 2) avoid code duplication, complexity, and bloat trying to handle all the different possible edge cases and conditions, and 3) simpler code support and maintainability across all 15 MCUs in the MSDK.

However, as you've pointed out though, it's not well documented to indicate that the enum names of mxc_gpio_drvstr_t represent the GPIO_DS[2] register setting and not the increasing level of the drive strength output. I'll fix the documentation on this.

Hope this explanation makes sense! It gets confusing quick when it comes to naming, so let me know if I need to clarify.

[Jake-Carter]

I think the PR helps a little bit, but still doesn't really address the root issue that we are not abstracting away this complexity from the user at all.

Yes, this is easier to maintain for us but it's almost a useless abstraction. Deciphering what drive strength 0 means is not a straightforward task for a user.

I agree that the top-level enum should be an actual current value. The role of the gpio_mexx.c file should be translating the current values to DS[2] values and handling these edge cases