At a glance, the CAT24C256 Electrically Erasable Programmable Read Only Memory (EEPROM) doesn't appear to add much value to the board. After all, the BeagleBone has a 2GB eMMC on the early revisions and a 4GB eMMC on revision C. An extra 256 kB of memory is hardly food scraps for the beagle. However, it serves a greater purpose; it's what enables automatic cape detection by the BBB.
The BBB has two 46 pin female expansion ports offering much more I/O capabilities than any other hobbyist board on the market. Certain pins can actually support eight different modes, mode 0 through mode 7. The mapping of pin features to a mode is known as pin muxing, short for pin multiplexing. To use a pin in a certain mode, the software must enable and configure this pin through the kernel's interface. This can be manually performed or scripted, but the easiest method is to use a BeagleBone cape.
During the kernel startup, the software will probe the I2C bus looking for cape EEPROMs. There are four valid addresses for Cape EEPROMs, 0x54 through 0x57. Therefore, the BBB supports up to four attached capes. The BBB will read the cape EEPROM, which must be programmed using the format in the BBB System Reference Manual (SRM). The BBB, using a software package called the capemgr, short for Cape Manager, will read the board name and revision from the Cape EEPROM. It will then try to match the name and revision to a compiled device tree fragment on your BBB. If there is a match, it will load that fragment.
Note
The latest production files for the BBB including the schematics and the SRM are located on the BBB wiki at http://elinux.org/Beagleboard:BeagleBoneBlack.
This automatic configuration provides two benefits. The first is that the pins on the BBB are automatically configured for a cape. The second is that the device tree can specify the kernel driver for the hardware on the cape, which means that the drivers for your hardware can be automatically loaded. The capemgr provides a plug-and-play like experience for embedded Linux.
If you are developing a BeagleBone cape, you should consider the process to have your cape supported in the BeagleBone images. This is a three-step process. First, you need to create a cape EEPROM file. This file should be written to your cape at manufacturing time. Second, you need to create a Device Tree Source (DTS) file, following the cape naming convention previously discussed, and submit a pull request on GitHub to BeagleBoard.org. Lastly, you need to create an eLinux wiki site discussing your cape. In the next sections, we'll briefly describe the software and hardware required to build a BeagleBone cape using the CryptoCape as an example.
If you have any semi-complicated hardware for the BeagleBone, you will benefit by adding a cape-compatible EEPROM. The essential reference to populating the EEPROM is the BeagleBone SRM's section on Cape Board Support. This section contains the EEPROM format. To jumpstart your EEPROM file creation, you can use a tool called the EEPROM cape generator available at: https://github.com/picoflamingo/BBCape_EEPROM. This tool with its simple command-line interface will provide the skeleton for your cape EEPROM. Currently, it does not completely implement the cape specification, so you must use a binary editor to set the remaining values of the EEPROM. The process to create the EEPROM binary involves reading through the SRM and writing the appropriate values, at the correct offsets, in a binary file.
You can view the CryptoCape's EEPROM by executing the following command as root:
cat /sys/bus/i2c/devices/1-0057/eeprom | hexdump -C
By default, the CryptoCape EEPROM is located at address 0x57 on the I2C bus. If you have multiple capes, you can change the address of the CryptoCape EEPROM by placing a solder jumper or solder blob on the A0 or A1 address pads next to the EEPROM. The results of reading the EEPROM with the previous command will produce the following:
00000000 aa 55 33 ee 41 31 42 42 2d 42 4f 4e 45 2d 43 52 |.U3.A1BB-BONE-CR| 00000010 59 50 54 4f 00 00 00 00 00 00 00 00 00 00 00 00 |YPTO............| 00000020 00 00 00 00 00 00 30 30 41 30 53 70 61 72 6b 46 |......00A0SparkF| 00000030 75 6e 00 00 00 00 00 00 00 00 42 42 2d 42 4f 4e |un........BB-BON| 00000040 45 2d 43 52 59 50 54 4f 00 00 00 11 32 30 31 34 |E-CRYPTO....2014| 00000050 30 30 30 30 30 30 30 30 00 00 00 00 00 00 00 00 |00000000........| 00000060 00 00 00 00 00 00 00 00 00 00 e0 73 e0 73 00 00 |...........s.s..| 00000070 00 00 00 00 00 00 00 00 00 00 00 00 a0 26 c0 06 |.............&..| 00000080 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| 00000090 00 00 a0 2f 00 00 00 00 00 00 c0 17 00 00 00 00 |.../............| 000000a0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| * 000000e0 00 00 00 00 00 00 00 00 00 00 00 00 01 f4 00 00 |................| 000000f0 00 00 00 00 47 50 47 20 46 69 6e 67 65 72 70 72 |....GPG Fingerpr| 00000100 69 6e 74 3a 20 30 78 42 35 39 31 39 42 31 41 43 |int: 0xB5919B1AC| 00000110 37 31 33 35 39 30 35 46 34 36 36 39 43 38 34 37 |7135905F4669C847| 00000120 42 46 41 35 30 33 31 42 44 32 45 44 45 41 36 0a |BFA5031BD2EDEA6.| 00000130 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff |................| * 00008000
If you walk through the SRM EEPROM data format, you should be able to match the fields with those in the CryptoCape EEPROM. The two most important fields are the Board Name, which starts at offset 6 and is 32 bytes in length and the Version, which starts at byte 38 and is 4 bytes in length. From the previous example, the board name is BB-BONE-CRYPTO and the version is 00A0. These two components are needed to name the DTS file in the next section. Starting at offset 244, the manufacturer can place any nonvolatile information. The CryptoCape contains the GNU Privacy Guard (GPG) fingerprint of the author's GPG public key, which is used to sign software packages and e-mail. In your cape, you could populate this with initial values for software or something similar.
Besides the EEPROM, you will also need to create a DTS file. This file defines attributes of your hardware to the Linux kernel. The DTS file for the CryptoCape Revision 00A0 is located on GitHub at: https://github.com/beagleboard/linux/blob/3.8/firmware/capes/BB-BONE-CRYPTO-00A0.dts. When creating a new DTS for your hardware, it's best to review the existing BeagleBone DTS files. With the growing number of capes, there is a good chance that there exists an approved DTS file with the hardware configuration you seek.
The BBB device tree overlay system is one of the areas undergoing active development, and important technical nuances change rapidly. If you need to build your own DTS file, it's best to check in with the BeagleBoard.org mailing list available at https://groups.google.com/forum/#!forum/beagleboard.
Note
A detailed introduction to the device tree system in the Linux kernel was presented by Thomas Petazzoni at the Embedded Linux Conference Europe in November 2013. The presentation is available on YouTube at https://www.youtube.com/watch?v=m_NyYEBxfn8.
Let's briefly look at a portion of the CryptoCape's DTS file. The capemgr will load the compiled version of this file to configure the hardware. The drivers for some of the chips on the CryptoCape are also loaded automatically since they are specified in the DTS file, as shown in the following code:
fragment@2 {
target = <&i2c2>;
__overlay__ {
#address-cells = <1>;
#size-cells = <0>;
/* Real Time Clock */
ds1307@68 {
compatible = "ds1307";
reg = <0x68>;
};
/* TPM */
tpm_i2c_atmel@29 {
compatible = "tpm_i2c_atmel";
reg = <0x29>;
};
};
};The previous code snippet loads two kernel drivers for two devices on the I2C bus. The first is the RTC at address 0x68. The DS3231M is compatible with the ds1307 driver. The second is the TPM driver, tpm_i2c_atmel, which is located at address 0x29. The EEPROM driver is automatically loaded and the other chips currently do not have a native Linux kernel driver.
If you have your DTS file completed and want it included in the official BBB image, you can submit a pull request to the previously mentioned repository that contains the CryptoCape DTS file. Since this repository contains the existing DTS files for the BeagleBone firmware, it is well worth studying if you are building your own cape.