NULLCape. How to Roll your own BeagleBone Capes (Part II)

In Part I (http://papermint-designs.com/community/node/331) we discussed how to attach an EEPROM to our cape. Now we will see how to fill the EEPROM with useful data.

GENERATING A VALID EEPROM

We've already seen how to write data in our EEPROM (see http://papermint-designs.com/community/node/331). Now, we need to know which data we have to write. That's easy, cape EEPROMs have to follow the format described in the System Reference Manual. Specifically in section 8.2.4 EEPROM Data Format.

This is a binary format and therefore a bit difficult to write by hand. So, we need a tool. I had only found two tools out there. If you know of any other, please just let me know in the comments.

First one is a Bonescript program which parses a JSON file in order to produce a valid EEPROM file ready to dump into our chip. Second one is an interactive C application wrote by K. Keller. Details about both of them can be found at K. Keller blog (don't miss it):

http://azkeller.com/blog/?p=62

For my first test I used the mkeeprom tool from K.Keller. It works great. The BeagleBone script requires to create a quite verbose JSON file. You can chose whatever you want. The JSON thing is not that bad because you can start from a template.

Anyhow, just for fun, I started to create my own tool. It does not do that much right now. It just creates a valid minimal EEPROM file form a set of hardcoded values.

INTRODUCING bbcape_eeprom

You can get bbcape_eeprom from my just started github repository: https://github.com/picoflamingo/BBCape_EEPROM

As I said, right now it just creates a static file that will allow us to continue with this tutorial. Hopefully it would evolve into a full tool in the future... Let's see.

This is the output of the tool after typing the tree available commands: d for dump, w for write and q for quit.

root@beaglebone:~# ./bbcape_eeprom 
BeagleBone Cape EEProm Generator 0.1
(c) 2013, David Martinez Oliveira
License GPLv3+: GNU GPL version 3 or later 
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

BBCapeEEPROM> d
     00 01 02 03 04 05 06 07 - 08 09 0a 0b 0c 0d 0e 0f
0000 aa 55 33 ee 41 31 42 65 - 61 67 6c 65 42 6f 6e 65  | �U3�A1Be agleBone
0010 20 4e 55 4c 4c 43 61 70 - 65 00 00 00 00 00 00 00  |  NULLCap e.......
0020 00 00 00 00 00 00 30 30 - 41 30 70 69 63 6f 46 6c  | ......00 A0picoFl
0030 61 6d 69 6e 67 6f 00 00 - 00 00 42 42 2d 4e 55 4c  | amingo.. ..BB-NUL
0040 4c 43 61 70 65 00 00 00 - 00 00 30 30 32 39 31 32  | LCape... ..002912
0050 57 54 48 52 30 33 38 33 - 00 00 00 00 00 00 00 00  | WTHR0383 ........
0060 00 00 00 00 00 00 00 00 - 00 00 00 00 00 00 00 00  | ........ ........
0070 00 00 00 00 00 00 00 00 - 00 00 00 00 00 00 00 00  | ........ ........
0080 00 00 00 00 00 00 00 00 - 00 00 00 00 00 00 00 00  | ........ ........
0090 00 00 00 00 00 00 00 00 - 00 00 00 00 00 00 00 00  | ........ ........
00a0 00 00 00 00 00 00 00 00 - 00 00 00 00 00 00 00 00  | ........ ........
00b0 00 00 00 00 00 00 00 00 - 00 00 00 00 00 00 00 00  | ........ ........
00c0 00 00 00 00 00 00 00 00 - 00 00 00 00 00 00 00 00  | ........ ........
00d0 00 00 00 00 00 00 00 00 - 00 00 00 00 00 00 00 00  | ........ ........
00e0 00 00 00 00 00 00 00 00 - 00 00 00 00 00 00 00 00  | ........ ........
00f0 00 00 00 00 00 00 00 00 - 00 00 00 00 00 00 00 00  | ........ ........

BBCapeEEPROM> w nullcape.bin
+ Writting EEPROM to file 'nullcape.bin'

BBCapeEEPROM> q
--
Thanks for using BeagleBoneCape EEPROM Generator
Visit http://papermint-designs.com/community for more tools and tutorials
Now we have our EEPROM content in the nullcape.bin file and we can write it into our EEPROM from the command line:
root@beaglebone:~# cat nullcape.bin > /sys/bus/i2c/devices/1-0057/eeprom
Remember we are using address 0x57. Change command above if you are using a different I2C address. At this point, our NULLCape is ready. We are the proud owners of a real BeagleBone Cape! However, as it is now we are not taking any advantage of using an EEPROM in our cape. As we mentioned in the previous article, this EEPROM content is intended to support the software in the BeagleBone to configure itself, specifically the pin mux status for the P8 and P9 connectors.

SOFTWARE CONFIGURATION. THE DEVICE TREE

If we boot the BeagleBone without any further action and we check the system log for NULLCape we will see something like this:
root@beaglebone:~# dmesg | grep NULL
[    0.384911] bone-capemgr bone_capemgr.9: slot #3: 'BeagleBone NULLCape,00A0,picoFlamingo,BB-NULLCape'
[    0.385897] bone-capemgr bone_capemgr.9: loader: before slot-3 BB-NULLCape:00A0 (prio 0)
[    0.385925] bone-capemgr bone_capemgr.9: loader: check slot-3 BB-NULLCape:00A0 (prio 0)
[    0.389839] bone-capemgr bone_capemgr.9: loader: after slot-3 BB-NULLCape:00A0 (prio 0)
[    0.389870] bone-capemgr bone_capemgr.9: slot #3: Requesting part number/version based 
'BB-NULLCape-00A0.dtbo
[    0.389900] bone-capemgr bone_capemgr.9: slot #3: Requesting firmware 'BB-NULLCape-00A0.dtbo' for 
board-name 'BeagleBone NULLCape', version '00A0'
[    3.651953] bone-capemgr bone_capemgr.9: failed to load firmware 'BB-NULLCape-00A0.dtbo'
[    3.660495] bone-capemgr bone_capemgr.9: loader: failed to load slot-3 BB-NULLCape:00A0 (prio 0)
First thing we can see is that the data we had stored in our EEPROM had made it to the software side through the Cape Manager (bone-capemgr for friends) component. Second thing is that the Cape Manager is trying to load a firmware file, in order to enable the cape. That is a device tree file whose name depends on the information we had wrote to our EEPROM. So, now we need to create that file. For our NULLCape, which actually does nothing, the file below will work.
/dts-v1/;
/plugin/;

/ {
    compatible = "ti,beaglebone", "ti,beaglebone-black";

    /* identification */
    part-number = "BB-NULLCAPE";

    /* version */
    version = "00A0";

    fragment@0 {
        target = <&i2c2>;
        __overlay__ {
            status = "okay";
        };
    };

};
I had not yet dive into the device tree stuff so I will not say anything about the contents of the file at this point. It is even possible that it is not fully correct, however it works for the current purpose of this article. Device tree details will be a matter for a future article. The only thing we have to know right now is that the file name we have to use shall be:
BB-NULLCape-00A0.dts
We need to use this name in order to match the content of our EEPROM, and therefore, let the Cape Manager find the proper firmware file for our cape. Now we need to compile this device tree source file, into an object binary file. The following command like will do the trick:
dtc -O dtb -o BB-NULLCape-00A0.dtbo -b -o -@ BB-NULLCape-00A0.dts
OK, too much black magic. I know. At this point, what we need to know is that the content in the EEPROM allows the Cape Manager to find a file that describes the cape. This file has to be in a binary form and a "compiler" (dtc -- device tree compiler) is used to generate those binary files from a more "human friendly" format... more or less.

FINALLY BOOTING WITH OUR NULLCAPE

Anyhow, our firmware file is ready so we can test it. First thing to do is to copy our just generated firmware file in the proper place:
root@beaglebone:~# cp BB-NULLCape-00A0.dtbo /lib/firmware/.
root@beaglebone:~#
Now we can tell the Cape Manager about our cape.
root@beaglebone:~# cat /sys/devices/bone_capemgr.*/slots
 0: 54:PF--- 
 1: 55:PF--- 
 2: 56: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
root@beaglebone:~# echo BB-NULLCape > /sys/devices/bone_capemgr.*/slots
root@beaglebone:~# cat /sys/devices/bone_capemgr.*/slots
 0: 54:PF--- 
 1: 55:PF--- 
 2: 56: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
 6: ff:P-O-L Override Board Name,00A0,Override Manuf,BB-NULLCape
In the sequence of commands above you can see the default built-in capes for the eMMC and HDMI peripherals in the BeagleBone. After telling Cape Manager about our cape (the echo line somewhere in the middle) we see a new overlay cape in our system. From this point on, whenever our cape is connected and the Cape Manager can read our EEPROM the proper firmware will be loaded. To finish with this article. Let's see how it looks like after a reboot This is what we will see in the system log.
root@beaglebone:~# dmesg | grep NULL
[    0.384869] bone-capemgr bone_capemgr.9: slot #3: 'BeagleBone NULLCape,00A0,picoFlamingo,BB-NULLCape'
[    0.385849] bone-capemgr bone_capemgr.9: loader: before slot-3 BB-NULLCape:00A0 (prio 0)
[    0.385878] bone-capemgr bone_capemgr.9: loader: check slot-3 BB-NULLCape:00A0 (prio 0)
[    0.389823] bone-capemgr bone_capemgr.9: loader: after slot-3 BB-NULLCape:00A0 (prio 0)
[    0.389855] bone-capemgr bone_capemgr.9: slot #3: Requesting part number/version based 
'BB-NULLCape-00A0.dtbo
[    0.389886] bone-capemgr bone_capemgr.9: slot #3: Requesting firmware 'BB-NULLCape-00A0.dtbo' for 
board-name 'BeagleBone NULLCape', version '00A0'
[    3.547865] bone-capemgr bone_capemgr.9: slot #3: dtbo 'BB-NULLCape-00A0.dtbo' loaded; converting to 
live tree
[    3.548151] bone-capemgr bone_capemgr.9: loader: done slot-3 BB-NULLCape:00A0 (prio 0)
root@beaglebone:~#
Good. This time the Cape Manager found our firmware and used it. And this is what the Cape manager will show us:
root@beaglebone:~# cat /sys/devices/bone_capemgr.*/slots                                                                                                 
 0: 54:PF--- 
 1: 55:PF--- 
 2: 56:PF--- 
 3: 57:P---L BeagleBone NULLCape,00A0,picoFlamingo,BB-NULLCape
 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
Note that, after rebooting, our cape appears in the proper I2C address and as a real cape. When we loaded the firmware dynamically into the Cape Manager before the cape was shown as a overlay... As I said, all this device tree details will be treated in detail in a future article... whenever I manage to master them :) CU The picoFlamingo Team

Comments

You can choose whatever name for the dts file

Hi,
First thank you for the tutorial and the eeprom tool.
I just wanted to tell you that, the device tree source file does not really need to have the "same" name as the device tree object file (dtbo).
You just need to indicate the dts filename in the -@ option of the dtc command line.

However, the dtbo file name needs to be the same as the one you wrote in your eeprom.

Keep it up.

Cheers,
Oussema.

You are completely right.

You are completely right. Thanks for the clarification, I had just re-read the text and indeed it seems to suggest that the source name requires an special convention.

cheers
picoFlamingo

failed to load slot-1 BB-NULLCape:00A0 (prio 0)

Hello!

It always fails to load slot-1. I have done exactly as you example. (BeagleBone Black)
Is there any way to get better error messages?

Cheers,
Andreas

[ 1.792469] bone-capemgr bone_capemgr.9: slot #1: 'BeagleBone NULLCape,00A0,picoFlamingo,BB-NULLCape'
[ 1.985454] bone-capemgr bone_capemgr.9: loader: before slot-1 BB-NULLCape:00A0 (prio 0)
[ 1.993967] bone-capemgr bone_capemgr.9: loader: check slot-1 BB-NULLCape:00A0 (prio 0)
[ 2.016599] bone-capemgr bone_capemgr.9: loader: after slot-1 BB-NULLCape:00A0 (prio 0)
[ 2.037535] bone-capemgr bone_capemgr.9: slot #1: Requesting part number/version based 'BB-NULLCape-00A0.dtbo
[ 2.068355] bone-capemgr bone_capemgr.9: slot #1: Requesting firmware 'BB-NULLCape-00A0.dtbo' for board-name 'BeagleBone NULLCape', version '00A0'
[ 3.298025] bone-capemgr bone_capemgr.9: failed to load firmware 'BB-NULLCape-00A0.dtbo'
[ 3.306647] bone-capemgr bone_capemgr.9: loader: failed to load slot-1 BB-NULLCape:00A0 (prio 0)

Linux almlink 3.8.13-bone28 #1 SMP Fri Sep 13 03:12:24 UTC 2013 armv7l armv7l armv7l GNU/Linux

Refer to comments on Part IV

Hi Andreas,

It looks like your problem is common for a given configuration that I haven't identified yet. Please refer to the comments on the last part of the tutorial. There you will find some useful pointers from other cape hackers.

http://papermint-designs.com/community/node/377#comments

As mentioned in the tutorial there are still a missed part which will give details on the device tree and cape manager. Maybe I manage to get it out next week.

cheers
picoFlamingo