Debian Preparation for PPL

First you need to download all the stuff for the PPL on the BeagleBone Black. In the home directory, execute the following command:

wget http://kn-pr.tkn.tu-berlin.de/ppl/Beaglebone.tar.gz

If you are unsure in which directory you currently are, execute the cd command first. This will change into the home directory.

Now extract the archive by executing the command:

tar -xzf Beaglebone.tar.gz

You will see a new directory called Beaglebone, containing additional directories:

ls Beaglebone
dts  spi  SPI_test

We will need these later. For now let's focus on the proper setup and configuration of the Debian operating system that is required for this lab.

All of the following commands assume to be executed by the superuser. To become superuser, you have to enter the command:

sudo -s -H

after booting the BeagleBone Black and logging in into the debian account, whose default password is temppwd.

Otherwise you have to prefix every command with the word sudo. E.g. instead entering the command apt-get update enter the command sudo apt-get update.

Now, after you have become superuser, it is a good advice to update the operating system with new packages by entering the commands:

apt-get update
apt-get upgrade

This ensures the the operation system is up do date.

The following additional packages are needed:

apt-get install cmake

You may set the timezone to German standard time using the following command:

timedatectl set-timezone Europe/Berlin

Issue the timedatectl command without parameters to verify your system time. If it's not synchronized correctly, don't worry, it will eventually synchronize later.

At the time of writing this memo, the kernel version included in the Debian image was 4.19.94-ti-r42. To update to the latest stable kernel release, that most likely is a newer kernel than the kernel of the Debian image, do the following:

cd /opt/scripts/tools/
git pull
./update_kernel.sh

Now boot the BeagleBone Black once again.

reboot

After the reboot, let's check our new upgraded kernel:

uname -a
Linux beaglebone 4.19.94-ti-r72 #1buster SMP PREEMPT Tue Mar 8 22:13:06 UTC 2022 armv7l GNU/Linux

Now the kernel version 4.19.94-ti-r72 is installed.

In PPL, we need to configure the device tree of the system. A device tree dynamically¹⁾ describes which and how hardware is connected to the system. As we use the SPI protocol to communicate with the CC1200, we need to configure our hardware in a way that the kernel is able to communicate with the SPI controller and the PRU in the first place. This can be done by loading so called device tree overlays which overwrite the default configuration done by the master device tree, which gets shipped by the kernel.

In the following we will instruct the bootloader (called U-Boot) to load some device tree overlays during boot, which are required to configure the hardware peripherals to fit our needs. You will also compile and install a custom device tree overlay, which represents the actual wiring of the CC1200 to the BeagleBone's pins. This is required because there are multiple pins we could connect the CC1200 to and the kernel is unable to automatically discover these.

In first versions the wiring was made by hand. Today an adapter card is used. The wiring is shown in Fig. 1 and described here.

Fig. 1: Wireing of BeagleBone Black with CC1200

The pins of HDMI port are multiplexed with the pins of the SPI bus. In order to use the SPI bus, the HDMI pins must be disabled by uncommenting the following line in the file /boot/uEnv.txt:

disable_uboot_overlay_video=1

Per default the pins of the BeagleBone Black are wired for universal use, meaning the pins are connected to the commonly used devices. This will result in an error, if loading your own device tree overlay.

To disable universal use, comment out the following line in the file /boot/uEnv.txt

enable_uboot_cape_universal=1

To make the changes effective, reboot.

To test that HDMI is disabled, execute the following command:

grep "pin 41" /sys/kernel/debug/pinctrl/44e10800.pinmux-pinctrl-single/pins

and look, that the output matches the following:

pin 41 (PIN41) 44e108a4 0000002f pinctrl-single

If the Hex-code is not 0000002f HDMI is still enabled.

²⁾

The communication between the ARM host processor and the PRU (Programmable Realtime Unit) is implemented either by the Remoteproc-Driver or the UIO PRU driver. Per default the Remoteproc driver is used. In this memo, it will be described, how to enable the UIO PRU driver.

After booting a fresh Debian image and executing the command:

lsmod
 
Module                  Size  Used by
pru_rproc              28672  0
irq_pruss_intc         20480  1 pru_rproc
pruss                  16384  1 pru_rproc
pm33xx                 16384  0
wkup_m3_ipc            16384  1 pm33xx
wkup_m3_rproc          16384  1
remoteproc             57344  3 pru_rproc,wkup_m3_rproc,wkup_m3_ipc
virtio                 16384  1 remoteproc
pvrsrvkm              421888  0
virtio_ring            28672  1 remoteproc
pruss_soc_bus          16384  0
usb_f_acm              16384  2
u_serial               20480  3 usb_f_acm
usb_f_ncm              28672  2
usb_f_mass_storage     53248  2
uio_pdrv_genirq        16384  0
uio                    20480  1 uio_pdrv_genirq
usb_f_rndis            32768  4
u_ether                20480  2 usb_f_ncm,usb_f_rndis
libcomposite           65536  18 usb_f_acm,usb_f_ncm,usb_f_mass_storage,usb_f_rndis

Looking at the output, it seems the UIO PRU driver (uio_pdrv_genirq) is already enabled, but this Assumption is wrong. It needs several steps to enable the driver.

We need to instruct the bootloader to load the device tree overlay blob which enables the UIO driver. This can be done by uncommenting the the following line in the file /boot/uEnv.txt:

uboot_overlay_pru=/lib/firmware/AM335X-PRU-UIO-00A0.dtbo

We should also disable the overlay for the unused rproc driver by commenting out the following line in the same file:

uboot_overlay_pru=/lib/firmware/AM335X-PRU-RPROC-4-19-TI-00A0.dtbo

Finally the Remoteproc driver must be disabled by editing the file /etc/modprobe.d/pruss-blacklist.conf (create the file if it's not there).

Remove the line 'blacklist uio_pruss' and add the following lines:

blacklist pruss
blacklist pruss_intc
blacklist pru-rproc
blacklist spidev

Afterward reboot the Beaglebone Black.

reboot

To verify that the device tree modifications have been loaded correctly, execute:

lsmod
 
Module                  Size  Used by
pm33xx                 16384  0
wkup_m3_ipc            16384  1 pm33xx
wkup_m3_rproc          16384  1
remoteproc             57344  2 wkup_m3_rproc,wkup_m3_ipc
virtio                 16384  1 remoteproc
virtio_ring            28672  1 remoteproc
pvrsrvkm              421888  0
uio_pruss              16384  0
usb_f_acm              16384  2
u_serial               20480  3 usb_f_acm
uio_pdrv_genirq        16384  0
usb_f_ncm              28672  2
uio                    20480  2 uio_pruss,uio_pdrv_genirq
usb_f_mass_storage     53248  2
usb_f_rndis            32768  4
u_ether                20480  2 usb_f_ncm,usb_f_rndis
libcomposite           65536  18 usb_f_acm,usb_f_ncm,usb_f_mass_storage,usb_f_rndis

Now only UIO PRU drivers are loaded and no rproc drivers.

For PPL the CC1200 is connected to the SPI bus of the BeagleBone Black and the SPI bus is controlled by the PRU. Therefore we have to tell the Linux kernel how exactly the CC1200 is wired with the PRU and the system. This is described in a device tree overlay file which you have downloaded in the very first step of this chapter. Change to the directory where you have downloaded the ppl files to, e.g.:

cd ~/Beaglebone/dts

Directory dts contains the file BB-BONE-CC1200-00A0.dts. In this file the device tree modifications are included. To compile it to a binary file enter:

dtc -O dtb -o  BB-BONE-CC1200-00A0.dtbo -b 0 -@ BB-BONE-CC1200-00A0.dts

During the compilation you can safely ignore warnings like

BB-BONE-CC1200-00A0.dtbo: Warning (unit_address_vs_reg): Node /fragment@0 has a unit name, but no reg property

dtc is the device tree compiler, which produces the bizarre overlay file BB-BONE-CC1200-00A0.dtbo. Next copy this file to the system firmware directory:

cp BB-BONE-CC1200-00A0.dtbo /lib/firmware/

Now that we have compiled the device tree overlay and placed it in the right location, we have to instruct the bootloader to load this custom overlay. To do so open the file /boot/uEnv.txt and find the line:

###Custom Cape
#dtb_overlay=/lib/firmware/<file8>.dtbo

Uncomment this line and edit it so that it loads our own device tree overlay blob:

dtb_overlay=/lib/firmware/BB-BONE-CC1200-00A0.dtbo

After that, reboot.

After all that is done we can do a final test to verify that all the hardware is configured correctly.

Execute the command as root and inspect its output:

/opt/scripts/tools/version.sh | grep -i uboot

It should look like the following:

UBOOT: Booted Device-Tree:[am335x-boneblack-uboot.dts]
UBOOT: Loaded Overlay:[AM335X-PRU-UIO-00A0]
UBOOT: Loaded Overlay:[BB-ADC-00A0.bb.org-overlays]
UBOOT: Loaded Overlay:[BB-BONE-eMMC1-01-00A0.bb.org-overlays]
uboot_overlay_options:[enable_uboot_overlays=1]
uboot_overlay_options:[disable_uboot_overlay_video=1]
uboot_overlay_options:[uboot_overlay_pru=/lib/firmware/AM335X-PRU-UIO-00A0.dtbo]
uboot_overlay_options:[dtb_overlay=/lib/firmware/BB-BONE-CC1200-00A0.dtbo]
cmdline:[console=ttyO0,115200n8 bone_capemgr.uboot_capemgr_enabled=1 root=/dev/mmcblk0p1 ro rootfstype=ext4 rootwait coherent_pool=1M net.ifnames=0 lpj=1990656 rng_core.default_quality=100 quiet]

If you see any of the following lines in the output, something went wrong. Redo the above steps in this case.

UBOOT: Booted Device-Tree:[am335x-boneblack-uboot-univ.dts]
UBOOT: Loaded Overlay:[AM335X-PRU-RPROC-4-19-TI-00A0]
UBOOT: Loaded Overlay:[BB-HDMI-TDA998x-00A0]
uboot_overlay_options:[uboot_overlay_pru=/lib/firmware/AM335X-PRU-RPROC-4-19-TI-00A0.dtbo]
uboot_overlay_options:[enable_uboot_cape_universal=1]