Chapter 5. Basic Programming Recipes with the Linux Kernel

In this chapter, we will cover the following recipes:

• Kernel application binary interface

• Installing the latest kernel image

• Installing and building a custom kernel

• Interactions with the kernel – sysfs entries and controlling the GPIOs

• Device Tree and its roots

• Device Tree / basic build

• Device Tree / advanced – adding DT overlay to run a custom cape

• Universal cape overlay

• Running a script to check DT usage on GPIO pins

Introduction

We will now learn something about the real guts of our platform, the Linux kernel. Of course, understanding all the bits about the kernel is for another very large set of books and discussion. We won't be doing that here!

What we do want to explore is how to update, build, and modify the kernel in ways that will give us tighter control over our hardware and make the development process less opaque. Then, we'll conclude the chapter by working with one of the key differentiators for BeagleBone Black, the Device Tree, which is a clever way to describe the hardware in our system.

The best part is that if you do all the recipes, you'll be forever known as Colonel kernel. Well, lieutenant kernel. All right, maybe private kernel. But it's a start....

Kernel building basics

What is this mysterious kernel thing of which we speak? What does it look like? Where does it live? Well, on one level, it is merely a file. Let's take a peek. Open up a terminal on your BBB and type the following commands...

Kernel application binary interface

Now, let's do a quick, simple task with a command to find out which kernel we are running. The command can serve as a first-level "diagnostic" tool when we need to troubleshoot errors or incompatibilities with any software we want to add or compile for our system.

Getting ready

This is a simple setup, so all you need to do is connect your board via USB to your host computer and fire it up. Then, open a terminal window.

How to do it...

The steps to do this are simple:

1. Firstly, log in as the root user using the following command:

   $ sudo -i
   

2. Now, run a command that tells us a few important things about the kernel. Let's choose the -a option to show all information about the system, as follows:

   root@beaglebone:~# uname -a
   Linux beaglebone 3.8.13-bone67 #1 SMP Wed Sep 24 01:36:09 UTC 2014 armv7l GNU/Linux
   

   From this command's output, we discover several items of interest, as follows:

   The kernel version: According to our output, the installed version of the Linux kernel...

Installing the latest kernel image

All the way back in Chapter 1, Setting Up for the First Time, we used a set of tools that came with our Debian distro. In that case, we used a tool (a bash script) to expand our partition. In this case, we'll use another script from that toolset that runs a routine to update our kernel image. Let's go get it. With developer Robert Nelson's slick scripts (https://eewiki.net/display/linuxonarm/BeagleBone+Black), the process to update or build the kernel on Debian for the BBB has become a snap.

Getting ready

As in our preceding recipe, connect your board via USB to your host computer, boot up, and then open a terminal window.

How to do it...

Let's get started! To do this, perform the following steps:

1. Firstly, log in as root with the following command:

   # sudo -i
   

   Following this, check the current version of your kernel through the following command:

   # uname -a
   Linux beaglebone 3.8.13-bone67 #1 SMP Wed Sep 24 01:36:09 UTC 2014 armv7l GNU/Linux
   

   Note

   Write down the version...

Installing and building a custom kernel

This recipe will build the kernel and modules from scratch and copy them to a deploy or temporary directory.

Getting ready

Connect and power up your board via USB to your host computer; then, open a terminal window.

How to do it...

To perform this recipe, follow these steps:

1. First, log in as the root user and then download the kernel file from Robert C. Nelson's git repo:

   $ sudo -i
   # git clone https://github.com/RobertCNelson/bb-kernel.git
   

2. Navigate to the new directory that git created for you on your BBB with this command:

   # cd bb-kernel/
   

3. At this point, you have two options for the kernel version you prefer to use: either v3.8.x or the latest experimental v3.14.x. You'll notice that the git command also generates a tmp directory for the build:

   • For the 3.8.x Wheezy branch (this version comes with full cape support) use this command:

     ~/bb-kernel# git checkout origin/am33x-v3.8 -b tmp
     

   • For the v3.14.x Jessie branch (which comes with better USB and Ethernet...

Interactions with the kernel – sysfs entries and controlling the GPIOs

When first starting out with physical computing and a Linux board, such as the BBB in particular, it is less daunting to use preexisting libraries along with familiar programming tools. This is why we used tools such as Python libraries and BoneScript to gain access to BeagleBone Black's GPIO pins, methods that abstract the kernel layer from the user space layer.

However, it is useful to understand the nature of this abstraction a bit better, particularly when it comes to the GPIO pins. The Linux kernel uses a virtual file system interface—or sysfs—to read and write to the pins. Sysfs easily and effectively exposes drivers for the hardware—buttons, LEDs, sensors, add-ons, and so on. So, you can control them. Manipulating this system gives us insight into how the kernel and hardware can interoperate. In this section, we'll look at how to activate the sysfs interface.

To reiterate, instead of programming with a userland library...

Device Tree and its roots

Linus Torvalds was sad and mad. ARM was making Linus sad and mad. There were too many cooks, too many ingredients, too many new hardware variations in the world of ARM devices. The architecture had become so popular in the embedded computing world that a thicket of third-party devices were being cooked up to work with ARM. Custom hardware drivers and custom kernels were everywhere. This was making the Linux kernel playground increasingly chaotic.

So, Linus roared: go back to the kitchen, cooks, and make a better recipe! So, they did. Or, so the story goes. Thus was born Device Tree....

For beginners, Device Tree can be a bit difficult to wrap one's head around. However, in order to use BeagleBone Black in more interesting projects, an understanding is often critical. Basically, Device Tree is a data structure to describe the hardware that you add on to your board. With Device Tree, the details of a device are available to the board without needing to be hardcoded...

Device Tree / basic build

On the BBB, there are three essential steps to create and run a Device Tree file:

1. Create a source file (dts).

2. Compile it and make a binary (dtb)—also known as blob—of the file.

3. Ensure that the kernel knows where to find the new blob.

Let's start with a simple recipe, one that turns off one of the onboard LEDs: specifically, USR0, which is the LED that blinks with the "heartbeat" pattern. There are simpler ways to do this, as we did the same thing with BoneScript in Chapter 3, Physical Computing Recipes Using JavaScript, the BoneScript Library, and Python. However, it remains a useful introductory recipe to understand Device Tree's interaction with the kernel.

Getting ready

For the next recipe, simply power up your board via the USB port. Internet connectivity is not required.

How to do it...

You need to perform the following steps:

1. Log in as root with this command:

   $ sudo -i
   #
   

2. Grab the file that we need for this recipe. Going forward in the book, we will more commonly have...

Device Tree / advanced – adding DT overlay to run a custom cape

BeagleBone Black introduced the idea of Device Tree overlays that provide even more functionality to DT by modifying the tree in user space, typified in our prior example. With DT overlay, there is no need to reboot.

We saw in our earlier section on sysfs usage the directory/extension .capemgr, which refers to cape manager. The BeagleBone kernel uses cape manager as a way to provide dynamic loading and unloading of device tree fragments both at compile time and from user space after the device has booted. We will demonstrate this again here; except this time, we will use DT to enable a custom cape, one which delivers audio I/O functionality to the BBB.

Getting ready

In addition to your usual BBB setup, we will use Audio Cape Rev. B, available from CircuitCo (http://boardzoo.com/index.php/beaglebone-black/bone-audio.html). Attach the cape to your BBB's header stack, following the orientation shown in the following pictures:

Note

If...

Universal cape overlay

Developer Charles Steinkuehler developed an enormously useful addition to the BeagleBone Black and DT world with his universal cape overlay. Now included by default on the current 3.7 and 3.8 kernels, the code greatly simplifies pin and cape management via simple command-line calls. The toolset can, in some cases, obviate the need to use many types of sysfs calls, some of which you learned earlier in the chapter.

Getting ready

A BBB hooked up and powered via USB.

How to do it…

Perform the following steps:

1. Begin by logging in as the root user and then loading the cape overlay using the following commands:

   $ sudo -i
   # echo cape-universaln > /sys/devices/bone_capemgr.*/slots
   

   This command loads all devices and exports gpio. The pins currently default to gpio inputs. However, with the next set of commands, we can easily change their state.

2. Let's consider the example of the P8_12 pin and run a command to find out its state:

   # config-pin -q P8.12
   P8_12 Mode: gpio Direction:...

Running a script to check DT usage on GPIO pins

When modifying or working with Device Tree files, we frequently need to check pin usage so that we do not inadvertently try to write to claimed or unsuitable pins.

The following recipe employs two scripts that you can run with Node.js and helps us locate which pins are free. The scripts exist thanks to the coding work of Professor Mark Yoder at Rose-Hulman Institute of Technology.

Getting ready

You do not need anything more than your basic BBB kit for this recipe, which is a board connected to your host computer via USB.

How to do it…

To run this script, you need to follow these steps:

1. You first need to open up the Cloud9 IDE and create a new script called freeGPIO.js.

2. If you ran the recipe Device Tree Basic Build earlier in this chapter, you will find the file freeGPIO.js in the directory that you got from our GitHub repo. This was available by running the following command:

   git clone https://github.com/HudsonWerks/device-tree.git
   

   Otherwise, you...