Repository files navigation

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, 5 and on Raspberry Pi Zero), except on the Raspberry Pi Pico, which is not supported. 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 release comes withUSB mass-storage device gadget support.test/usb-msd-gadget shows, how this can be used to provide direct access to the SD card via USB. Furthermore this version supportsHDMI sound for the Raspberry Pi 5. The sound samples and tests have been updated to use this. TheRaspberry Pi 5 with BCM2712 stepping D0 is supported. TheLVGL support has been updated toversion 9.2.0.

The network library has been updated to support the receiving of ICMP packets in applications. This is used intest/ping-client to implement aping client. Raspberry Pi models without an on-board Ethernet NIC can be used withRTL8152 and RTL8153 USB Ethernet adapters to access a network.

The platformDMA controller drivers supportcyclic write transfers now. To implement this, it was necessary to extend the typeTDMACompletionRoutine by a buffer index. If you directly use DMA transfers in your application, you have to update your DMA completion routine.

There is a complete rewrite of the Flashyserial bootloader tool in C, which is called cFlashy and which does not need a Node-JS environment any more. You can defineUSEFLASHY=0 in the fileConfig.mk to enable it. Seedoc/bootloader.txt for details.

More news:

• A classCmDNSPublisher was added, which can be used to publish services to mDNS (aka Bonjour) in a local network. Seetest/mdns-publisher for an example.
• There is a new optionbacklight= forcmdline.txt for setting the backlight level for the Official 7" Raspberry Pi touchscreen. For some versions of this touchscreen this option is required.
• The classCSerialDevice now supports modifying the parity setting (including a mark or space parity) and a per character receive for specific RS-485 applications.
• A block cursor can be enabled on the screen usingCScreenDevice::SetCursorBlock(). Seetest/screen-ansi-colors for an example.
• The SD card driver implements theGetSize() method now.
• Only serious USB transaction errors are logged on Raspberry Pi 1-3 any more.
• The new doc filedoc/debug-swd.txt explains SWD debugging on the Raspberry Pi 5 using the Raspberry Pi Debug Probe adapter.

Fixes:

• Only 4 GB RAM were usable, even on Raspberry Pi 5 with 8 GB RAM.
• The MAC address for WLAN access is read from the device tree on the Raspberry Pi 5 now, as it is required. Before always the same address was used.
• The Official 7" Raspberry Pi touchscreen did not work with circle-stdlib.
• The MQTT client delivered an invalid payload inOnMessage(), when there were multiple MQTT publish messages arriving in one network packet.
• The access to USB bulk endpoints on the Raspberry Pi 1-3 in no-hub configurations was occupying the whole USB bandwidth, which was not allowing to access other endpoints on the same USB device.
• The I2C master was not initialized on the Raspberry Pi 5 insample/34-sounddevices.

The recommended firmware version has been updated and is required to use the Raspberry Pi 5 with BCM2712 stepping D0. Please note that the filebcm2712d0.dtbo has to be copied into the directoryoverlays/ on the SD card.

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:

USB gadget library

• CUSBMSDGadget: USB mass storage device gadget
• CUSBMSDGadgetEndpoint: Endpoint of the USB mass storage gadget

Net library

• CmDNSPublisher: mDNS / Bonjour client task

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.