Circle

Overview

Circle is a C++ bare metal programming environment for the Raspberry Pi. It should be usable on all existing models (tested on model A+, B, B+, on Raspberry Pi 2, 3, 4, 400 and on Raspberry Pi Zero), except on the Raspberry Pi Pico, which is not supported. Circle provides several ready-tested C++ classes and add-on libraries, which can be used to control different hardware features of the Raspberry Pi. Together with Circle there are delivered several sample programs, which demonstrate the use of its classes. Circle can be used to create 32-bit or 64-bit bare metal applications.

Circle includes bigger (optional) third-party C-libraries for specific purposes in addon/ now. This is the reason why GitHub rates the project as a C-language-project. The main Circle libraries are written in C++ using classes instead. That's why it is called a C++ programming environment.

Release 45.2

This release provides many enhancements and fixes for the USB audio streaming support for Raspberry Pi 4, 400 and Compute Module 4. USB audio interfaces with 16-bit or 24-bit wide samples with up to 32 channels are supported now. You have to specify the option soundopt=24 in the file cmdline.txt to select 24-bit wide samples and the option usbsoundchannels=TX,RX to select a specific number of output (TX) and input (RX) channels. See the file cmdline.txt for more info on this option. You can call the methods GetHWTXChannels() and GetHWRXChannels() of a sound device driver class to request the number of available hardware channels in your application now.

Please note that an application, which uses the alternate sound interface and wants to use USB audio streaming support with 24-bit wide samples, has to implement the method unsigned GetChunk(u32 *pBuffer, unsigned nChunkSize), were each sample occupies 3 bytes. The class CUSBSoundBaseDevice must be instantiated, when the USB host controller driver has been initialized already. Therefore you cannot do this in the constructor of CKernel and must create the driver object later using the new operator.

There is support for the Raspberry Pi Camera Modules 1 and 2 now in the external project libcamera.

Further improvements:

• The LVGL submodule has been updated to version 8.3.7. The CLVGL wrapper class has been updated for better performance and compatibility with LVGL.
• The FatFs submodule has been updated to release R0.15 with patch 1 and 2.
• The support for USB serial interfaces has been extended for more CP210x family devices.
• Support for Ctrl+navigation key combinations for USB keyboard devices in cooked mode has been added.
• Support for rotated and/or mirrored display for SSD1306-based dot-matrix displays has been added.
• A C2DGraphics::DrawText() method for displaying text with 2D graphics has been added.
• gzip-compressed kernel images (supported for 64-bit kernels only) can be generated by defining GZIP_KERNEL = 1 in Config.mk now.

Bug fixes:

• DMA4 (DMA_CHANNEL_EXTENDED) memory-to-memory transfers sometimes failed.
• C2DGraphics::DrawImageRect() used display stride instead of image stride.

The recommended firmware has been updated and can be downloaded in boot/. It is now always recommended to copy the file config32.txt (AArch32) or config64.txt (AArch64) from the boot/ directory to the SD card and to rename it to config.txt there.

The recommended toolchain is based on GCC 12.2.1 now. You can download it using the link in the Building section below. With this toolchain the system options SAVE_VFP_REGS_ON_IRQ and SAVE_VFP_REGS_ON_FIQ are enabled by default in any case now.

Please note that it is checked on start-up now, if the system option KERNEL_MAX_SIZE is properly set. If the given value (default 2 MByte) is too small, the system does not boot.

The 45th Step

This release comes with support for USB audio streaming devices, available for Raspberry Pi 4, 400 and Compute Module 4 only. Supported should be devices, which are compliant with the "USB Device Class Definition for Audio Devices", Release 1.0 and 2.0. Only USB audio interfaces with 16-bit PCM audio and two channels (Stereo) are supported for output and input, and additionally with one channel (Mono) for input. There is no constant chunk size for USB sound devices and it is not configurable here. You should enable the system option REALTIME for applications, which use USB sound. Some devices also may require the option usbpowerdelay=1000 in the file cmdline.txt to enumerate successfully.

USB audio streaming devices often support multiple jacks for output and input and some method was required to select them. Furthermore these devices have Feature Units, which allow to set the volume for different audio channels or to mute the whole signal. Before there was no common API for such functions. This release adds the new feature of a sound controller for that purpose, which is provided by the class CSoundController. A pointer to the sound controller of an existing sound device (derived from the class CSoundBaseDevice) can be requested by calling GetController() on its device object. See the Circle documentation for more information.

Please note that the sound controller is optional and currently only the following sound devices implement it: CUSBSoundBaseDevice, CI2SSoundBaseDevice (for PCM512x-based devices), CVCHIQSoundBaseDevice. Because implementations of sound controllers for new devices are expected in the future, which provide additional audio functions, the sound controller API may be extended or modified in coming releases.

The sound support has been moved from the base library to the new library lib/sound/libsound.a with the header files in include/circle/sound/ (instead of include/circle/). If your application uses sound, you have to add the sound library to the LIBS variable in the Makefile and to update some #include statements for the sound classes.

The samples 29-miniorgan, 34-sounddevices and 42-soundinput (former 42-i2sinput) have been updated to use USB audio streaming devices. The samples 29 and 42 also demonstrate functions of the sound controller. The sound recorder in sample 42 generates compatible .wav files now. The default sample rate for these samples is 48000 Hz now, because it is supported by most USB sound cards. The new test sound-controller may also be of interest for trying several sound features and the sound controller.

There is a new method CDevice::UnregisterRemovedHandler() for undoing the registration of device remove handlers. Calling CDevice::RegisterRemovedHandler() with a nullptr for this purpose does not work any more. There can be multiple device remove handlers for one device now.

Further improvements:

• The LVGL submodule has been updated to version 8.3.3.
• The FatFs submodule has been updated with two recent patches. Furthermore it supports the function f_mkfs() for USB mass-storage devices now. This requires the FatFs option FF_USE_MKFS to be enabled in addon/fatfs/ffconf.h.
• There is a new driver for SSD1306-based displays in addon/display/.
• The new system option USE_LOG_COLORS can be defined to use different ANSI colors for different severities in the system log.

Bug fixes:

• Reading the USB HID report descriptor for int3-0-0 devices did fail on some devices, when they were not configured yet. The USB HID support was not usable on these devices before.
• Some USB MIDI controllers use an USB interrupt endpoint for reporting MIDI events, instead of a bulk endpoint. These devices were not usable before.
• The serial bootloader "Flashy" did not work with the Bluetooth modules HC-05/-06.

This release has been built with a new recommended toolchain, which comes from a new webpage. See the link in the Building section below.

With this release a number of Circle applications can be built using Clang/LLVM. Please see doc/clang-support.txt for details. This support is currently experimental.

Don't forget to update the used firmware to the one downloadable in boot/!

Features

Circle supports the following features:

Building

For building 64-bit applications (AArch64) see the next section.

This describes building on PC Linux. See the file doc/windows-build.txt for information about building on Windows. If building for the Raspberry Pi 1 you need a toolchain for the ARM1176JZF core (with EABI support). For Raspberry Pi 2/3/4 you need a toolchain with Cortex-A7/-A53/-A72 support. A toolchain, which works for all of these, can be downloaded here. Circle has been tested with the version 12.2.Rel1 (arm-gnu-toolchain-12.2.rel1-x86_64-arm-none-eabi.tar.xz) from this website.

First edit the file Rules.mk and set the Raspberry Pi version (RASPPI, 1, 2, 3 or 4) and the PREFIX of your toolchain commands. Alternatively you can create a Config.mk file (which is ignored by git) and set the Raspberry Pi version and the PREFIX variable to the prefix of your compiler like this (don't forget the dash at the end):

RASPPI = 1
PREFIX = arm-none-eabi-

The following table gives support for selecting the right RASPPI value:

For a binary distribution you should do one build with RASPPI = 1, one with RASPPI = 2 and one build with RASPPI = 4 and include the created files kernel.img, kernel7.img and kernel7l.img. Optionally you can do a build with RASPPI = 3 and add the created file kernel8-32.img to provide an optimized version for the Raspberry Pi 3.

The configuration file Config.mk can be created using the configure tool too. Please enter ./configure -h for help on using it!

There are a number of configurable system options in the file include/circle/sysconfig.h. Please have a look into this file to learn, how you can configure Circle for your purposes. Some hardware configurations may require modifications to these options (e.g. using USB on the CM4).

Then go to the build root of Circle and do:

./makeall clean
./makeall

By default only the latest sample (with the highest number) is build. The ready build kernel.img file should be in its subdirectory of sample/. If you want to build another sample after makeall go to its subdirectory and do make.

You can also build Circle on the Raspberry Pi itself (set PREFIX = (empty)) on Raspbian but you need some method to put the kernel.img file onto the SD(HC) card. With an external USB card reader on model B+ or Raspberry Pi 2/3/4 model B (4 USB ports) this should be no problem.

AArch64

Circle supports building 64-bit applications, which can be run on the Raspberry Pi 3 or 4. There are also Raspberry Pi 2 versions and the Raspberry Pi Zero 2, which are based on the BCM2837 SoC. These Raspberry Pi versions can be used too (with RASPPI = 3).

The recommended toolchain to build 64-bit applications with Circle can be downloaded here. Circle has been tested with the version 12.2.Rel1 (arm-gnu-toolchain-12.2.rel1-x86_64-aarch64-none-elf.tar.xz) from this website.

There are distro-provided toolchains on certain Linux platforms (e.g. g++-aarch64-linux-gnu on Ubuntu or gcc-c++-aarch64-linux-gnu on Fedora), which may work with Circle and can be a quick way to use it, but you have to test this by yourself. If you encounter problems (e.g. no reaction at all, link failure with external library) using a distro-provided toolchain, please try the recommended toolchain (see above) first, before reporting an issue.

First edit the file Rules.mk and set the Raspberry Pi architecture (AARCH, 32 or 64) and the PREFIX64 of your toolchain commands. The RASPPI variable has to be set to 3 or 4 for AARCH = 64. Alternatively you can create a Config.mk file (which is ignored by git) and set the Raspberry Pi architecture and the PREFIX64 variable to the prefix of your compiler like this (don't forget the dash at the end):

AARCH = 64
RASPPI = 3
PREFIX64 = aarch64-none-elf-

The configuration file Config.mk can be created using the configure tool too. Please enter ./configure -h for help on using it!

Then go to the build root of Circle and do:

./makeall clean
./makeall

By default only the latest sample (with the highest number) is build. The ready build kernel8.img or kernel8-rpi4.img file should be in its subdirectory of sample/. If you want to build another sample after makeall go to its subdirectory and do make.

Installation

Copy the Raspberry Pi firmware (from boot/ directory, do make there to get them) files along with the kernel*.img (from sample/ subdirectory) to a SD(HC) card with FAT file system.

It is now always recommended to copy the file config32.txt (for 32-bit mode) or config64.txt (for 64-bit mode) from the boot/ directory to the SD(HC) card and to rename it to config.txt there. These files are especially required to enable FIQ use on the Raspberry Pi 4. Furthermore the additional file armstub7-rpi4.bin (for 32-bit mode) or armstub8-rpi4.bin (for 64-bit mode) is required on the SD card then. Please see boot/README for information on how to build these files.

Finally put the SD(HC) card into the Raspberry Pi.

Directories

• include: The common header files, most class headers are in the include/circle/ subdirectory.
• lib: The Circle class implementation and support files (other libraries are in subdirectories of lib/).
• sample: Several sample applications using Circle in different subdirectories. The main function is implemented in the CKernel class.
• addon: Contains contributed libraries and samples (has to be build manually).
• app: Place your own applications here. If you have own libraries put them into app/lib/.
• boot: Do make in this directory to get the Raspberry Pi firmware files required to boot.
• doc: Additional documentation files.
• test: Several test programs, which test different features of Circle.
• tools: Tools for building Circle and for using Circle more comfortable (e.g. a serial bootloader).

Classes

The following C++ classes were moved in Circle:

Base library -> Sound library (new)

• CDMASoundBuffers: Concatenated DMA buffers to be used by sound device drivers
• CHDMISoundBaseDevice: Low level access to the HDMI sound device (without VCHIQ)
• CI2SSoundBaseDevice: Low level access to the I2S sound device
• CPWMSoundDevice: Using the PWM device to playback sound samples in different formats
• CPWMSoundBaseDevice: Low level access to the PWM device to generate sounds on the headphone jack
• CSoundBaseDevice: Base class of sound devices, converts several sound formats

The following C++ classes were added to Circle:

USB library

• CDWHCIFrameSchedulerIsochronous: Schedules the transmission of isochronous split-frames
• CUSBAudioControlDevice: Driver for USB audio control devices
• CUSBAudioFunctionTopology: Topology parser for USB audio class devices
• CUSBAudioStreamingDevice: Low-level driver for USB audio streaming devices

Sound library (new)

• CPCM512xSoundController: Sound controller for PCM512x
• CSoundController: Optional controller of a sound device
• CUSBSoundBaseDevice: High-level driver for USB audio streaming devices
• CUSBSoundController: Sound controller for USB sound devices
• CWM8960SoundController: Sound controller for WM8960

The available Circle classes are listed in the file doc/classes.txt. If you have Doxygen installed on your computer you can build a class documentation in doc/html/ using:

./makedoc

At the moment there are only a few classes described in detail for Doxygen.

Additional Topics

• Standard library support
• Dynamic memory management and the "new" operator
• DMA buffer requirements
• Serial bootloader support
• Multi-core support
• USB plug-and-play
• Debugging support
• JTAG debugging
• QEMU support
• Eclipse IDE support
• About real-time applications
• cmdline.txt options
• Screen escape sequences
• Keyboard escape sequences
• Clang support
• Memory layout
• Naming conventions
• Known issues

Trademarks

Raspberry Pi is a trademark of Raspberry Pi Ltd.

Linux is a trademark of Linus Torvalds.

PS3 and PS4 are registered trademarks of Sony Computer Entertainment Inc.

Windows, Xbox 360 and Xbox One are trademarks of the Microsoft group of companies.

Nintendo Switch is a trademark of Nintendo.

Khronos and OpenVG are trademarks of The Khronos Group Inc.

OpenGL ES is a trademark of Silicon Graphics Inc.

The micro:bit brand belongs to the Micro:bit Educational Foundation.

HDMI is a registered trademark of HDMI Licensing Administrator, Inc.