The BeagleBone Black is the newest member in the BeagleBoard family. The board is designed to be a low sized small form factor board. The size of the board is comparable to the size of a credit card and it offers expansion headers to add headers called as capes similar to the Raspberry Pi.

The table below highlights the key onboard components of the board along with the connectors available on the board. The diagram of the table below is taken from the BeagleBone Black System Reference Manual.

To work with an embedded system you need a work station on which you can perform the various tasks that are required in the development life cycle. These tasks include:

In this document we use the popular Debian based Linux operating system, Ubuntu as our work station for all the tasks listed above. Ubuntu can be easily downloaded and installed on any PC or laptop.

The source code management tool used by the Linux kernel community is GIT. To use GIT we need to install the packages required on our work station using the Advanced Packaging Tool(APT) using a command line terminal.

Once the packages are successfully installed we will need to configure GIT with some basic information about our name and email address

Further infomation about GIT can be obtained at:
http://git-scm.com/.

Since we are going through the training material provided by Free Electrons we’ll need to download their slides and lab data from their website link:
http://free-electrons.com/training/kernel/

As Free Electrons continues to improve on their training material, this journal will be based on the version available at the time of its writing:

Now that GIT is present in the workstation we can get the main development tree of the Linux kernel as follows:

And if you’re in a corporarte environment or if your firewall blocks out the network port for git you can use http instead as follows:

The whole process should take a while so you can go for a small coffee break and come back. Comparitively using git is recommended as it is faster than http

If you happen to have a copy of the Linux GIT repository all you have to do is pull in the latest changes

Once you have the Linux GIT repository you can pull the latest changes by by running git pull.

Typically when we are developing a project we reuse multiple projects to build our application on top of. Similarly since we will be learing about Embedded Linux we cannot use the tip of the tree as it is the latest but not the stablest version of the kernel.

With GIT we don’t have to clone the whole repository all over again. Instead we can add a reference to a remote tree to our existing clone and fetch all the commits which are unique in that repository. As the stable release is derived from the mainline tree we can add a remote to our repository as follows:

The last part is fetching the unique commits in the stable remote. This command should take a while.

If we check the disk usage per directory in the Linux Kernel source code we get the distribution below. We’ll go through the type of source code in each of those directories in a later section.

Certain busses have interfaces exposed by the kernel which can be used to develop a user space device driver if the hardware is connected to that bus:

On certain SOCs the vendor also provides a user space device driver along with a kernel driver which has access to other processors in the SOC which are running a firmware for highly specialized applications.

The Good

The Bad

One such tool is Cscope which allows us to browse the Linux source code with ease from editors like vim, emacs and also independently using only cscope.

This is a generic indexing tool and code browser which is available as a web service. It supports both C and C++ and it makes it easy to search for declarations, definitions and symbols. A good examples of LXR with the Linux Kernel in action is through the Free Electrons LXR Site and further information abouit LXR can be obtained from its sourceforge page.

In order to get the list of branches on our stable remote tree we have to enter the Linux Kernel source tree and use the git branch command as follows:

We will be working with the 3.13 stable branch and so we will use the remote branch remotes/stable/linux-3.13.y from the list of branches displayed.

Before we do anything let us check the version of our master branch using the top level Makefile in the source code. Using vim or your favourite editor or head examine the first few lines of the Makefile

We can see the version of our master branch is at 3.18.0 -rc4 and the name of the release is "Diseased Newt". Now let us create a local branch starting from the stable remote branch of 3.13.y. The following command uses git checkout to checkout the stable remote branch stable/linux-3.13.y as a local branch with the name 3.13.y.

Once again let us examine the first few lines of the top level Makefile. We can now see the version is at 3.13.11 and the name of the release is "One Giant Leap for Frogkind". So we have successfully managed to create a branch pointing to a stable release of the Linux Kernel source code.

There are several tools that can be used to browse the kernel code and search. We will demonstrate the commands used with examples taken from the labs.

The process of configuring the Linux Kernel includes modifying the configuration file located at the root of the source code. This file is named .config. The dot at the beginning of the file name indicates that it is a hidden file.

The syntax of this file is in the form of simple key value pairs as shown in the example below:

An important point to note is that because options have dependencies it is not advisable to edit the .config file by hand. Preferably use the available configuration interfaces.

It doesn’t make any difference which is used and we can shift between either of the interfaces as they all edit the same .config file.

Upon configuring the kernel source and completion of the build we get a single image which represents the kernel and all the features it is configured for. However it is possible to configure some of the features such as device drivers, filesystems, driver tests, etc. as separate entities called kernel modules.

By configuring certain features as modules we are able to keep the size of the kernel to a minimum. Kernel modules can be loaded from user space to support certain applications on execution or on insertion of certain devices into the system buses like USB, PCI, etc..

Therefore in the configuration of certain features it is possible to select if the feature needs to be compiled as a kernel module. All kernel modules will have to be stored in a file system and will have to be loaded into the running kernel by some user space application or script.

An important point to note in choosing if a feature should be compiled as a module is the latency with which the feature needs to be activated from boot of the system. As the kernel module is stored in a filesystem, it will not be loadable until the filesystem is mounted in the kernel.

When selecting different features and configuring the kernel we come across different types based on the information required to complete the configuration.

There will be dependencies between different kernel objects. To describe the dependency there are two types:

The xconfig configuration utitlity which uses Qt is invoked when running make xconfig in the root directory. If we try to invoke it we get the following error:

Ok we need to install Qt in our system. The dependencies are libqt4-dev and g++. For older kernel sources the dependencies are libqt3-mt-dev.

Again we try running make xconfig and see the graphical interface as shown in the screen capture below:

It is possible to search for a particular feature using the search interface. This can be invoked with a CTRL + F keyboard combination.

Another graphical interface is the gconfig target.This GTK based configuration gives the following error when we invoke it:

In this case we have to install the debian package libglade2-dev

This configuration interface requires no graphical interface and only requires the libncurses-dev debian package to be installed. This interface is popular with other projects such as Linux Target Image Builder (LTIB), Busybox, OpenWrt, etc.. It works well enough for us to ignore the graphical interfaces. It is brought up using a make menuconfig command in the root directory.

We get the following screen shot one the interface is invoked from the shell.

Searching with the menuconfig interface is done by hitting the '/' key similar to vim. Once the search page is displayed we can enter a key word for the search.

The results of the search are displayed as follows:

Another similar test based configuration interface is nconfig with the same dependency on libncurses_dev debian package. Again to invoke the interface we will have to use make nconfig.

We get the following screen shot once the interface is invoked from the shell.

If we are upgrading to a newer release and use the .config file from an older release of the Linux kernel then we need to run make oldconfig. This will inform us of the configuration settings that are irrelevant in the newer release and if there are newer features or parameters then it will prompt us asking for appropriate values for these settings.

Another scenario in which make oldconfig may come in use is if we modify the .config file by hand.

If we mess up our configuration and build a kernel that is unusable then we can revert to the older configuration that the kernel was built. This is done by copyting the .config.old file which gets created if we use any of the configuration interfaces available. All the interfaces save a copy of the existing configuration file .config as a back up in .config.old

Along with the kernel the compiled modules will also have to be installed in the system. To achieve this there is a target modules_install which can be executed after executing the install target of the root makefile.

The kernel modules and related files are installed in the /lib/modules/<version>/ directory. If we explore this directory we will see the following:

There are several targets that are used to clean up files that have been generated by the configuration and compilation of the Linux kernel source code.

Many times when working with embedded boards we don’t set the configuration of a particular board from scratch. It is easier if there is a predefined configuration with which we can start from and there is in most cases. We get a list of predefined configurations from make help which allows us to set the .config to a particular configuration for a specific board.

For instance if we run make viper_defconfig it will overwrite the .config file with the file from arch/arm/configs/viper_defconfig. To get a list of default configurations we can either use make help or the find utility as shown below:

Once we’ve loaded a default configuration which is basically a minimal configuration it’s time to tailor the configuration to our specifications. This will include running one of the configuration interfaces like make menuconfig. We see the settings of the default configuration in the interface.

We also have the ability to save our configuration once it is tailored, as a default configuration. This can be done by running the command make savedefconfig. Running this target causes make to save the .config file with a name defconfig. We can move the new defconfig file to the architecture configs directory with an appropriate name.

Overall the choice of starting from a default minimal configuration lies with the developer. We can also start from scratch but be mindful about selection of the CPU selection and the correct device drivers.

Most embedded platforms have non-discoverable hardware which exists as part of the SOC. This hardware has to be described to the kernel in the form of code or a special hardware description language called Device Tree.

The Device Tree language is used only recently in certain architectures such as ARM, PowerPC, ARC, etc.. The Device Tree source file is compiled into a binary called Device Tree Blob by a compiler and passed to the kernel through the bootloader. Each board will have its own unique hardware and therefore will have a unique device tree source file.

The Device Tree files will be located in the /arch/<ARCH>/boot/dts/ folder. The bootloader has to have the capability to load the Device Tree Blob and the kernel image before starting execution of the kernel.

A popular bootloader with embedded platforms is U-Boot. U-Boot works with a format of kernel image called uImage. This is generated from the zImage using a make uImage target execution for ARM. Newer versions of U-Boot also support booting of the ARM based kernel image zImage directly.

Some ARM platforms require the LOADADDR to be passed along with the make uImage target execution. The address associated with this variable represents the physical memory where the image is executed in.

U-Boot also has the ability to load the Device Tree Blob in memory and pass it to the kernel. The boot process follows the steps

The kernel takes in a list of arguments which can affect its behavior at run time. These argument can be hardcoded during the configuration of the kernel source code by setting the CONFIG_CMDLINE option.

The command line argument can also be passed to the kernel at boot up using an environment variable like bootargs in the case of U-Boot.

There are several kernel arguments documented in Documentation/kernel-parameters.txt. We typically set:

At this point we have to get familiar with our board. It is good to go through the features of the board given in section 4.0 of the BeagleBone Black System Reference Manual.

Design is not possible without documentation, so we download the documents which will help us in the lab sessions. The following are needed:

Tht System Reference Manual describes the details about the design of the board and is available on this site here
The latest document should be available at: https://github.com/CircuitCo/BeagleBone-Black/blob/master/BBB_SRM.pdf?raw=true.

The datasheet of the TI AM335x SoCs is useful to see the PIN assignments later when we want to configure the pinmux settings and is available on this site here
The original link is at the TI website at: http://www.ti.com/lit/ds/symlink/am3359.pdf

The last document is the Technical Reference Manual(TRM) of the TI AM335x SoCs. At over 4000 pages it describes the internal IP design of the chip. It is available here.
The same document can be retrieved from the TI website at : http://www.ti.com/product/am3359

We will be using the lab data available from Free Electrons to setup our BeagleBone Black. First make sure the lab data is downloaded. The lab data which was available at the time of writing this journal is here.

We’ll have to uncompress the file with sudo permissions and change the permissions of the resulting folder. The prime reason being that the package contains system device node files for the NFS root filesystem:

The xz extension of the package indicates that it requires XZ compression utility which if not available on your system can be upgraded as follows:

Now we deviate slightly from the Free Electrons lab slides and first prepare our board as per the instructions provided in the linux-kernel-labs/bootloader/beaglebone-black/README.txt file. The bootable micro-SD card will automatically format the on board eMMC device.

Take the micro-SD card and insert it into a micro-SD adapter/reader like the one shown in the image below:

This memory card reader/adapter should be inserted into the SD card slot available. If your system has a micro-SD card slot then please use that directly. On checking the kernel logs with dmesg we should be able to identify the card detected in the system. If a micro-SD card slot is available then the system should register it as a /dev/mmcblk0 whereas in this case with a memory card reader we see it as /dev/sdb. The following shows the kernel logs:

We will have to first partition the micro-SD card using the sfdisk utility which is part of the util-linux APT package. This tool helps us to list the partitions of a device, check the sizes of the partitions, check the partitions on a device and re-partition a device. We must be extra careful when we use such a tool as it could also cause damage to our workstation system if we select the wrong device file unintentionally.

If the micro-SD card is already partitioned and formated it may be auto mounted by our work station. We will have to un-mount all the partitions before we can proceed.

Again we attempt to repartition the micro-SD card

We will have to format the first partition of the disk using the mkfs.vfat partition.

We now remove and re-insert the micro-SD card into the system to see if it gets detected and automatically mounted. It does and we see that Ubuntu opens up the directory located in /media/conrad/boot.

We will finally have to copy the files from the lab data folder to this partition and un mount the device.

We can now safely eject or remove the micro-SD card from the work station.

The bootable micro-SD card will now be used to reflash the eMMC device to get it ready for the lab session. The process is short but the steps maybe a bit confusing so follow the pictures to nail it down correctly.

The debug serial header connector has been descibed in the Getting Comfortable With The Board section and should be easy to locate with the labelled image in that section. It is a 1x6 header. Serial capability is provided by UART0 of the processor. It would be good to read the section on the debug serial header given in the Technical Reference Manual.

The only two signals available are TX and RX on the connector and the levels on these signals is 3.3V. A FTDI USB to serial cable is recommended as this serves to provide a serial port to PCs/Laptops making use of the available USB port. The FTDI chip translates the USB data to serial and vice versa. There are several provided in the elinux.org website link at:
http://elinux.org/Beagleboard:BeagleBone_Black_Serial.

We will now need to setup the board in such a way so as to allow us to download files to its system memory using U-Boot. To do this we will use Trivial File Transfer Protocol (TFTP) through an ethernet cable. Our board will be the TFTP client and we will configure our Ubuntu work station to act as a TFTP server. TFTP can be installed as shown below using APT.

Now we will connect an ethernet cable between our workstation and the BeagleBone Black ethernet connector. If the workstation does not have any more connections then we will have to use a USB ethernet adapter. In this case we have an unused connection so we will connect the cable as shown.

We next have to configure the network interface on the workstation side. Click on the network manager tasklet on the desktop and select Edit Connections.

Click on the Add button on the left and then Create.. an ethernet connection.

Edit the new ethernet connection by changing its name to BBB. Change the IPV4 settings by selecting the method as manual. And finally add the static address as 192.168.0.1 and netmask as 255.255.255.0. There’s no need to add a gateway but if the cursor is in the textbox enter 0.0.0.0. Save the settings and the interface is set up on the workstation.

Now that we have our workstation ethernet interface configured we can setup networking on U-Boot’s side. We can print the environment to check what the variables are set to by running printenv which will give out the values of all the variables in the U-Boot environment. In our case with the default environment values we see that the IP address and TFTP server IP is not set.

We will set the server IP to the static IP we assigned to our ethernet interface on our workstation and IP address to a different value as follows:

The next step is to test the connection by creating a file called testfile.txt in /var/lib/tftpboot/. We will attempt to download the file through the tftp command in U-Boot.

This may happen if the tftp service has not been started properly. So we can restart the service using the following command on the workstation.

Now when we try the tftp command again in the U-Boot command prompt we are able to successfully download the file.

We have successfully setup U-Boot to download the kernel.

In the previous lab we enabled network connectivity between the board and workstation by configuring the U-Boot environment appropriately. This enables us to build our binaries on the workstation and test it on the board without having to flash the board which saves time as well as prolongs the life of the eMMC device or micro-SD card. We will also enable a NFS type of root filesystem which will allow us to test cross-compiled modules on board.

We will need to install a couple of packages before we can proceed with the lab.

We start with configuring the kernel source code with a default configuration. Since our board has a processor(AM335x) which belongs to the OMAP2 family we will use a default configuration file for that board i.e. omap2plus_defconfig.

Now configure the kernel to use a NFS root filesystem. This can be done with any of the configuration targets i.e. menuconfig, nconfig, gconfig or xconfig.

To identify the configuration option for NFS root filesystem search for CONFIG_ROOT_NFS once the menuconfig screen appears.

We see that CONFIG_ROOT_NFS can be reached through "File systems" and "Network File Systems"

Now it is time to cross-compile the kernel after we have configured it correctly. We will first do a clean on the source code to make sure we’re compiling fresh

We will now need to setup our workstation as a NFS server. This will require installation of the nfs-kernel-server package.

Once installed we need to edit the /etc/exports file to configure the server to allow a NFS client to connect to it and mount a directory. In this case we want to configure the NFS server in such a way so as to allow our BeagleBone Black platform to mount the root filesystem which is there in our workstation lab data directory.

Finally before we boot make sure to restart the NFS server as shown below. If there are any errors then the server will refuse to start and error logs will appear. The /etc/exports file must be revisited and the syntax of the line must be inspected and corrected. Fix the errors and ensure the NFS server restarts before proceeding.

We will now proceed to boot the system. Make sure the BeagleBone Black is connected to the USB to serial connector correctly as was described in Lab2. Also make sure your etherned cable is connected between the board and your workstation. On powering up the board interrupt the boot sequence so that we have access to the U-Boot console.

A kernel module can use functions and variables defined in other parts of the Linux kernel source code so long as they are exported. There are two macros that are used to export the symbol names that can be used by other modules:

The diagram illustrates the difference between exporting a symbol with EXPORT_SYMBOL versus EXPORT_SYMBOL_GPL. Symbols exported by EXPORT_SYMBOL_GPL(func3, func4) can be used by only GPL modules whereas symbols exported by EXPORT_SYMBOL can be used by both GPL and Non-GPL modules. A module gets it’s license from the MODULE_LICENSE macro added in it’s source code along with the other metadata.

The kernel can only use symbols defined in its source code. It cannot use symbols exported by modules even if they are GPL licensed modules. Symbols exported with EXPORT_SYMBOL_GPL can be used only by GPL licensed modules. Symbols exported with EXPORT_SYMBOL can be used by GPL and Non-GPL licensed modules

The MODULE_LICENSE macro is used to define the license of the module. It is used to restrict the functions that a module can use if it is not a GPL licensed module. GPL licensed modules have access to all exported symbols whereas Non-GPL licensed modules can only access symbols exported with EXPORT_SYMBOL.

Another use for module licenses is to identify issues comming from proprietary modules. Typically kernel developers do not fix issues coming from proprietary modules or drivers which cause kernel crashes and OOPSes.

GPL compatible licenses are defined in the include/linux/license.h file as shown above. These include GPL, GPL v2, GPL and additional rights, Dual BSD/GPL, Dual MIT/GPL or Dual MPL/GPL. All other licenses are considered as proprietary.

The source code is maintained separately outside the kernel source code. It is easier to modify the source code, however adapting the module source code to changes in the kernel API means that the maintainer has the onus of keeping it upto date with the changing kernel. One disadvantage is that the module cannot be built statically with the kernel. The following snippet shows the Makefile that can be used to build an out of tree kernel module/driver.

When compiled out of tree the Makefile does not have KERNELRELEASE defined and therefore KDIR is set to the path to either:

The kernel Makefile gets invoked as KDIR is set and the rule for the target all will change to the KDIR first and call the corresponding Makefile in that path. Additionally $PWD is passed as an argument value in M to the kernel Makefile. The double $$ is required to pass $PWD as the value to M.

The kernel Makefile knows that it has to compile a module and because there is a value for M it can locate where the module Makefile is present. This time the kernel Makefile calls the module Makefile and the value of KERNELRELEASE is defined. The kernel uses the definition of obj-m to identify the module to be compiled which in our case is wassup.o. In this way the module Makefile given above is invoked twice, the first time from the module directory and second time by the kernel Makefile.

The kernel directory pointed to by KDIR in the module makefile must be configured as there will be differences between different configurations of the kernel. The module compiled against a specific version will only load in that version and configuration of the kernel. If there is a mismatch then insmod/modprobe will crib with an output "Invalid module format".

The source code is integrated inside the kernel source code. It can be integrated with the configuration and compilation process of the kernel. The module can be built statically with the kernel source code.

To add a new driver or module to the kernel source tree we have to place the source file in the appropriate source directory. For example we’ll take a look at the USB serial navman driver. The source code for the driver/module should be present in a single file. If the driver is really big then it should have its own directory. The source file for the navman driver is in drivers/usb/serial/navman.c

To configure the kernel to include a module or driver we need to add information in the drivers/usb/serial/Kconfig file in the same directory. The snippet below shows that the navman driver has a kernel option type of tristate which means it can be enabled, disabled or configured as a module.

Next we take a look at the drivers/usb/serial/Makefile which has a line based on the drivers/usb/serial/Kconfig setting. The name of the configuration field CONFIG_USB_SERIAL_NAVMAN is derived from the KConfig settings. The value of CONFIG_USB_SERIAL_NAVMAN will be based on the configuration applied upon invoking make menuconfig. After configuring the kernel and enabling th module/driver we can build it by running make.

Further information about the Kernel build process and incorporating newer files to the source can be obtained at:
Documentation/kbuild