Capemgr

This page contains information on Capemgr, an in-kernel mechanism for dynamically loading Device Tree fragments from userspace.

= About =

Capemgr was created out of a need for boards like the BeagleBone to be able to detect installed expansion boards at boot time and allocate appropriate resources (load drivers, allocate GPIO, reserve bus addresses, etc) on kernels which use Device Tree. Traditionally, a Device Tree was a static file (or set of files) which described a machine (often an Embedded SoC and the board it's installed on). This of course is not able to support dynamically changing hardware, such as the BeagleBone and its add-on capes.

Further, it is one of the goals of the BeagleBone to allow 3rd parties to create their own capes and to allow users to install and use these capes without re-compiling the kernel.

A key feature of Capemgr is the ability to load Device Tree fragments as overlays to the existing Device Tree at runtime. On the BeagleBone, each cape has a Device Tree fragment which describes it.

= Implementation =

Capemgr is completely implemented in the kernel. There is no userspace component. Since the BeagleBone runs best with a kernel which is downstream from mainline, the Capemgr implementation is currently located in the BeagleBone kernel patch set at https://github.com/beagleboard/kernel/tree/3.8 and https://github.com/beagleboard/kernel/tree/4.1.

In the BeagleBone kernel, cape Device Tree fragments are located in. Each cape is represented by a single DTS (Device Tree Source) fragment file. At kernel build time, these fragments are compiled by the Device Tree Compiler into dtbo files (Device Tree Blob Object). At install time, these dtbo objects are copied to.

Each BeagleBone capes has an EEPROM on SPI bus 0 which contains information about the cape. The format of the data in the EEPROM is described in the System Reference Manual (SRM). The Board Name EEPROM field is used by Capemgr to determine which cape fragment to load. There are two ways this board name can be used. The first method is that the Board Name can be mapped in the BeagleBone's main Device Tree Source file to a filename using a structure like the following:

/* mrf24j40 cape */ cape@10 { part-number = "BB-BONE-MRF24J40"; version@00A0 { version = "00A0"; dtbo = "cape-bone-mrf24j40-00A0.dtbo"; };                   };

The above DT snippet maps the device named BB-BONE-MRF24J40 version 00A0 to the file

Alternatively, if there is no mapping in the main DTS file, the Capemgr loader will attempt to load a filename which matches the Board Name and Version fields in the EEPROM. For example, for a board named BB-BONE-LCD7-01 with version 00A2, the Capemgr loader will try to load. This way capes can be added to a system without modifying the BeagleBone's main Device Tree.

Loading a Fragment at Runtime
Capemgr provides a sysfs interface to load Device Tree fragments at runtime. contains information and controls for the Capemgr system. To manually load a DTBO fragment, one can run:

echo BB-BONE-MRF24J40 >/sys/devices/bone_capemgr.7/slots

The above command will cause Capemgr to act as though a device with a Board Name of BB-BONE-MRF24J40 was detected. It will then check if there is a mapping in  and load the appropriate dtbo file from. If not, it will attempt to load  as described in the above section.

One can also specify a version number on the command line:

echo BB-BONE-MRF24J40:00A1 >/sys/devices/bone_capemgr.7/slots

This will attempt to load revision 00A1, first using the mapping in, and then trying to load.

Compiling a DTS Fragment Outside the kernel build
On a BeagleBone, with the default Angstrom image, use the  compiler located at   to compile Device Tree sources into DTBO Device Tree objects without modifying any kernel source. The resulting dtbo can be manually copied into.

More on compilation can be read here.

= Updates =


 * Post on LKML against 4.1: https://lkml.org/lkml/2015/5/13/157
 * Some of the traffic regarding the 4.1 kernel with capemgr on the Beagle list:
 * TESTERS WANTED: beaglebone's cape manager - http://beagleboard.org/Community/Forums?place=msg%2Fbeagleboard%2FT5bjaKxH99c%2FQGyUZ64h6YIJ
 * 4.1 repo - http://beagleboard.org/Community/Forums?place=msg%2Fbeagleboard%2FTMGEWjBLsok%2FStLZ7lvUmRYJ
 * cape-universal & 4.1.x = default.. ;) - http://beagleboard.org/Community/Forums?place=msg%2Fbeagleboard%2F2D5Pz3r7ZZ8%2Fmlcb4xMQNYkJ
 * v4.1.x + overlay migration notes... - https://github.com/adafruit/adafruit-beaglebone-io-python/issues/80
 * Installing the 4.1 kernel with CapeMgr support: http://elinux.org/Beagleboard:BeagleBoneBlack_Debian#4.1.x_BeagleBone.2FBeagleBone_Black