Beagleboard:BeagleBone cape interface spec

''See the blog post on BeagleBoard.org for an introduction. ''

This is a list of symlink interfaces based on BeagleBone Cape header pins.

Below, when mentioning "Black", this is true for all AM3358-based BeagleBone boards. "AI" is AM5729-based. "AI-64" is TDA4VM-based.

= Overall =


 * A: ADC
 * C: CAN
 * D: Digital GPIO
 * E: EHRPWM
 * I: I2C
 * L: LCD
 * M: MMC/SDIO
 * P: PRU
 * Q: eQEP
 * S: SPI
 * U: UART

= LEDs =

The compatibility layer comes with simple reference nodes for attaching LEDs to any gpio pin. The format followed for these nodes is led_P8_## / led_P9_##. The gpio-leds driver is used by these reference nodes internally and allows users to easily create compatible led nodes in overlays for Black, AI and AI-64. For the definitions, you can see bbai-bone-buses.dtsi#L16 & bbb-bone-buses.dtsi#L16.

Definitions
= I2C =

Compatibility layer provides simple I2C bone bus nodes for creating compatible overlays for Black, AI and AI-64. The format followed for these nodes is bone_i2c_#. For the definitions, you can see bbai-bone-buses.dtsi#L388 & bbb-bone-buses.dtsi#L403.

= SPI = SPI bone bus nodes allow creating compatible overlays for Black, AI and AI-64. For the definitions, you can see bbai-bone-buses.dtsi#L406 & bbb-bone-buses.dtsi#L423.

= UART = UART bone bus nodes allow creating compatible overlays for Black, AI and AI-64. For the definitions, you can see bbai-bone-buses.dtsi#L367 & bbb-bone-buses.dtsi#L382.

= CAN = CAN bone bus nodes allow creating compatible overlays for Black, AI and AI-64. For the definitions, you can see bbai-bone-buses.dtsi#L440 & bbb-bone-buses.dtsi#L457.

= ADC =


 * TODO: We need a udev rule to make sure the ADC shows up at /dev/bone/adc! There's nothing for sure that IIO devices will show up in the same place.
 * TODO: I think we can also create symlinks for each channel based on which device is there, such that we can do /dev/bone/adc/Px_y

= PWM = PWM bone bus nodes allow creating compatible overlays for Black, AI and AI-64. For the definitions, you can see bbai-bone-buses.dtsi#L415 & bbb-bone-buses.dtsi#L432

If the PWM devices are not yet enabled on your board, follow these instructions to add the device tree overlay to your system.

= TIMER PWM= TIMER PWM bone bus uses ti,omap-dmtimer-pwm driver, and timer nodes that allow creating compatible overlays for Black, AI and AI-64. For the timer node definitions, you can see bbai-bone-buses.dtsi#L449 & bbb-bone-buses.dtsi#L466.

= eCAP =


 * 1) TODO: This doesn't include any abstraction yet.

= eMMC =

= LCD =

= eQEP =

On BeagleBone's without an eQEP on specific pins, consider using the PRU to perform a software counter function.

= McASP =

= PRU = The overlay situation for PRUs is a bit more complex than with other peripherals. The mechanism for loading, starting and stopping the PRUs can go through either UIO or RemoteProc.


 * /dev/remoteproc/prussX-coreY (AM3358 X = "", other x = "1|2")

= GPIO = TODO For each of the pins with a GPIO, there should be a symlink that comes from the names

= Methodology = The methodology for applied in the kernel and software images to expose the software interfaces is to be documented here. The most fundamental elements are the device tree entries, including overlays, and udev rules.

10-of-symlink.rules
ATTR{device/of_node/symlink}!="", \ ENV{OF_SYMLINK}="%s{device/of_node/symlink}"
 * 1) From: https://github.com/mvduin/py-uio/blob/master/etc/udev/rules.d/10-of-symlink.rules
 * 2) allow declaring a symlink for a device in DT

ENV{OF_SYMLINK}!="", ENV{DEVNAME}!="", \ SYMLINK+="%E{OF_SYMLINK}", \ TAG+="systemd", ENV{SYSTEMD_ALIAS}+="/dev/%E{OF_SYMLINK}"

TBD
SUBSYSTEM=="gpio", ACTION=="add", TEST=="value", ATTR{label}!="sysfs", \ RUN+="/bin/mkdir -p /dev/bone/gpio", \ RUN+="/bin/ln -sT '/sys/class/gpio/%k' /dev/bone/gpio/%s{label}"
 * 1) Also courtesy of mvduin
 * 2) create symlinks for gpios exported to sysfs by DT

= Verification = TODO: The steps used to verify all of these configurations is to be documented here. It will serve to document what has been tested, how to reproduce the configurations, and how to verify each major triannual release. All faults will be documented in the issue tracker.

= References =