Capemgr keeps track of the BeagleBone Black's expansion boards, known as capes

Controlling Capemgr

When booting a BBB system without any capes attached, many of the pins available via the P8 and P9 connectors are already allocated for specific purposes, because some pins are physically wired to specific lines on the board, and some are muxed by the device tree. Figure 2 shows which pins are already allocated and the signals that are available on them. Some of the used pins provide power or addressing signals that can't be muxed differently to serve a different purpose. Other pins in use belong to the built-in capes (e.g., eMMC, HDMI) that are detected and configured via dynamically applied overlays at boot.

Figure 2: Pins in use by default on the BeagleBone Black.

But, how are the capes attached to the BBB identified, and what part of the kernel loads the device tree overlays for those capes? Most importantly, how can you control this behavior? The answer to all of these questions is the Capemgr subsystem of the kernel. Capemgr is responsible for detecting any capes connected to the BBB and handling requests that load overlays.

Capemgr exposes its userspace interface through the /sys/devices/bone_capemgr.* directory via the sysfs filesystem. The slots file within this directory is used to interact with Capemgr. When Capemgr loads an overlay, it allocates the overlay to a "slot" within Capemgr. To determine which Capemgr slots currently contain an overlay, cat out the slots file. For a BBB in a default configuration without any capes connected, the slots output looks like Listing 2.

Listing 2

slots Output

user@beaglebone:~#  cd /sys/devices/bone_capemgr.*
user@beaglebone:/sys/devices/bone_capemgr.8# cat slots
0: 54:PF---
1: 55:PF---
2: 56:PF---
3: 57:PF---
4: ff:P-O-L Bone-LT-eMMC-2G,00A0,Texas Instrument,BB-BONE-EMMC-2G
5: ff:P-O-L Bone-Black-HDMI,00A0,Texas Instrument,BB-BONELT-HDMI

Figure 3 identifies what each field of the slots output means. The slot number is used by Capemgr to identify what device tree overlays are currently loaded. The first four slots (0-3) are reserved for overlays associated with capes that have been physically plugged in to the BBB. The I2C bus address is a hexadecimal byte used by capes to request that the cape be placed in a particular slot.

Figure 3: The various fields of Capemgr slots output.

Overlays that are loaded and not associated with an attached cape board (e.g., those manually loaded from userspace or associated with the built-in HDMI and eMMC capes) will have a listed I2C bus address of ff.

The slot status describes the current state of the slot. For more information on the slot status field, see the "Understanding the Slot Status Field" box. The remaining fields are specified as properties within the device tree node for the overlay. They describe the name of the device, its version and manufacturer, and which overlay is associated with the hardware.

Understanding the Slot Status Field

The slot status field has five characters that describe the current state of a particular slot on the Capebus. Each character position in the slot status field represents a state that the slot is in and is either a letter (state is active) or a dash (state is not active). The five states are, from left to right in the slot status field, "P" (slot has been probed for a cape), "F" (probing failed for this slot), "O" (an override has placed the cape in this slot), "l" (cape is still being loaded), and "L" (cape loading has completed).

To load an overlay manually from userspace, the overlay must be a compiled .dtbo file that is located in the firmware directory of the root filesystem. The part number associated with the overlay (not the full file name of the .dtbo file) is echo'd into the slots file to load the overlay. The Capemgr will examine each .dtbo file within the firmware directory to find the overlay associated with that part number. If a .dtbo with that part number is found, that .dtbo file is loaded. For example, to load the overlay file MY_OVERLAY-00A0.dtbo, which is located in the firmware directory, use the following command:

user@beaglebone:~# sudo echo MY_OVERLAY > /sys/devices/bone_capemgr.*/slots

Three kernel command-line options control the behavior of Capemgr at boot. These options are passed to the kernel by specifying them within the U-Boot [5] bootloader's uEnv.txt configuration file. The first option is capemgr.enable_partno, which explicitly loads the overlay for one or more capes that have a specific Capebus slot allocated for them in the device tree.

The second option is capemgr.disable_partno, which forces Capemgr not to load an overlay for a cape that is physically present. The third is capemgr.extra_override, which is similar to capemgr.enable_partno but is used to load overlays for capes that do not have a specific Capebus slot allocated to them. Unless you know what you are doing, avoid using the extra_override option. You can potentially load an overlay into the wrong slot that way.

As an example, consider the BBB's built-in HDMI cape. The device tree specifies two nodes for this cape: one node for a "full HDMI cape" that provides both audio and video data (BB-BONELT-HDMI) and one node for a "video-only HDMI cape" that provides only video data (BB-BONELT-HDMIN). Each of these nodes references a different overlay.

Capemgr attempts to load both of these overlays automatically because the device tree nodes for the cape specifically request that both always be loaded during kernel boot. Because both of these overlays request exclusive usage of the same resource (the pins that provide the video signal), only one can be loaded at any time.

The full HDMI cape overlay is given a higher priority by the device tree, so Capemgr will attempt to load it first before loading the video-only HDMI overlay. If Capemgr successfully loads the full HDMI overlay, then its attempt to load the video-only HDMI overlay will fail.

It is sometimes desirable to use the video-only HDMI overlay, rather than the full HDMI overlay. For example, the four McASP0 pins that carry the audio signal in the full HDMI overlay can be muxed into an additional SPI channel (SPI1) or GPIO signals, which might be more important to a project than having HDMI audio. Because the full HDMI overlay always loads before the video-only HDMI overlay, Capemgr must be told to skip loading the full HDMI overlay. This is done by adding the following command-line option to your kernel:

capemgr.disable_partno=BB-BONELT-HDMI

To disable the HDMI cape completely by not loading either the full or the video-only HDMI overlays, add the following command-line option to your kernel:

capemgr.disable_partno=BB-BONELT-HDMI,BB-BONELT-HDMIN

By not loading both HDMI overlays, you completely disable the built-in HDMI cape, which frees up 24 pins on the P8 and P9 connectors that can now be muxed into a combination of UARTS and GPIOs. Note that disabling only BB-BONELT-HDMIN (the video-only HDMI overlay) will have no effect because the higher priority full HDMI overlay will still be loaded.

Conclusion

The device tree and Capemgr give you a great deal of control over the BBB when configuring the system for custom interfacing projects. Knowing which pins of the BBB are in use, and understanding how to change their usage to suit your needs, will help you make the best use of the platform for your specific project.

Infos

  1. TI Sitara AM335x Technical Reference Manual: http://www.ti.com/lit/ug/spruh73i/spruh73i.pdf
  2. BeagleBone Black system reference manual: https://github.com/CircuitCo/BeagleBone-Black/blob/master/BBB_SRM.pdf?raw=true
  3. Device tree data structure: http://www.devicetree.org
  4. Capemgr subsystem: http://elinux.org/Capemgr
  5. U-Boot bootloader: http://www.denx.de/wiki/U-Boot

Der Autor

Andrew Henderson is a doctoral candidate in the Electrical and Computer Engineering PhD program at Syracuse University (New York, USA). When not conducting research on computer security, he enjoys teaching the BeagleBone Black to perform new tricks. He has been developing Linux software professionally for both the desktop and embedded systems for more than 15 years.

Buy this article as PDF

Express-Checkout as PDF

Pages: 6

Price $2.95
(incl. VAT)

Buy Raspberry Pi Geek

SINGLE ISSUES
 
SUBSCRIPTIONS
 
TABLET & SMARTPHONE APPS
Get it on Google Play

US / Canada

Get it on Google Play

UK / Australia

Related content