Getting Started

Downloading the Source Code

The Cuddl source code can be checked out from GitHub using this command:

git clone https://github.com/codecraftingtools/cuddl.git

Linux Installation

This section applies to all Linux-based systems, including those using Xenomai.

Setting Up Device Permissions

In order for Linux UIO devices and Cuddl devices to be accessible to non-root users, the desired permissions must be established by providing a udev rules file. This can be accomplished by creating a new file named (e.g.) 99-cuddl.rules in the /etc/udev/rules.d/ directory with the following content:

KERNEL=="uio*", MODE="0660", GROUP="sudo"
SUBSYSTEM=="cuddl*", MODE="0660", GROUP="sudo"

The GROUP may be changed to something more suitable, if desired. On Xenomai systems, for example, the following rules are probably more appropriate:

KERNEL=="uio*", MODE="0660", GROUP="xenomai"
SUBSYSTEM=="cuddl*", MODE="0660", GROUP="xenomai"

On Xenomai systems, the UDD / RTDM device nodes should already be set up for access by users in the xenomai group, but the above step must still be performed to allow access to the Cuddl manager and janitor device nodes.

Building the Kernel Modules

The cuddl.ko, cuddl_manager.ko, and cuddl_janitor.ko kernel modules can be built by executing the following commands from the root directory of the cuddl source tree:

cd kernel/linux
make

Note that verbose build output may be shown by running make V=1 instead of make. For more details on building out-of-tree kernel modules, you can refer to the official kernel.org documentation.

If you want to clean up the generated files so that you can recompile everything from scratch, you can run this command in the kernel/linux subdirectory

make clean

Inserting the Kernel Modules

If the UIO subsystem in the Linux kernel you are running was configured as a module, you will need to insert it before attempting to insert the Cuddl modules:

sudo modprobe uio

Similarly, if you are running a Xenomai kernel with UDD configured as a module, you will need to insert it as well:

sudo modprobe xeno_udd

Now you can insert the Cuddl kernel modules that were built in a previous step by executing the following commands from the kernel/linux subdirectory in this order:

sudo insmod cuddl.ko
sudo insmod cuddl_manager.ko
sudo insmod cuddl_janitor.ko

After inserting (or attempting to insert) kernel modules, you may want to inspect the kernel ring buffer for any warning or informational messages that may be relevant. You can run a command like this to see the last few messages:

dmesg | tail -n 40

or you can run this command in a separate terminal to get updates on-the-fly:

dmesg -w

Note

Kernel modules can be removed from the running kernel using the rmmod command:

sudo rmmod cuddl_janitor cuddl_manager cuddl

Note that multiple kernel modules may be specified, and that the .ko file extension is omitted for each module. Also note that this command can be run from any directory (i.e. the .ko don’t need to be present).

Setting up Modprobe

Manually loading the required kernel modules in the correct order (as demonstrated above) can be tedious and error prone. Thankfully, the Linux kernel developers have provided a way to automatically load a module’s dependencies automatically. This does, however, require a little bit of setup.

The first step is to determine the kernel release we are running:

uname -r

The result should be something like 5.4.0-117-generic.

The next step is to create a subdirectory to hold our new out-of-tree modules under the corresponding system /lib/modules directory:

sudo mkdir /lib/modules/5.4.0-117-generic/kernel/cuddl

or, more elegantly:

sudo mkdir /lib/modules/`uname -r`/kernel/cuddl

Next, copy the modules we built into this new directory:

sudo cp *.ko /lib/modules/`uname -r`/kernel/cuddl

Now adjust the permissions:

sudo chmod -R o+rX /lib/modules/`uname -r`/kernel/cuddl

Finally, run depmod to re-compute the module dependencies for the running kernel:

sudo /sbin/depmod -a

Now you should be able to load our new out-of-tree kernel modules using modprobe:

sudo modprobe cuddl_janitor

Note that this command can be run from any directory, that the .ko extension is not specified, and any prerequisite kernel modules are automatically loaded (i.e. cuddl_manager, cuddl, and uio in this case).

The modprobe command can also be used to remove a module, along with any prerequisite kernel modules that are no longer being used:

sudo modprobe -r cuddl_janitor

Loading Modules on Boot

When deploying a set of user-space device drivers to an operational system, you probably want them to be automatically loaded when the system boots up. This can be achieved by creating a new file named (e.g.) cuddl.conf in the /etc/modules-load.d/ directory with content like this:

cuddl_janitor
other_module_1
other_module_2

The format is simply the name of the modules to be loaded, one per line. Note that dependencies should be loaded automatically, like with modprobe.

Building a User-Space Application

There are currently no makefiles or build scripts provided for the Cuddl user-space code, so users will need to compile and link the required source files into their applications manually.

Assuming that cuddl_DIR is set to the root directory of the Cuddl source repository, the following include directories should be added to the C-preprocessor search path:

$(cuddl_DIR)/user/include
$(cuddl_DIR)/common/include

The following source files also need to be compiled and linked with the application:

$(cuddl_DIR)/user/src/cuddl_linux.c

For Xenomai applications, the Cuddl source files need to be compiled and linked with the appropriate flags (as supplied by xeno-config).

In order to get a meaningful result from cuddl_get_userspace_commit_id(), the following c-preprocessor flags need to be added:

-DCUDDLI_COMMIT_HASH=\"`git -C $(cuddl_DIR) rev-parse HEAD`\"
-DCUDDLI_REPO_IS_DIRTY=`git -C $(cuddl_DIR) diff --quiet HEAD && echo 0 || echo 1`

Otherwise, the result will yield "UNKNOWN".

RTEMS Installation

RTEMS support has not yet been implemented.

Building the Documentation

HTML documentation for this project may be generated from the reStructuredText source files in the project’s doc subdirectory using the Sphinx documentation tool.

These instructions describe how to set up a working Sphinx installation:

Once you have activated the virtual Python environment and installed the required Sphinx extensions and system packages, the Cuddl documentation can be built by executing the following command in the doc subdirectory of the cuddl source tree:

make html

You may then open the resulting top-level HTML file in a web browser:

_build/html/index.html

The generated documentation files may be removed by running:

make clean