About mode switches

Understanding them and avoiding them

Mode switches are occurrences which tend to interfere with the function of Bela.

This page explains what mode switches are, how to watch for them, and how to address them if they occur.

Table of contents

1. What is a mode switch?
2. What’s the impact of a mode switch?
3. What causes mode switches?
4. How can I tell if mode switches are happening?
5. How can I address a mode switch?

What is a mode switch?

A mode switch occurs when a process switches ‘modes’, from primary to secondary and back again.

Bela uses the Xenomai Linux library to execute code in hard real time. This means that anything on the audio thread – generally, code inside the render() function – is executed at a higher priority than anything else the system may be doing. This is called primary mode.

Things that the Linux system does outside the audio thread (such as connecting to wifi, printing, reading from the SD card, and so on) are executed in secondary mode. The distinction between these two modes is that primary mode always happens before secondary mode.

A mode switch happens when something on your audio thread (executing in primary mode) is a core Linux function, and is therefore executed in secondary mode. After this happens, the mode of execution changes back to primary mode so the real-time operations can continue. In other words, the mode is switched.

What’s the impact of a mode switch?

The impact of a mode switch is that the audio task you’ve defined in your render() function temporarily drops its real-time privileges, during which time other system processes can take higher priority. This tends to lead to underruns in the audio stream.

In other words, this means that things don’t execute as quickly as they need to. This can cause audio irregularities, sensor processing problems, or can cause the system to stop altgoether.

What causes mode switches?

A mode switch happens when something executing in primary mode relies on the Linux kernel. Many common functions rely on the Linux kernel, including file I/O, networking, USB, getting the clock time, printing to the console.

The most common cause of mode switches is printing a value to the console too often, such as every audio or analog frame. There are 44,100 audio frames per second and 22,050 analog frames per second - that’s a lot of switching!

How can I tell if mode switches are happening?

The IDE has a built-in function for looking for mode switches. It’s enabled by default, and you can turn it off or on in the right tab menu in Settings > IDE Settings > Mode switch monitoring.

How can I address a mode switch?

There are a few ways.

1. Look for system calls on your audio thread.

Are you printing too often? Try printing a few times a second if you need to see values, instead of every frame. Are you accessing files on your SD card? Consider how you might do this less often.

1. Use the built-in AuxiliaryTask() functions to handle anything requiring the Linux system.

Link to aux task things in the reference

---