Understanding the Raspberry Pi – FreeBSD gpio device
Recently I found myself wanting to understand how I2C for FreeBSD ARM, on the Pi works. The first step is to understand the GPIO implementation on Pi, since on a Pi, I2C is implemented on the GPIO.
So, here's the basic summary.
Firstly, the FreeBSD source browser is here.
In the directory /sys/ is the kernel code for all platforms, and in /sys/sys/ is the core kernel code. In /sys/sys/gpio.h, you'll find the header which declares the GPIO API for FreeBSD, which must be supported by all FreeBSD GPIO devices on all platforms.
Here's the important parts:
/* GPIO pin states */
#define GPIO_PIN_LOW 0x00 /* low level (logical 0) */
#define GPIO_PIN_HIGH 0x01 /* high level (logical 1) */
/* Max name length of a pin */
#define GPIOMAXNAME 64
/* GPIO pin configuration flags */
#define GPIO_PIN_INPUT 0x0001 /* input direction */
#define GPIO_PIN_OUTPUT 0x0002 /* output direction */
#define GPIO_PIN_OPENDRAIN 0x0004 /* open-drain output */
#define GPIO_PIN_PUSHPULL 0x0008 /* push-pull output */
#define GPIO_PIN_TRISTATE 0x0010 /* output disabled */
#define GPIO_PIN_PULLUP 0x0020 /* internal pull-up enabled */
#define GPIO_PIN_PULLDOWN 0x0040 /* internal pull-down enabled */
#define GPIO_PIN_INVIN 0x0080 /* invert input */
#define GPIO_PIN_INVOUT 0x0100 /* invert output */
#define GPIO_PIN_PULSATE 0x0200 /* pulsate in hardware */
struct gpio_pin {
uint32_t gp_pin; /* pin number */
char gp_name[GPIOMAXNAME]; /* human-readable name */
uint32_t gp_caps; /* capabilities */
uint32_t gp_flags; /* current flags */
};
/* GPIO pin request (read/write/toggle) */
struct gpio_req {
uint32_t gp_pin; /* pin number */
uint32_t gp_value; /* value */
};
/*
* ioctls
*/
#define GPIOMAXPIN _IOR('G', 0, int)
#define GPIOGETCONFIG _IOWR('G', 1, struct gpio_pin)
#define GPIOSETCONFIG _IOW('G', 2, struct gpio_pin)
#define GPIOGET _IOWR('G', 3, struct gpio_req)
#define GPIOSET _IOW('G', 4, struct gpio_req)
#define GPIOTOGGLE _IOWR('G', 5, struct gpio_req)
So, this defines what a GPIO device looks like to FreeBSD and the ioctls it supports, on all platforms.
For the ARM kernel, the source code is in /sys/arm/, and for Raspberry Pi, which based on a Broadcom BCM 2835 chip the kernel sources are at /sys/arm/broadcom/bcm2835/.
In /sys/arm/broadcom/bcm2835/bcm2835_gpio.c, you'll find the implementation which exposes the GPIO device, for a Raspberry Pi. You should notice that the header "gpio_if.h" is included. This is a generated file, and the source is in /sys/dev/gpio_if.m. The important parts of this are here:
INTERFACE gpio;
#
# Get total number of pins
#
METHOD int pin_max {
device_t dev;
int *npins;
};
#
# Set value of pin specifed by pin_num
#
METHOD int pin_set {
device_t dev;
uint32_t pin_num;
uint32_t pin_value;
};
#
# Get value of pin specifed by pin_num
#
METHOD int pin_get {
device_t dev;
uint32_t pin_num;
uint32_t *pin_value;
};
#
# Toggle value of pin specifed by pin_num
#
METHOD int pin_toggle {
device_t dev;
uint32_t pin_num;
};
#
# Get pin capabilities
#
METHOD int pin_getcaps {
device_t dev;
uint32_t pin_num;
uint32_t *caps;
};
#
# Get pin flags
#
METHOD int pin_getflags {
device_t dev;
uint32_t pin_num;
uint32_t *flags;
};
#
# Get pin name
#
METHOD int pin_getname {
device_t dev;
uint32_t pin_num;
char *name;
};
#
# Set current configuration and capabilities
#
METHOD int pin_setflags {
device_t dev;
uint32_t pin_num;
uint32_t flags;
};
An important piece of code to notice in "bcm2835_gpio.c" is the device driver method "probe":
static int
bcm_gpio_probe(device_t dev)
{
if (!ofw_bus_is_compatible(dev, "broadcom,bcm2835-gpio"))
return (ENXIO);
device_set_desc(dev, "BCM2708/2835 GPIO controller");
return (BUS_PROBE_DEFAULT);
}
This is the method FreeBSD calls to ask the driver if a specific piece of hardware is appropriate for that driver. The ARM GPIO driver looks for "broadcom,bcm2835-gpio", which is the exact name defined in the Raspberry Pi FDT.
Another method which if the "attach" method, which initializes the driver and adds it to the bus. This line gets a "bcm_gpio_softc" struct from the device_t passed by the kernel. The method "device_get_softc" is forward declared in /sys/sys/bus.h, and implemented in /sys/kern/subr_bus.c
struct bcm_gpio_softc *sc = device_get_softc(dev);
This method initializes a mutex for the driver:
mtx_init(&sc->sc_mtx, "bcm gpio", "gpio", MTX_DEF);
These macros
#define BCM_GPIO_LOCK(_sc) mtx_lock(&_sc->sc_mtx) #define BCM_GPIO_UNLOCK(_sc) mtx_unlock(&_sc->sc_mtx) #define BCM_GPIO_LOCK_ASSERT(_sc) mtx_assert(&_sc->sc_mtx, MA_OWNED)
Are used to serialize access in certain methods in the driver.
These lines allocate memory and IRQs for the driver, as specified in the FTD:
rid = 0;
sc->sc_mem_res = bus_alloc_resource_any(dev, SYS_RES_MEMORY, &rid,
RF_ACTIVE);
if (!sc->sc_mem_res) {
device_printf(dev, "cannot allocate memory window\n");
return (ENXIO);
}
sc->sc_bst = rman_get_bustag(sc->sc_mem_res);
sc->sc_bsh = rman_get_bushandle(sc->sc_mem_res);
rid = 0;
sc->sc_irq_res = bus_alloc_resource_any(dev, SYS_RES_IRQ, &rid,
RF_ACTIVE);
if (!sc->sc_irq_res) {
bus_release_resource(dev, SYS_RES_MEMORY, 0, sc->sc_mem_res);
device_printf(dev, "cannot allocate interrupt\n");
return (ENXIO);
}
These lines query the Open Firmware and verify the that device is indeed a GPIO controller, according to the FTD:
/* Find our node. */ gpio = ofw_bus_get_node(sc->sc_dev); if (!OF_hasprop(gpio, "gpio-controller")) /* Node is not a GPIO controller. */ goto fail;
These lines set up the initial state of the GPIO controller pins:
if (bcm_gpio_get_reserved_pins(sc) == -1)
goto fail;
/* Initialize the software controlled pins. */
for (i = 0, j = 0; j < BCM_GPIO_PINS - 1; j++) {
if (bcm_gpio_pin_is_ro(sc, j))
continue;
snprintf(sc->sc_gpio_pins[i].gp_name, GPIOMAXNAME,
"pin %d", j);
func = bcm_gpio_get_function(sc, j);
sc->sc_gpio_pins[i].gp_pin = j;
sc->sc_gpio_pins[i].gp_caps = BCM_GPIO_DEFAULT_CAPS;
sc->sc_gpio_pins[i].gp_flags = bcm_gpio_func_flag(func);
i++;
}
sc->sc_gpio_npins = i;
bcm_gpio_sysctl_init(sc);
Finally, these lines add two devices "gpioc" and "gpiocbus", and then attach the dev to the main bus
device_add_child(dev, "gpioc", device_get_unit(dev)); device_add_child(dev, "gpiobus", device_get_unit(dev)); return (bus_generic_attach(dev));
The function "device_add_child" is implemented in /sys/kern/subr_bus.c. The devices "gpio" and "gpioc" are generic devices, which work for all architectures, and they are in:
/sys/dev/gpio/gpioc.c and /sys/dev/gpio/gpiobus.c. The reason the kernel is able to find them by their device class names "gpio" and "gpiobus" is because they are registered with the kernel via these lines of code in gpioc.c and gpiobus.c.
driver_t gpioc_driver = {
"gpioc",
gpioc_methods,
sizeof(struct gpioc_softc)
};
devclass_t gpioc_devclass;
DRIVER_MODULE(gpioc, gpio, gpioc_driver, gpioc_devclass, 0, 0);
MODULE_VERSION(gpioc, 1);
driver_t gpiobus_driver = {
"gpiobus",
gpiobus_methods,
sizeof(struct gpiobus_softc)
};
devclass_t gpiobus_devclass;
DRIVER_MODULE(gpiobus, gpio, gpiobus_driver, gpiobus_devclass, 0, 0);
MODULE_VERSION(gpiobus, 1);
The gpio driver which will finally appear on the Pi as "/dev/gpio0", includes the header system header "/sys/gpio.h" and implements all its methods via that API, which ultimately comes back to /sys/arm/broadcom/bcm2835/bcm2835_gpio.c.