Discussion for config-pin C-API

beaglebone-pinmux.h

/* -*- mode: c; c-basic-offset: 8; indent-tabs-mode: nil; -*- */
/* Pinmux setting working in conjuction with the universal cape */

/* [[
 * Comments in here in [[ double square brackets ]] are meta comments useful
 * while working on a review of this API.
 *
 * Note, this _only_ addresses pinmux configuration, not anything how to write
 * or read bits on GPIOs etc. This is left up to the application (I usually just
 * memory map the proper regions in code or PRU, but there are many different
 * ways including writing to device-paths).
 *
 * So this is a separate can of worms explicitly a non-goal of this API.
 *
 * ]]
 */

#ifndef BEAGLEBONE_PINMUX_H
#define BEAGLEBONE_PINMUX_H

#ifdef __cplusplus
extern "C" {
#endif

#include <stdint.h>

/* The different types of physical header configurations. */

/* [[ This should have good names that are also not too specific
 *    (e.g. BEAGLEBONE_BLACK would not cover Beaglebone Green. ]]
 */
enum BeagleboneHeaderConfiguration {
        BEAGLEBONE_NONE,  /* This is not a supported Beaglebone. */
        /* [[ the old white Beaglebone, what was the configuration there ? ]] */
        BEAGLEBONE_2x46,  /* Beaglebone Black, Green etc. Headers P8, P9 */
        BEAGLEBONE_2x36,  /* Pocketbeagle; Headers P1, P2 */
        BEAGLEBONE_BLUE,  /* Various headers [[hopefully they have names?]] */
};

enum BeaglebonePinType {
        PIN_TYPE_GPIO_IN,
        PIN_TYPE_GPIO_OUT,
        PIN_TYPE_PRU_IN,
        PIN_TYPE_PRU_OUT,
        PIN_TYPE_PWM,
        PIN_TYPE_TIMER,
        PIN_TYPE_ANALOG_IN,
        PIN_TYPE_QEP,
        PIN_TYPE_CAN,
        PIN_TYPE_SPI,
        PIN_TYPE_SPI_CS,
        PIN_TYPE_I2C,
        PIN_TYPE_UART,
        /* [[ what else ? ]]
           [[ Do we need qualifications ? Is it ever possible to have
           e.g. either GPIO 12 or 21 on a pin, so that we'd need to
           qualify which GPIO ? Similar: can a single pin be either part
           of SPI_0 or SPI_1 ? ]] */
};

/* Optional mods for */
enum BeaglebonePinModifier {
        PIN_MOD_NONE = 0,
        PIN_MOD_PULL_UP = 1,
        PIN_MOD_PULL_DOWN = 2,
        PIN_MOD_DRIVE_HIGH = 4,
        PIN_MOD_DRIVE_LOW = 8,
        /* [[ there are probably others, such as slow rise ? ]] */
};

/* Result of the configuration call */
enum BeaglebonePinConfigResult {
        PIN_CONFIG_SUCCESS,
        PIN_CONFIG_INVALID_HEADER,  /* unknown header number on this BB     */
        PIN_CONFIG_INVALID_PIN,     /* unknown pin number on this BB header */
        PIN_CONFIG_INVALID_TYPE,    /* Pin cannot be conf'd to this type    */
        PIN_CONFIG_INVALID_MOD,     /* Invalid modification or combo.       */
};

/* Utility function: Return the header configuration of the currently
 * running beaglebone. This helps to decide which headers and pins are
 * available.
 */
enum BeagleboneHeaderConfiguration bb_discover_header_config(void);

/* Configure pin on beaglebone. The configuration might fail if you attempt
 * to configure a pin that is not valid on the beaglebone this is running
 * on. For instance: valid header numbers for the Beaglebone Black are 8 or 9,
 * while on the Pocketbeagle it is 1 or 2.
 *
 * "header_number" is the number of the header on this Beaglebone as shown
 *                 on the silk screen.
 * "pin"           The pin number on the given header. See silk-screen for
 *                 guidance which is pin 1.
 *
 * [[ Instead of the header + pin thing, should we have some defines such
 *    as BB_P8_13 defines (as it is often done) that essentially just refers
 *    to the internal numbering of the Sitara and then do the pinmapping from
 *    there ? this requires however, that different Beagleboards have disjoint
 *    sets of pins, which looks like it is at least true currently with
 *    P8, P9 (BBB) vs P1, P2 (Pocketbeagle) prefix
 *
 *    It would require some set of #defines or enums in the global namespace
 *    though.
 * ]]
 *
 * "type"          The functional type this pin should be configured to. For
 *                 each pin, there is only a subset available.
 * "pin_mode" is a bit-ored combination of BeaglebonePinModifier.
 *
 * [[ Instead of type + pin_mode, should we just have them OR-ed together ?
 *    PIN_TYPE_GPIO_IN | PIN_MOD_PULL_UP
 *    This is shorter to write, but also muddies the type-safetey and clarity ]]
 */
enum BeaglebonePinConfigResult bb_config_pin(int header_number, int pin,
                                             enum BeaglebonePinType type,
                                             uint32_t pin_mods);

#ifdef __cplusplus
}
#endif

#endif /* BEAGLEBONE_PINMUX_H */

to answer a question in line 55: apparently, some pins can be qualified. Like this change shows: P9.28 can be pinmuxed to two different PWMs
beagleboard/bb.org-overlays@6925979#diff-8c06097db3e81f863e4f63cb4f4bac43
So we might need a PIN_TYPE_PWM2 (and then the first should be named PIN_TYPE_PWM1. Maybe 0 and 1 ?)