Beagleboard:BeagleBone cape interface spec

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

= LEDs =

Bone LED pin uses gpio-leds driver and allows users to easily create compatible led nodes in overlays for BBBWL, BBB, and BBAI. For the definitions, you can see bbai-bone-buses.dtsi#L16 & bbb-bone-buses.dtsi#L16.

= I2C =

I2C bone bus nodes allow creating compatible overlays for BBBWl, BBB, & BBAI. 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 BBBWl, BBB, & BBAI. 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 BBBWl, BBB, & BBAI. 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 BBBWl, BBB, & BBAI. For the definitions, you can see bbai-bone-buses.dtsi#L440 & bbb-bone-buses.dtsi#L457.

= ADC = Work needs to be done to create these symlinks as well as handle major differences in the driver used for the ADC. Maybe just have the "okay" in here and more in the base tree?

/dev/bone/adc/n
https://github.com/beagleboard/bb.org-overlays/blob/master/src/arm/BB-ADC-00A0.dts
 * 0 - AM3358 in_voltage0_raw, AM5729 in_voltage0_raw
 * 1 - AM3358 in_voltage1_raw, AM5729 in_voltage1_raw
 * 2 - AM3358 in_voltage2_raw, AM5729 in_voltage3_raw
 * 3 - AM3358 in_voltage3_raw, AM5729 in_voltage2_raw
 * 4 - AM3358 in_voltage4_raw, AM5729 in_voltage7_raw
 * 5 - AM3358 in_voltage5_raw, AM5729 in_voltage6_raw
 * 6 - AM3358 in_voltage6_raw, AM5729 in_voltage4_raw

= PWM = PWM bone bus nodes allow creating compatible overlays for BBBWl, BBB, & BBAI. For the definitions, you can see bbai-bone-buses.dtsi#L415 & bbb-bone-buses.dtsi#L432

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

= ECAP =

/dev/bone/ecap/1
TODO AM3358 N/A AM5729 eCAP1_in_PWM1_out
 * P8.15

/dev/bone/ecap/2
TODO AM3358 N/A AM5729 eCAP2_in_PWM2_out
 * P8.14

/dev/bone/ecap/3
TODO AM3358 N/A AM5729 eCAP3_in_PWM3_out
 * P8.04

= MMC =

/dev/bone/mmc/2
TODO: need overlay. Note: On Black, this is used by the on-board eMMC. On AI, these pins are available. AM3358 MMC2 AM5729 MMC3
 * P8.21 - CLK
 * P8.20 - CMD
 * P8.25 - DAT0
 * P8.24 - DAT1
 * P8.5 - DAT2
 * P8.6 - DAT3
 * P8.23 - DAT4
 * P8.22 - DAT5
 * P8.4 - DAT7
 * P8.3 - DAT6

= LCD = TODO

= eQEP =

/dev/bone/eqep/0
https://github.com/beagleboard/bb.org-overlays/blob/master/src/arm/bone_eqep0-00A0.dts AM3358 eQEP0 AM5729 eQEP3
 * P9.42 - A
 * P9.27 - B
 * P9.25 - STROBE (N/A on AI)
 * P9.41 - INDEX (N/A on AI)
 * P8.6 - STROBE (N/A on AM3358)
 * P8.5 - INDEX (N/A on AM3358)

/dev/bone/eqep/1
https://github.com/beagleboard/bb.org-overlays/blob/master/src/arm/bone_eqep1-00A0.dts AM3358 eQEP1 AM5729 eQEP1
 * P8.34 - A
 * P8.36 - B
 * P9.21 - STROBE (N/A on AM3358)

/dev/bone/eqep/2
https://github.com/beagleboard/bb.org-overlays/blob/master/src/arm/bone_eqep2b-00A0.dts AM3358 eQEP2 AM5729 eQEP2
 * P8.12 - A
 * P8.11 - B
 * P8.15 - STROBE on AM3358 only
 * P8.18 - STROBE on AM5729 only
 * P8.16 - INDEX on AM3358 only
 * P9.15 - INDEX on AM5729 only

/dev/bone/eqep/2a
https://github.com/beagleboard/bb.org-overlays/blob/master/src/arm/bone_eqep2-00A0.dts AM3358 eQEP2 AM5729 ''N/A'
 * P8.41 - A
 * P8.42 - B
 * P8.40 - STROBE
 * P8.39 - INDEX

= McASP = TODO

= 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/bone/pru/0.0 (eCAP)
Not sure where to put this as it doesn't really have it's own Linux control interface, just an overlay. TODO: provide overlay, since it is a different pinctrl mode. AM3358 PRUSS AM5729 PRUSS1
 * P8.15

/dev/bone/pru/0.0
TODO AM3358 PRU0 AM5729 PRUSS1, PRU0

/dev/bone/pru/0.1
TODO AM3358 PRU1 AM5279 PRUSS1, PRU1

/dev/bone/pru/1.0
TODO AM3358 N/A AM5729 PRUSS2, PRU0
 * P8.3 - I/O 10 (N/A on AM3358)
 * P8.4 - I/O 11 (N/A on AM3358)
 * P8.5 - I/O 5 (N/A on AM3358)
 * P8.6 - I/O 7 (N/A on AM3358)
 * P8.8 - I/O 20 (N/A on AM3358)

/dev/bone/pru/1.1
TODO AM3358 N/A AM5729 PRUSS2, PRU1
 * P8.7 - I/O 16 (N/A on AM3358)
 * P8.9 - I/O 6 (N/A on AM3358)
 * P8.10 - I/O 15 (N/A on AM3358)

= 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 =