Repository files navigation

Circle is a C++ bare metal programming environment for the Raspberry Pi. It should be usable on most existing models (tested on model A+, B, B+, on Raspberry Pi 2, 3, 4, 400, 5 and on Raspberry Pi Zero (2)), except on the Raspberry Pi Pico, which is not supported. It is not known, if it works on the Raspberry Pi 500 and on Compute Module 5. Circle provides several ready-testedC++ classes andadd-on libraries, which can be used to control different hardware features of the Raspberry Pi. Together with Circle there are delivered severalsample 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.

This hotfix release solves the following issues:

• Download of firmware files in boot/ did not work any more.
• LVGL library in addon/lvgl/ did not build on Windows.
• "fgrep is obsolescent" warnings appeared on newer build host systems.

This release comes with an improved dot-matrix display management. All driver classes for dot-matrix displays should be derived from the classCDisplay now. The old character display support for ST7789- and SSD1306-based displays is still available, but will be deprecated in a future version. Instead there is the new classCTerminalDevice, which implements a scrolling character terminal display for any display driver, which is derived fromCDisplay. This class is also used to implement the classCScreenDevice now for the known terminal display on a firmware-driven frame buffer device. The following displays are currently supported byCDisplay-derived driver classes:

• Firmware-driven frame buffer (CBcmFrameBuffer)
• ST7789 SPI display (CST7789Display)
• SSD1306 I2C display (CSSD1306Display)
• ILI9341 SPI display (CILI9341Display)

Beside the terminal support also the 2D graphics (C2DGraphics) and LVGL (CLVGL) support have been updated to work with all these displays. The 2D graphics support works with logical colors (T2DColor) now. There is a new classC2DImage, which manages the color conversion from logical to physical colors for 2D sprite images.

Classes, which support the displaying of text on dot-matrix displays, allow the selection of the used font now. The default system font can by defined with system optionDEFAULT_FONT.

There is a new classCWindowDisplay, which allows to use multiple non-overlapping windows on a dot-matrix display. This is demonstrated in the multi-core programsample/43-multiwindow.

sample/08-usbkeyboard,sample/41-screenanimations andaddon/lvgl/sample have been updated for the new display management and support SPI and I2C displays too.

There are a number of API breaking changes for the new display support, which are listed inthis article.

More news:

• The external PCIe bus of the Raspberry Pi 5 can be accessed using the classCBcmPCIeHostBridge now. See thetest/pcie-external for details. Interrupts from the external PCIe bus are available via the INTA pin at the IRQ numberARM_IRQ_PCIE_EXT_HOST_INTA.
• A driver for XPT2046-based touchscreens has been added. Seetest/xpt2046-touchscreen for details.
• The FatFs support has been updated to R0.15a + patch1.
• The LVGL support has been updated to v9.2.2.
• DMA channels are usable in different modes now. Before a DMA channel, which has been used for an asynchronous transfer, could not be used for synchronous transfers afterwards without re-initialization. The completion routine has to be set prior to each asynchronous transfer now.

Fixes:

• The detection of WM8960-based I2S codecs did not work, when the I2C address was explicitly specified.
• Commit ae00d9d8 in Step48 was leading to lost MIDI events with USB MIDI devices on the Raspberry Pi 1-3 and has been reverted. In the rare case that you are using an USB device, which has a MIDI interface and an other (e.g. HID) interface, and the device is directly connected to the root port without USB hub in-between (e.g. on Raspberry Pi Zero), you have to define the system optionUSE_NAK_USB_FIX now.
• The MQTT client might have crashed after receiving a disconnect from peer before.
• The check for the length, opcode and block number of incoming ACK packets in the TFTP daemon used an invalid logical operator. This could have caused receiving invalid files on read requests.
• The HideLink THEC64 USB keyboard did not work before.
• The initial LVGL mouse cursor was not centered on the Raspberry Pi 5.
• Theconfigure script and cFlashy can be used on macOS now. cFlashy caused a build error before on macOS.

The recommended firmware version has been updated. The optioninitial_turbo=0 has been added to the fileconfig.txt, because newer firmware versions enableinitial_turbo=60 by default now, which can disturb the Circle device initialization.

Only the features with a "x" or other info are currently supported on the Raspberry Pi 5.

Circle supports the following features:

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

Circle does not support 32-bit applications on the Raspberry Pi 5.

This describes building on PC Linux. See the filedoc/windows-build.txt for information about building on Windows. If building for the Raspberry Pi 1 you need atoolchain 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 downloadedhere. Circle has been tested with the version13.2.Rel1 (arm-gnu-toolchain-13.2.rel1-x86_64-arm-none-eabi.tar.xz) from this website. This is the recommended toolchain for AArch32 builds.

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

RASPPI = 1PREFIX = arm-none-eabi-

The following table gives support for selecting the rightRASPPI value:

For a binary distribution you should do one build withRASPPI = 1, one withRASPPI = 2 and one build withRASPPI = 4 and include the created fileskernel.img,kernel7.img andkernel7l.img. Optionally you can do a build withRASPPI = 3 and add the created filekernel8-32.img to provide an optimized version for the Raspberry Pi 3.

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

There are a number of configurable system options in the fileinclude/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 Circle libraries are built. To build a sample program aftermakeall go to its subdirectory and domake.

You can also build Circle on the Raspberry Pi itself (setPREFIX = (empty)) on Raspbian but you need some method to put thekernel.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.

Circle supports building 64-bit applications, which can be run on the Raspberry Pi 3, 4 or 5. 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 (withRASPPI = 3).

The recommended toolchain to build 64-bit applications with Circle can be downloadedhere. Circle has been tested with the version13.2.Rel1 (arm-gnu-toolchain-13.2.rel1-x86_64-aarch64-none-elf.tar.xz) from this website. This is the recommended toolchain for AArch64 builds.

There are distro-provided toolchains on certain Linux platforms (e.g.g++-aarch64-linux-gnu on Ubuntu orgcc-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 fileRules.mk and set the Raspberry Pi architecture (AARCH, 32 or 64) and thePREFIX64 of your toolchain commands. TheRASPPI variable has to be set to 3, 4 or 5 forAARCH = 64. Alternatively you can create aConfig.mk file (which is ignored by git) and set the Raspberry Pi architecture and thePREFIX64 variable to the prefix of your compiler like this (don't forget the dash at the end):

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

The configuration fileConfig.mk can be created using theconfigure 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 Circle libraries are built. To build a sample program aftermakeall go to its subdirectory and domake.

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

It is now always recommended to copy the fileconfig32.txt (for 32-bit mode) orconfig64.txt (for 64-bit mode) from the boot/ directory to the SD(HC) card and to rename it toconfig.txt there. These files are especially required to enable FIQ use on the Raspberry Pi 4. Furthermore the additional filearmstub7-rpi4.bin (for 32-bit mode) orarmstub8-rpi4.bin (for 64-bit mode) is required on the SD card then. Please seeboot/README for information on how to build these files.

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

• 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: Domake 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).

The following C++ classes were added to Circle:

Base library

• CDisplay: Base class for dot-matrix display drivers
• CTerminalDevice: Terminal support for dot-matrix displays
• CWindowDisplay: Non-overlapping window on a display

USB library

• CUSBFloppyDiskDevice: Driver for USB floppy disk devices (CBI transport)

Input library

• CXPT2046TouchScreen: Driver for XPT2046-based touch screens

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

./makedoc

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

• 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
• SWD debugging (Raspberry Pi 5)
• 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

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.