If you read this file in an editor you should switch line wrapping on.

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 and on Raspberry Pi Zero). It 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 named a C++ programming environment.

This intermediate release comes with some new features, improvements in detail and fixes. For the Raspberry Pi 4 now the four additional peripheral devices each are supported for I2C master, SPI master and UART. The SPI slave is supported too on the latest Raspberry Pi model now.

Time has been spent to improve the network library. The ARP problem, which caused a delayed start of network transmissions, has been solved. ARP requests are retried now if necessary and the first packet sent in a new connection after reboot is not discarded any more. ICMP handling has been improved too. The DHCP client sends an configurable host name (default "raspberrypi") now in requests, so that the DHCP server can add a DNS entry for your Raspberry Pi, if it this enabled in the server.

There is a new software profiling support library in addon/profile for single core applications. The file gmon.out, which is generated by the software profiling library, is compatible with the gprof tool.

Previously a CMemorySystem object had to be instanced as first member of CKernel with STDLIB_SUPPORT < 2 to be able to configure MMU usage by the application. This caused several problems. Newer compilers may generate code in the early stages, which does not work without MMU. Also constructors of static objects were called with MMU off before. Now that the CMemorySystem object is constructed early, these problems will be solved and all applications run with MMU on. For compatibility it is not a problem, if the application constructs a second instance of CMemorySystem in CKernel. It is used as an alias for the first instance.

The documentation generated by Doxygen with ./makedoc has been improved by integrating and linking available documentation files. Important class definitions from the addon/ subdirectory are included in the generated documentation now.

The following issues have been fixed:

• The BCM54213PE Gigabit Ethernet driver for the Raspberry Pi 4 did not reset the device properly. This caused some heavy re-transmissions of frames after chain boot (e.g. with sample/38-bootloader).

• AArch64 FIQ support did not initialize or close properly on Raspberry Pi 4 in some cases.

• It turned out, that the PWM audio channel outputs are swapped on some Raspberry Pi models. This will be considered automatically now. If you have implemented your own PWM audio driver, you can request from the CMachineInfo class, if the channels are swapped.

• Multi-core applications might have freezed when calling CSocket::Connect().

• CNTPDaemon did only save a pointer to the host name of the NTP server before. This might have caused problems, if the string buffer disappeared after returning from the constructor.

With this release Circle supports nearly all features on the Raspberry Pi 4, which are known from earlier models. Only OpenGL ES / OpenVG / EGL and the I2C slave support are not available.

On Raspberry Pi 4 models with over 1 GB SDRAM Circle provides a separate HEAP_HIGH memory region now. You can use it to dynamically allocate memory blocks with new and malloc() as known from the low heap. Both heaps can be configured to form a larger unified heap using a system option. Please read the file doc/new-operator.txt for details about using and configuring the heaps.

The new sample/39-umsdplugging demonstrates how to use CUSBHCIDevice::RescanDevices() and CDevice::RemoveDevice() to be able to attach USB mass-storage devices (e.g. USB flash drives) and to remove them again on application request without rebooting the system.

Some support for the QEMU semihosting interface has been added, like the possibility to exit QEMU on halt(), optionally with a specific exit status (set_qemu_exit_status()). This may be used to automate tests. There is a new class CQEMUHostFile, which allows reading and writing files (including stdin / stdout) on the host system, where QEMU is running on. See the directory addon/qemu/, the new sample in addon/qemu/hostlogdemo/ and the file file doc/qemu.txt for info on using QEMU with Circle with the semihosting API.

The Circle build system checks dependencies of source files with header files now and automatically rebuilds the required object files. You will not need to clean the whole project after editing a header file any more. You have to append the (last) line -include $(DEPS) to an existing Makefile to enable this feature in your project. The dependencies check may be globally disabled, by defining CHECK_DEPS = 0 in Config.mk.

If you want to modify a system option in include/circle/sysconfig.h, explicitly changing this file is not required any more, which makes it easier to include Circle as a git submodule. All system options can be defined in Config.mk this way:

DEFINE += -DARM_ALLOW_MULTI_CORE
DEFINE += -DNO_CALIBRATE_DELAY

Finally a project file for the Geany IDE is provided in tools/template/. The recommended toolchain is based on GNU C 9.2.1 now. As announced the Bluetooth support has been removed for legal reasons.

Circle supports the following features:

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

Building is normally done on PC Linux. 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 9.2-2019.12 (gcc-arm-9.2-2019.12-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.

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.

Building Circle from a non-Linux host is possible too. Maybe you have to adapt the shell scripts in this case. You need a cross compiler targetting (for example) arm-none-eabi. OSDev.org has an excellent document on the subject that you can follow if you have no idea of what a cross compiler is.

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

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

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-

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.

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. Put the SD(HC) card into the Raspberry Pi.

The config.txt file, provided in the boot/ directory, is only needed to enable 64-bit mode and has to be copied on the SD card in this case. It must not be on the SD card otherwise!

FIQ support for AArch64 on the Raspberry Pi 4 requires an additional file armstub8-rpi4.bin on the SD card. Please see boot/README for information on how to build this file.

• 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.
• tools: Some tools for using Circle more comfortable (e.g. a serial bootloader).

The following C++ classes have been added to Circle:

Base library

• CHeapAllocator: Allocates blocks from a flat memory region.
• CPageAllocator: Allocates aligned pages from a flat memory region.

USB library

• CXHCISharedMemAllocator: Shared memory allocation for the xHCI driver.

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.

• Standard library support
• Dynamic memory management and the "new" operator
• Serial bootloader support
• Multi-core support
• Debugging support
• QEMU support
• Eclipse IDE support
• About real-time applications
• cmdline.txt options
• Screen escape sequences
• Keyboard escape sequences
• Memory layout
• Known issues

Raspberry Pi is a trademark of the Raspberry Pi Foundation.

Linux is a trademark of Linus Torvalds.

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

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.