Miosix Wiki - User contributions [en]

Miosix processes

2026-05-17T07:33:18Z

Fede.tft:

TODO: this part needs better documenting.

A complete example for running processes can be found in [https://github.com/fedetft/miosix-kernel/tree/master/templates/processes templates/processes].

To compile it, you have to change the default linker script for your board so that the size of the [[Process pool|process pool]], the memory allocator for processes is greater than zero. This needs to be done in the ''config/board'' directory for your board. For example, for an RP2040 the file is [https://github.com/fedetft/miosix-kernel/blob/master/miosix/config/board/rp2040_raspberry_pi_pico/Makefile.inc config/board/rp2040_raspberry_pi_pico/Makefile.inc].

The linker script is usually simply called processes, and needs to be uncommented while also commenting the default linker script:

<source lang=bash>
## Select linker script
#LINKER_SCRIPT := unikernel.ld
LINKER_SCRIPT := processes.ld
</source>

TODO: explain how the Makefile for the kernel and the one for processes works, and the use of the ''-qkernelspace'' GCC option that has been added by the GCC patches as part of the [[Miosix Toolchain]] to change the code generation and linking stage to either build a position independent code program where the libc links with the libsyscalls (processes), or a non-position-independent code program where kercalls remain undefined references to be resolved at the link stage when linking with the kernel's libmiosix.a. Also explain the need for the postlinking stage (''mx-postlinker'' tool) to specify the size of the RAM memory region of programs, as well as the stack size.

Miosix processes

2026-05-17T07:32:36Z

Fede.tft:

TODO: this part needs better documenting.

A complete example for running processes can be found in [https://github.com/fedetft/miosix-kernel/tree/master/templates/processes templates/processes].

To compile it, you have to change the default linker script for your board so that the size of the [[Process pool|process pool]], the memory allocator for processes is greater than zero. This needs to be done in the ''config/board'' directory for your board. For example, for an RP2040 the file is [https://github.com/fedetft/miosix-kernel/blob/master/miosix/config/board/rp2040_raspberry_pi_pico/Makefile.inc config/board/rp2040_raspberry_pi_pico/Makefile.inc].

The linker script is usually simply called processes, and needs to be uncommented while also commenting the default linker script:

<source lang=bash>
## Select linker script
#LINKER_SCRIPT := unikernel.ld
LINKER_SCRIPT := processes.ld
</source>

TODO: explain how the Makefile for the kernel and the one for processes works, and the use of the ''-qkernelspace'' GCC option that has been added by the GCC patches as part of the [[Miosix toolchain]] to change the code generation and linking stage to either build a position independent code program where the libc links with the libsyscalls (processes), or a non-position-independent code program where kercalls remain undefined references to be resolved at the link stage when linking with the kernel's libmiosix.a. Also explain the need for the postlinking stage (''mx-postlinker'' tool) to specify the size of the RAM memory region of programs, as well as the stack size.

Fluid kernel

2026-05-17T07:32:02Z

Fede.tft:

TODO: the fluid kernel architecture needs to be documented in the wiki.
In the meantime, you can read [https://ieeexplore.ieee.org/document/11173649 the paper].

For a tutorial on [[Miosix processes]] read here.

Main Page

2026-05-17T07:31:16Z

Fede.tft:

The Miosix wiki contains useful information for using the Miosix kernel.

= Getting started =
This section will guide you from zero to compiling an hello world using Miosix.

* [[Linux Quick Start|Getting Started on Linux]].
* [[Windows Quick Start|Getting Started on Windows]].
* [[MacOS Quick Start|Getting Started on MacOS]].

= Software =
* See [[Miosix and git workflow]] to understand how to add Miosix as a dependency to your embedded application.
* Information on [[Debugging]] can be found here.
* Learn about the [[Fluid kernel|fluid kernel]] architecture and how to create programs that can run inside userspace [[Miosix processes|processes]].
* Have a look at the Miosix [[API list|APIs]], [[Library list|libraries]] and [[Examples list|examples]] that you can use for your applications.
* The page on [[Synchronization primitives]] lists the possible ways to shnchronize beween multiple threads or between a thread and an interrupt routine.
* How to [[Miosix code size optimization|reduce the kernel code size]] for deeply embedded applications.
* Notes about configuring [[IDEs]] for Miosix.

= Hardware =
* Check out which microcontroller [[Board list|boards]] are supported by Miosix.
* Notes about flashing tools for [[Linux flashing tools | Linux]], [[Windows flashing tools | Windows]] and [[MacOS flashing tools | MacOS]].
* Notes on [[Miosix in emulation]] with QEMU and Renode.

= Account creation =
Due to spam (within two days from setting up the wiki) account registration is disabled. If you want to create an account, ask to fede.tft&&miosix.org (s/&&/@/)

= Index =
* [[Special:Categories|Categories]]
* [[Special:AllPages|All Pages]]

Miosix processes

2026-05-17T07:29:37Z

Fede.tft: Created page with "TODO: this part needs better documenting. A complete example for running processes can be found in [https://github.com/fedetft/miosix-kernel/tree/master/templates/processes templates/processes]. To compile it, you have to change the default linker script for your board so that the size of the process pool, the memory allocator for processes is greater than zero. This needs to be done in the ''config/board'' directory for your board. For example, for an..."

TODO: this part needs better documenting.

A complete example for running processes can be found in [https://github.com/fedetft/miosix-kernel/tree/master/templates/processes templates/processes].

To compile it, you have to change the default linker script for your board so that the size of the [[Process pool|process pool]], the memory allocator for processes is greater than zero. This needs to be done in the ''config/board'' directory for your board. For example, for an RP2040 the file is [https://github.com/fedetft/miosix-kernel/blob/master/miosix/config/board/rp2040_raspberry_pi_pico/Makefile.inc config/board/rp2040_raspberry_pi_pico/Makefile.inc].

The linker script is usually simply called processes, and needs to be uncommented while also commenting the default linker script:

<code lang=bash>
## Select linker script
#LINKER_SCRIPT := unikernel.ld
LINKER_SCRIPT := processes.ld
</code>

TODO: explain how the Makefile for the kernel and the one for processes works, and the use of the ''-qkernelspace'' GCC option that has been added by the GCC patches as part of the [[Miosix toolchain]] to change the code generation and linking stage to either build a position independent code program where the libc links with the libsyscalls (processes), or a non-position-independent code program where kercalls remain undefined references to be resolved at the link stage when linking with the kernel's libmiosix.a. Also explain the need for the postlinking stage (''mx-postlinker'' tool) to specify the size of the RAM memory region of programs, as well as the stack size.

Linux Netbeans configuration

2026-05-17T07:20:08Z

Fede.tft:

=== Installing the IDE ===

Netbeans is an IDE written in Java, and the Java virtual machine is needed to use the IDE. By default most Linux distributions do not come with a jvm pre-installed, so you need to install one.

<source lang="bash">
sudo apt-get install openjdk-7-jre # Install Java for Ubuntu/Debian
</source>

After that, you can install the Netbeans IDE. In theory, you could install it via apt-get, but in that way you will get the version of the IDE to write Java programs, not C/C++ programs. Even though you can install C/C++ support later, you will end up with an installation that requires far more disk space (up to several hundred megabytes). It is therefore best to download the IDE from the [https://netbeans.org/downloads Netbeans website] and install it manually. The download page will show many options depending on the programming language you are interested in. Among the possible versions choose the C/C++ version, because these are the languages used by Miosix.

The downloaded file has a .sh extension, and a name like ''netbeans-8.0-cpp-linux.sh''. You can install it by opening a terminal and typing

<source lang="bash">
sudo sh netbeans-8.0-cpp-linux.sh
</source>

a wizard will guide you through the installation.

== Theme configuration ==

If you use Gnome the IDE will use the right theme out of the box, but if you use a different desktop environment, like KDE there is a trick to get the nice theme, which consists in editing the .desktop file for Netbeans, which by default is in ''/usr/share/applications/netbeans-8.0.desktop'' (if you have installed a version of the IDE different from 8.0, the name will change likewise) and change the ''Exec='' line from

<source lang="bash">
Exec=/bin/sh "/usr/local/netbeans-8.0/bin/netbeans"
</source>

to the following value which will force the IDE to use the nice Linux theme

<source lang="bash">
Exec=/usr/local/netbeans-8.0/bin/netbeans --laf com.sun.java.swing.plaf.gtk.GTKLookAndFeel
</source>

To edit the configuration file, which is writable only by root, you can use ''nano'' or ''vi'' from a shell.

<source lang="bash">
sudo nano /usr/share/applications/netbeans-8.0.desktop
</source>

=== Configuring the IDE ===

Netbeans is a generic C/C++ IDE, and once installed is not set up by default to develop for ARM microcontrollers and Miosix. So you need to configure it. This is a one-time step that you will have to do again only if you re-install the IDE.

Note: this assumes you have already installed the Miosix toolchain, if not read the [[Linux Quick Start]] tutorial first.

Open the Netbeans IDE and click on "Tools > Options". From the top of the options window select the C/C++ panel, and click the "Add" button to add a compiler to Netbeans. As "Base directory" choose "/opt/arm-miosix-eabi/arm-miosix-eabi/bin". Choose "GNU" as "Tool collection family", and "ARM_MIOSIX_EABI" as "Tool collection name".
Note that you '''must''' use the "ARM_MIOSIX_EABI" name, or you'll have problems later.
The C and C++ compiler should be automatically filled in by Netbeans, if not copy them from the screenshot below.

[[File:Nbsetup1-linux.png]]

Last, you will need to set up the paths with the compiler libraries for code completion to work. Click on the "Code assistance" tab, and "C compiler" sub-tab. The list of folders and macro definitions should look like in this screenshot, if not, add the paths manually.

[[File:Nbsetup2-linux.png]]

Then click th "C++ compiler" sub-tab and check if the paths and macro definitions are correct. If not add the missing paths manually as in the next screenshot.

[[File:Nbsetup3-linux.png]]

Configuration is now complete. You can close the Options windows by clicking "Ok".

=== Building the Miosix kernel with Netbeans ===

Select "File > Open project" and select the "miosix_np_2" directory withn the Miosix top level directory.

[[File:Nbsetup4-linux.png]]

You may want to rename the project from the default "miosix_np_2" to the name of the project you are going to develop, by right clicking on the project name and selecting "Rename", once you have opened it.

Miosix supports different boards, each of which has different board support packages and peripheral drivers. To get code completion support for your board you need to select it within the IDE, as in the following image

[[File:Nbsetup5-linux.png]]

Please note that in the [[Linux Quick Start]] you had to select the board to compile for by editing the [[Makefile.inc|miosix/config/Makefile.inc]]. The board selection within the IDE '''does not replace''' the need to edit Makefile.inc, they serve two different purposes:
* Board selection within the IDE is used by the IDE to set up code completion for your board
* Board selection in Makefile.inc tells the kernel for which board it needs to be compiled.
However, please note that you can edit Makefile.inc and [[miosix_settings.h|miosix/config/miosix_settings.h]] as regular source files within the IDE, without the need to use a standalone text editor.

You can open main.cpp (double click on it from the left pane), and start typing your code. Code completion is invoked by typing the first letters of the function, variable, class or member function and hitting "Ctrl-space". Netbeans also integrates with Doxygen documentation, so you can see the documentation for Miosix classes and functions directly from the IDE.

[[File:Nbsetup6-linux.png]]

Building is performed by clicking the hammer icon above the source code editor. The Output window will appear below the source editor showing the compilation progress and eventual compiler errors.
There is no known way to transfer the compiled program on a microcontroller board directly from the IDE, for this you will have to use the QSTLink2 tool as explained in [[Linux Quick Start]].

[[Category:Installation and Configuration]]

Windows Netbeans configuration

2026-05-17T07:19:28Z

Fede.tft:

=== Installing the IDE ===

Download the [https://netbeans.org/downloads Netbeans IDE]. Among the possible versions choose the C/C++ version.
Netbeans is an IDE written in Java, so it requires the JDK to function. If you don't have the JDK installed, download it from [http://www.oracle.com/technetwork/java/index.html here] and install it before installing Netbeans.

=== Configuring the IDE ===

Netbeans is a generic C/C++ IDE, and once installed is not set up by default to develop for ARM microcontrollers and Miosix. So you need to configure it. This is a one-time step that you will have to do again only if you re-install the IDE.

Note: this assumes you have already installed the Miosix toolchain, if not read the [[Windows Quick Start]] tutorial first.

Open the Netbeans IDE (there should be an icon on the Desktop after installation) and click on "Tools > Options". From the top of the options window select the C/C++ panel, and click the "Add" button to add a compiler to Netbeans. As "Base directory" choose "C:\arm-miosix-eabi\arm-miosix-eabi\bin". Choose "GNU MinGW" as "Tool collection family", and "ARM_MIOSIX_EABI" as "Tool collection name".
Note that you '''must''' use the "ARM_MIOSIX_EABI" name, or you'll have problems later.
The C and C++ compiler should be automatically filled in by Netbeans, if not copy them from the screenshot below. Please note that make.exe should have '''no path''' otherwise compiling will fail.

[[File:Nbsetup1-windows.png]]

Last, you will need to set up the paths with the compiler libraries for code completion to work. Click on the "Code assistance" tab, and "C compiler" sub-tab. The list of folders and macro definitions should look like in this screenshot, if not, add the paths manually.

[[File:Nbsetup2-windows.png]]

Then click th "C++ compiler" sub-tab and check if the paths and macro definitions are correct. If not add the missing paths manually as in the next screenshot.

[[File:Nbsetup3-windows.png]]

Configuration is now complete. You can close the Options windows by clicking "Ok".

=== Building the Miosix kernel with Netbeans ===

Select "File > Open project" and select the "miosix_np_2" directory withn the Miosix top level directory.

[[File:Nbsetup4-windows.png]]

You may want to rename the project from the default "miosix_np_2" to the name of the project you are going to develop, by right clicking on the project name and selecting "Rename", once you have opened it.

Miosix supports different boards, each of which has different board support packages and peripheral drivers. To get code completion support for your board you need to select it within the IDE, as in the following image

[[File:Nbsetup5-windows.png]]

Please note that in the [[Windows Quick Start]] you had to select the board to compile for by editing the [[Makefile.inc|miosix/config/Makefile.inc]]. The board selection within the IDE '''does not replace''' the need to edit Makefile.inc, they serve two different purposes:
* Board selection within the IDE is used by the IDE to set up code completion for your board
* Board selection in Makefile.inc tells the kernel for which board it needs to be compiled.
However, please note that you can edit Makefile.inc and [[miosix_settings.h|miosix/config/miosix_settings.h]] as regular source files within the IDE, without the need to use Notepad++.

You can open main.cpp (double click on it from the left pane), and start typing your code. Code completion is invoked by typing the first letters of the function, variable, class or member function and hitting "Ctrl-space". Netbeans also integrates with Doxygen documentation, so you can see the documentation for Miosix classes and functions directly from the IDE.

[[File:Nbsetup6-windows.png]]

Building is performed by clicking the hammer icon above the source code editor. The Output window will appear below the source editor showing the compilation progress and eventual compiler errors.
There is no known way to transfer the compiled program on a microcontroller board directly from the IDE, for this you will have to use the QSTLink2 tool as explained in [[Windows Quick Start]].

[[Category:Installation and Configuration]]

Miosix and git workflow

2026-05-17T07:18:01Z

Fede.tft:

= The Miosix git repository =

Miosix uses the git version control system to manage the kernel source code. To download and use the kernel you have to clone its git repository. The main Miosix git repository is hosted on this website, miosix.org, but we have no web page where you can browse the kernel sources. For this, we use a [https://github.com/fedetft/miosix-kernel github mirror] and the two repositories will be always kept in sync.

As the kernel is under active development, users are advised to periodically ''git fetch'' or check the [https://github.com/fedetft/miosix-kernel kernel page on github] to look for new features and bug fixes, and pull the changes if required.

Cloning the kernel repository from miosix.org can be done with:

<source lang="bash">
git clone https://miosix.org/git-public/miosix-kernel.git
</source>

While cloning the github mirror with:

<source lang="bash">
git clone https://github.com/fedetft/miosix-kernel.git
</source>

== Branches ==

By default, when cloning a repository, git will download the ''master'' branch. Miosix offers two additional branches, ''testing'' and ''unstable'', and you should be aware of the conventions we use for how we manage branches:
* The ''master'' branch contains the stable kernel, it is updated infrequently, usually once a year when a new release is made. Sometimes, a few minor releases are updated in short order.
* The ''testing'' branch contains the in-development code that we consider almost ready. Use this branch to get more bleeding edge features.
* The ''unstable'' branch is where the Miosix development team is working. It's meant to be used only by people in contact with the development team, as we occasionally rebase and force-push changes, so you may have a hard time keeping your git repository in sync with ours (the commit you downloaded today may no longer exist after a force push). If you're writing applications, it's best to ignore this branch and wait for the desired change to trickle to testing.

To checkout a specific branch, once you have cloned the git repository, use the following command
<source lang="bash">
cd miosix-kernel
git checkout testing
</source>

= Using Miosix in your projects =

The rest of this page explains how to set up a software project making use of the Miosix kernel. There are basically two ways to do so:

* Using out of git tree projects: this is the suggested workflow for developing applications using Miosix. Your application directory (and optionally git repo) stay separate from the kernel directory and git repo. The kernel can be a git submodule of your project.
* Forking the Miosix kernel git repository. This is the suggested workflow for extending the kernel, such as adding new board support packages (BSPs).

The two workflows can be combined, for example you may want to fork the kernel to add your BSPs, and then use the forked kernel as submodule for developing your applications.

= Out of git tree projects =

Out of git tree projects allow you to write applications in a directory that stays separate from the Miosix kernel directory. When we say ''out of git tree'', we mean that your project is developed outside of the ''Miosix'' git tree. Your project can be a git repository too, but that is up to you to decide.

Additionally, a key part of an out of git tree project is that it allows to perform the kernel configuration (that requires editing configuration files) without the need to make changes to files within the Miosix git repo ''at all''. This last point is important both to have the Miosix git repository as a [http://www.git-scm.com/book/en/Git-Tools-Submodules git submodule] of your application's git repository, and to allow sharing the same downloaded copy of the Miosix kernel across different applications, each with its own configuration. The kernel source code size on the hard drive has grown bigger in recent years due to the inclusion of headers with peripheral registers definitions in the [https://github.com/fedetft/miosix-kernel/tree/master/miosix/arch/CMSIS CMSIS] directory, so you may want to share a single downloaded copy of the kernel across several projects.

Note that the ability to develop applications without making changes to the kernel directory is currently limited to the use case of configuring the kernel for one of the available BSPs. If you need to add BSPs to the kernel, then you'll most likely also have to fork the kernel repository. The ''most likely'' is due to ''generic'' BSPs in the kernel, which can be identified in the list of boards in [https://github.com/fedetft/miosix-kernel/blob/master/miosix/config/Makefile.inc Makefile.inc] as ''<chip name>_generic'' such as ''stm32f103xb_generic''. If you're writing an application for a board that has a chip with a generic BSP in the kernel, you can (unless you ''really'' need to run some custom code during boot) get away with selecting the generic BSP without forking the kernel. If there's no generic BSP for your chip, or need to add support for an entirely new chip, then you'll have to fork the kernel to add it.

== Organizing your out of git tree projects ==

For an out of git tree project, you need to create a directory in your computer that will contain your project. The ''miosix-kernel'' directory (and git repo) can either be a subdirectory of your project's directory (common option when adding the Miosix kernel as a git submodule to your project):

[[File:Out-of-tree-subdirectory.png]]

Or you can organize your projects side by side to the kernel (common when sharing a single kernel among multiple projects):

[[File:Out-of-tree-shared.png]]

The only constraint (it's a limitation in the Makefile build systems), is that the ''relative'' path from your project directory to the kernel should not contain spaces. This practically means that you should not give your project directories names with spaces.

== Adding Miosix as a submodule to your git project ==

Suppose you have a git repository called myapplication, which is the repo of your application, and you would like to download the miosix-kernel repository as a git submodule. Then open a shell in the test repository and type:

<source lang="bash">
git submodule init
git submodule add https://miosix.org/git-public/miosix-kernel.git miosix-kernel
git commit -m "Added miosix-kernel as a git submodule"
</source>

== Initializing an out of git tree project ==

Using out of git tree projects implies having a build system in your project directory that can both compile the source code of your application and the Miosix kernel. Miosix provides two build systems, Makefiles and [[CMake]]. In this tutorial we'll use Makefiles.

Miosix projects start from a template that you can find in the ''miosix-kernel/templates'' directory. You can copy the template yourself from the kernel source tree to your project directory, but in that case, you'll need to fix the relative paths in the build system. Alternatively, you can use the ''init_project_out_of_git_tree.pl'' script to initialize a project.

Additionally, the kernel configuration directory needs to be copied to your project. This is necessary because you'll need to make changes to those files to select kernel build options, at minimum which board you want to compile the kernel for.
As you may know, git submodules work well if you never make changes in the submodule directory, otherwise you will have to basically fork the submodule, or you will find yourself making changes to a repository in a detached head state and risk losing them at the next git pull.
For this reason, we'll copy the config directory to your project and make changes there. The ''init_project_out_of_git_tree.pl'' performs also this action for you.

=== Initialize a project using ''init_project_out_of_git_tree.pl'' ===

Just open a shell in your project directory and invoke the perl script in the kernel:

<source lang=bash>
perl <path to the kernel>tools/init_project_out_of_git_tree.pl
</source>

Thus for the case when the kernel is a subdirectory of your project that would be:
<source lang=bash>
perl miosix-kernel/tools/init_project_out_of_git_tree.pl
</source>

While for the side-by-side case:
<source lang=bash>
perl ../miosix-kernel/tools/init_project_out_of_git_tree.pl
</source>

Note that you have to run the script without moving the current directory away from the one of your project. This means you can't ''cd'' to the ''miosix-kernel/tools'' directory, run the script there, and then ''cd'' back. The script withes the project files to the current directory it's been invoked from.

If all goes well you'll get a message similar to:
<source lang=bash>
Successfully created Miosix project
Target directory: myapplication
Kernel directory: myapplication/miosix-kernel/miosix
</source>

and your project should now contain the ''config'' directory and the ''main.cpp'', ''Makefile'' and ''CMakeLists.txt'' files.

From there, you'll need to edit the configuration as desired, and start building your application starting from ''main.cpp''.

=== Manually copying a template ===

The perl script is convienient, but not necessary. It's possible to do the configuration manually by copying and editing files.

To do so, there are 3 steps involved.

First, copy the ''miosix-kernel/miosix/config'' directory to your project.

Second, copy a template form the ''miosix-kernel/templates'' directory to your project. The ''simple'' template configures the kernel as a unikernel and will run your application in kernelspace. The ''processes'' template will allow you to develop (part of) your application in a userspace process with memory protection, bu that's a more advanced topic related to the [[fluid kernel]] concept.

You shouldn't copy the template directory, rather its content, so the ''main.cpp'', ''Makefile'' and ''CMakeLists.txt'' files in the case of the ''simple'' template.

Third and final step, you should edit the build system to point to the correct kernel and config directory. This step was done automatically by the perl script, in this case you'll have to do it manually.

Open the ''Makefile'' file, and edit the following lines:

<source lang=bash>
KPATH := ../../miosix
CONFPATH := $(KPATH)
</source>

The first line, defining the KPATH variable should be assigned to the relative path from your project directory to the kernel directory. If your ''miosix-kernel'' is a subdirectory of your project that should be:

<source lang=bash>
KPATH := miosix-kernel/miosix
</source>

The second line defines the CONFPATH variable, and since you want to the kernel to find the ''config'' directory in your project , and '''not''' the one in the ''miosix-kernel/miosix/config'' directory, you'll have to chege it to the current directory, or ''.'':

<source lang=bash>
CONFPATH := .
</source>

Finally, open ''CMakeLists.txt''. Also in this case you'll have to tell it where is the kernel directory, and to use the ''config'' directory in your project. The kernel directory is specified by replacing:

<source lang=bash>
set(MIOSIX_KPATH ${CMAKE_SOURCE_DIR}/../../miosix)
</source>

with:

<source lang=bash>
set(MIOSIX_KPATH ${CMAKE_SOURCE_DIR}/miosix-kernel/miosix)
</source>

Whiel to tell CMake to use the config directory in your project, uncomment the following line:

<source lang=bash>
set(MIOSIX_USER_CONFIG_PATH ${CMAKE_SOURCE_DIR}/config)
</source>

= Forking the Miosix git repository =

Forking the Miosix git repository simply means cloning the kernel repository and start making changes within the kernel. To clone the git repository you simply type the following commands:

<source lang="bash">
git clone https://miosix.org/git-public/miosix-kernel.git
cd miosix-kernel
git checkout testing
</source>

The Miosix top-level directory contains the following files and subdirectories:

[[File:Miosix-top-level-directory.png]]

The [https://github.com/fedetft/miosix-kernel/blob/master/README.md README.md] file contains more detailed information on how the kernel source code directory tree is structured, but a quick overview is that the entire kernel code is in the ''miosix'' subdirectory, ''templates'' contains application templates you can copy out of the kernel directory to create your out of tree projects, ''examples'' contains some demos of the Miosix APIs, wile ''tools'' contains scripts and support code that does not get compiled into the kernel. It also contains the scripts and patches used to build the [[Miosix Toolchain]], the GCC-based cross compiler used to build the kernel.

== Making changes ==

Once you start making changes you can simply commit in the cloned git repository. If you need to share your changes, perhaps because there are multiple developers, git allows to have multiple remotes for a repository, so you can leave the default remote to periodically pull updates and bugfixes from the upstream Miosix repository, as well as push and pull from your personal remote repository.

== Testing changes ==

Once you start making changes to the kernel, you'll most likely want to quickly test to see if they work, which entails compiling the kernel to check for compile-time errors, and flash it to a board to check the code works at run-time.

To do so you can set up a Miosix out of git tree project as described earlier that points to your cloned kernel, but there's a quicker way: building the templates from within the kernel tree.

To do so, you'll need to select the board you want to build directly in the [https://github.com/fedetft/miosix-kernel/blob/master/miosix/config/Makefile.inc miosix/config/Makefile.inc] inside the kernel source tree, and select additional options (if needed) directly in the [https://github.com/fedetft/miosix-kernel/blob/master/miosix/config/miosix_settings.h miosix/config/miosix_settings.h] inside the kernel source tree.

Ad this point, you can ''cd'' to the ''templates/simple'' (or any other template directory) and type

<source lang=bash>
make
make program
</source>

from that directory.

Although convenient, this comes with two caveats that you should be careful about:
* If you also use the kernel for making out of tree projects, the scripts such as ''init_project_out_of_git_tree.pl'', when copying the configuration and template directory to initialize a out of tree project, will also copy the testing code with it. This is often just a minor inconvenience, which can easily be solved in many ways, such as by using ''git stash'' before running an ''init_project_out_of_git_tree.pl'' script to temporarily stash those changes.
* You should remember to '''not commit''' these changes to configuration files, especially when you plan to contribute patches upstream. The list of boards in Makefile.inc should by default have all the available boards commented out, so as to let users select the board they want by uncommenting it.

== Running the Miosix regression testsuite ==

Miosix comes with a regression test suite that exercises most of the kernel code and is useful when making changes to the kernel to verify the absence of regressions.

To compile the testsuite you should follow the instructions above to moddify the kernel's ''miosix/config'' directory to select the board you want to run the testsuite on, and then compile the testuite that is in the ''tools/testsuite'' directory.

<source lang=bash>
cd tools/testsuite
make
make program
</source>

Note that compiled firmware of the testsuite is quite large since it contains every function of the kernel, especially if compiled with support for the filesystem and userspace processes.

Making it easier to run the testsuite on small microcontrollers with little FLASH and RAM memory is a work in progress, he Miosix development team "chops" the testsuite in smaller pieces by commenting out part of it and running it one piece at a time, this is a tip worth knowing if you need to run it on very small microcontrollers.

== Contributing to Miosix ==

Miosix uses a shared ownership model, meaning that you retain the copyright for the contributions you add to the kernel. Your contributions should however be licensed with the same license of the rest of the kernel:

<source lang=CPP>
/***************************************************************************
* Copyright (C) <year> by <your name> *
* *
* This program is free software; you can redistribute it and/or modify *
* it under the terms of the GNU General Public License as published by *
* the Free Software Foundation; either version 2 of the License, or *
* (at your option) any later version. *
* *
* This program is distributed in the hope that it will be useful, *
* but WITHOUT ANY WARRANTY; without even the implied warranty of *
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
* GNU General Public License for more details. *
* *
* As a special exception, if other files instantiate templates or use *
* macros or inline functions from this file, or you compile this file *
* and link it with other works to produce a work based on this file, *
* this file does not by itself cause the resulting work to be covered *
* by the GNU General Public License. However the source code for this *
* file must still be made available in accordance with the GNU General *
* Public License. This exception does not invalidate any other reasons *
* why a work based on this file might be covered by the GNU General *
* Public License. *
* *
* You should have received a copy of the GNU General Public License *
* along with this program; if not, see <http://www.gnu.org/licenses/> *
***************************************************************************/
</source>

Be sure to add the copyright notice to all nontrivial source files. An example of a trivial source file would be a forwarding header such as [https://github.com/fedetft/miosix-kernel/blob/master/miosix/arch/cpu/armv8m/interfaces-impl/endianness_impl.h this one].

If you wrote the file you want to add from scratch, just add your name to the copyright notice. If instead you copy-pasted the file from another one already present in the kernel and modified it (this often happens when making BSPs as there's almost always a similar BSP in the kernel to take inspiration from), just append your name to the list of authors of the file you copied.

Since we use github only as a mirror to our repository that we host on miosix.org, we do not accept pull requests. You will instead be required to make a [https://git-scm.com/docs/git-format-patch format-patch] with the changes you want to be pushed upstream and send it via email to fede.tft&&miosix.org (s/&&/@/). It may be a good idea to get in contact first to discuss the changes you want pushed upstream, especially if they include modifications to the kernel itself rather than being simply new BSPs.

When submitting patches for inclusion, please make sure that commits are small and self-contained, in order to simplify the integration process.

Your changes should apply to the latest ''testing'' branch. If changes are related to the kernel itself, we may request to rebase them on top of ''unstable''.

[[Category:Installation and Configuration]]

Fluid kernel

2026-05-17T07:16:03Z

Fede.tft: Created page with "TODO: the fluid kernel architecture needs to be documented in the wiki. In the meantime, you can read [https://ieeexplore.ieee.org/document/11173649 the paper]."

TODO: the fluid kernel architecture needs to be documented in the wiki.
In the meantime, you can read [https://ieeexplore.ieee.org/document/11173649 the paper].

Miosix in emulation

2026-05-15T16:14:12Z

Fede.tft:

This page attempts to provide enough instructions to try out Miosix under the most common system emulators.
Running Miosix under an emulator could be useful to try it out or debug it if you don't have (or if you don't want to buy) the required hardware.

'''Important:''' At the moment none of the emulators we have attempted to use have managed to properly boot a fully-functioning instance of Miosix and pass all self-tests. Some of them might work well enough for simple applications, but will fail when certain kernel APIs are called.
The main issue is how well emulators emulate the complex logic of the peripherals of a microcontroller. Often emulators claim to support a specific microcontroller, while the emulation of most peripherals is either completely missing or incomplete.
Hardware timers not running at the correct rate or at all is a common issue, also USART input appears to not work on any emulator. Therefore, '''do not base your opinion of Miosix on your experience with running it under emulation'''.

Miosix versions before 2.5, which are not [[Wikipedia:Tickless kernel|tickless kernels]], are known to work better under emulation.

== QEMU ==

[https://www.qemu.org QEMU] is an open-source virtual machine monitor and emulator software capable to emulate a wide range of hardware, including CPUs, graphics adapters, network cards, and storage devices. It is commonly used by software, firmware and hardware engineers for testing, debugging, and virtualization purposes. Furthermore, QEMU is easy to set-up from the command line.

=== Supported boards ===

The QEMU Documentation mentions a few supported STM32 boards. Among those, the [[Stm32f100rb stm32vldiscovery|STM32VLDISCOVERY]] board is supported by Miosix as well. However, at the moment we are writing, the latest version of QEMU (8.0.2) lacks support for many STM32 devices, and therefore a non-negligible amount of peripherals and interfaces are not available for emulation. Additionally, even the existing implementation of supported devices appears to be incomplete.

To show the boards supported by the QEMU version installed on the system, type the following command:

<pre>
qemu-system-arm -machine help
</pre>

=== Configuration of Miosix ===

To make the Miosix kernel work on QEMU it is important to '''disable the DMA''' since it is unimplemented and will cause emulation to hang as soon as it is accessed.
To disable the DMA, it is sufficient to open the board settings file in the config directory [https://github.com/fedetft/miosix-kernel/blob/master/miosix/config/board/stm32f100rb_stm32vldiscovery/board_settings.h miosix/config/board/stm32f100rb_stm32vldiscovery/board_settings.h] and set <code>defaultSerialDma</code> to false:

<code lang=CPP>
const bool defaultSerialDma=false;
</code>

It is also important to avoid the usage of unimplemented devices, such as GPIOs, therefore LEDs and buttons don't work.

=== Launching emulation ===

To emulate the board and launch the freshly compiled Miosix kernel you can use the following command:

<pre>
qemu-system-arm -M stm32vldiscovery -kernel main.bin
</pre>

For debug purposes, it is possible to obtain a list of all the unimplemented devices used by Miosix by adding the <code>-d unimp</code> argument to the command line.

Now, in the QEMU Monitor, it is possible to check the data transferred through the USART interface by opening the "View" pop-up menu on top and selecting "serial0".

=== Debugging the emulated machine with GDB ===

To use GDB to monitor the loaded kernel, it is important to open a localhost tcp communication port for it and to start the emulated board in frozen mode (freeze at program\_counter=1). This is done by adding the arguments <code>-s -S</code>
in the previously mentioned QEMU start emulation command. The first argument is the shorthand for <code>-gdb tcp:1234</code>, while the second one is needed to start in frozen mode.

Now GDB can be started with the command:

<pre>
arm-miosix-eabi-gdb main.elf -ex "target remote localhost:1234"
</pre>

== QEMU-STM32 ==

[https://github.com/beckus/qemu_stm32 QEMU-STM32] is a QEMU fork which extends version 2.1.3 of the well-known emulator to the STM32 board family. In particular, the newly-supported boards are:
* Olimex STM32P103
* Olimexino_STM32
* STM32F103C8_BLUEPILL

The last one of these boards is supported in Miosix with the name <code>stm32f103c8_breakout</code>.

QEMU-STM32 predates the current support for STM32 microcontrollers available in mainline QEMU, however its support is more complete. On the other hand, the development of QEMU-STM32 appears to not be active anymore in 2023, therefore building it requires to install several legacy dependencies. Additionally, the repository appears to reference several now inaccessible submodules. Therefore, to build QEMU-STM32 it is necessary to manually edit the submodule configuration to replace <code>git://git.qemu-project.org</code> and <code>git://github.com/rth7680</code> with <code>https://gitlab.com/qemu-project</code>.

Once you have built QEMU-STM32, using it is no different than a more recent version of QEMU. The command line to use for launching a build of Miosix for the BluePill board is the following:

<pre>
qemu-system-arm -machine stm32-f103c8 -kernel main.bin -serial stdio
</pre>

The setting <code>-serial stdio</code> allows to use the standard input/output devices for sending/receiving USART data.

== Renode ==

[https://renode.io Renode] is an open-source simulation framework for hardware and software development. Its advertisements say it provides "a virtual environment where developers can simulate the behaviour of their devices and test their software on a virtual platform before deploying it on physical hardware".

Renode supports the [[Stm32f407vg stm32f4discovery|STM32F4_DISCOVERY]] board, which is a popular and well-tested target for Miosix as well. Renode supports the DMA and GPIO peripherals of the STM32, therefore no specific modifications of the Miosix code are required.

=== Configuration of Renode ===

Before using the STM32F4_DISCOVERY on Renode, it is necessary to:
<ol>
<li>
<p>Add the CCM ('Core Coupled Memory') in the memory map of Renode because it is not implemented by default. The easiest way to solve this problem is to modify the <code>renode/platforms/cpus/stm32f4.repl</code> file, where all MCU registers are mapped. The following lines need to be added at the end of the file:
<pre>
ccm: Memory.MappedMemory @ sysbus 0x10000000
size: 0x10000
</pre>
'''Note!''' Make sure the code has the same indentation shown above, because it is significant for the compilation of the Platform Descriptor file.
</li>
<li>
Modify the <code>GPIO</code> pin associated to the <code>UserLED</code> because Miosix uses a different one. This could be done by modifying the <code>renode/platforms/boards/stm32f4_discovery.repl</code> file and substituting <code>pin12</code> with <code>pin14</code>:
<pre>
gpioPortD:
14 -> UserLED@0
</pre>
</li>
</ol>

=== Launching emulation ===

To launch an instance of Miosix, built for the <code>stm32f407vg_stm32f4discovery</code> target, launch Renode and write the following commands on the Renode console:

<ol>
<li>
Create a Machine, load the board and load the kernel:
<pre>
mach create
machine LoadPlatformDescription @platforms/boards/stm32f4_discovery-kit.repl
sysbus LoadELF @main.elf
</pre>
</li>
<li>
Open the serial monitor on USART3:
<pre>
showAnalyzer sysbus.usart3
</pre>
</li>
<li>
Start the GDB server (if needed):
<pre>
machine StartGdbServer 3333
</pre>
<code>3333</code> is the remote port to specify in GDB to connect to the emulated machine.
</li>
<li>
Start the machine:
<pre>
start
</pre>
</li>
</ol>

Renode provides very useful debugging commands, mainly to monitor the status of devices, such as <code>sysbus.gpioPortD.UserLED State</code>, or <code>sysbus.gpioPortD GetGPIOs</code> which prints the status of all the ''GPIO portD'' pins. To enable logs type the command <code>sysbus LogPeripheralAccess sysbus.gpioPortD True</code>.

== Acknowledgments ==

Most of the contents of this page were contributed by Francesco Lenzi and Donato Carlo Giorgio. Thanks!

Synchronization primitives

2026-05-15T16:02:57Z

Fede.tft:

Miosix provides synchronization primitives, both high and low level. High level synchronization primitives are standard mutexes and condition variables that are familiar to programmers of multithreaded applications. This page addresses in more detail the low level synchronization primitives which are Miosix-specific, and is most useful when developing low level code, especially device drivers, on Miosix.

= High level synchronization primitives =
For what concerns high level synchronization primitives, Miosix provides the ususal mutexes and condition variables, accessible through three APIs:
* The C++11 classes such as ''std::thread'', ''std::mutex'' and ''std::condition_variable'' through the C++ standard library
* The POSIX thread functions and opaque data types such as ''pthread_t'', ''pthread_mutex_t'' and ''pthread_cond_t'' through the C standard library
* The native Miosix API which is the underlying implementation of all the other APIs. This is a C++ API including class ''Thread'' which is the actual Task Control Block (TCB) used by the scheduler, and classes ''Mutex'', ''FastMutex'', ''KernelMutex'' and ''ConditionVariable''

The use for these synchronization primitives is to protect data structures from concurrent access by multiple threads. These synchronization primitives are very easy to use, with almost no preconditions or special requirements, but cannot be used for more low-level tasks, such as synchronizing between threads and interrupt routines.

Both the mutex and the condition variable are optimized for speed, for example a lock/unlock pair of function calls to an uncontended mutex take around 100 clock cycles on an architecture such as the Cortex-M. Recursive mutexes are supported, and so are mutexes with priority inheritance, as well as timed waits on condition variables.

Just like the standard C++, RAII-style mutex locking is recommended also with the native API, through the provided ''Lock<T>'' and ''Unlock<T>'' classes.
Compare this example using directly the ''Mutex'' member functions

<source lang="CPP">
class Foo
{
int x;
Mutex m;
public:
void decIfPositive()
{
m.lock();
if(x<=0) return;
x--;
m.unlock();
}
};
</source>

As you can see, the code contains an error: the return in the middle of the function does not unlock the mutex, something that will likely cause problems.

On the other hand, if a ''Lock''' is used

<source lang="CPP">
class Foo
{
int x;
Mutex m;
public:
void decIfPositive()
{
Lock<Mutex> l(m);
if(x<=0) return;
x--;
}
};
</source>

you don't have to worry about that. When considering that functions can return due to a propagation of a C++ exception, using locks is the only way to write exception-safe C++ code.

If you need to temporarily unlock a mutex from within a scope where a ''Lock'' is in effect, this is made possible by creating an inner scope and using an ''Unlock'' object, like this:

<source lang="CPP">
Mutex m;
{
Lock<Mutex> l(m);
//Now the Mutex is locked
{
Unlock<Mutex> u(l);
//Now the mutex is unlocked
}
//Now the Mutex is again locked
}
</source>

Note how to create an ''Unlock'' object you have to pass a ''Lock'' to its constructor. This prevents you from trying to unlock a mutex you have not locked.

For what concerns the ''ConditionVariable'' class, it provides the ''wait()'', ''signal()'' and ''broadcast()'' member functions as you'd expect. Moreover, there's an overload of ''wait()'' taking a ''Lock'' instead of a bare mutex for convenience.

= Low level synchronization primitives =

Miosix provides two low-level synchronization primitives, the GlobalIrqLock or "GIL" and the PauseKernelLock or "PK".

== The GIL lock ==

The GlobalIrqLock or "GIL". On single core architectures, this lock disables interrupts and makes the code fragment taking this lock uninterruptible, not even by interrupt handlers. On multicore architectures, this lock disables interrupts on the core taking the lock, making the code fragment using it uninterruptible, not even by interrupt handlers. Additionally, only up to '''one''' core can take the GIL at any given time. If a second core attempts to take the GIL while another core has already taken it, it will block execution until the core holding the GIL has released it. Taking the GIL must be done using one of three [https://en.wikipedia.org/wiki/RAII RAII] C++ classes: ''GlobalIrqLock'', which is recursive, thus allowing to take the lock multiple times, ''FastGlobalIrqLock'', a faster but non-recursive version, or ''FastGlobalLockFromIrq'', the only version that can be used to take the GIL from an interrupt handler (this version is not recursive).

The GIL is used to implement device drivers that make use of interrupts, as well as inside the kernel, by the scheduler which also runs from inside an interrupt. Since both use the same lock, it's possible for an interrupt handler in a device driver to wakeup a thread from within an interrupt handler without corrupting the scheduler data structures.

The reason why a regular mutex cannot be used for this purpose is because interrupts are by their very nature asymmetric. An interrupt can interrupt the code of a thread, but a thread cannot interrupt an interrupt. This means that when you're writing device drivers and you need to synchronize between an interrupt and normal code a mutex won't do the job. If the mutex is already locked when the interrupt code starts, trying to lock it within the interrupt will attempt to block the interrupt till the thread unlocks it, and as you can imagine, this won't end up well.

To synchronize in such cases you have to temporarily disable interrupts from within your thread or main program, so that the thread and the interrupt won't try to access some data structure at the same time.

There's nothing new in that, if you've programmed microcontrollers before without an OS, you've accustomed to disabling interrupts as a mean of synchronization. The only difference is that in multicore architectures, you'll have to remember to take the ''FastGlobalLockFromIrq'' also from within interrupt handlers before calling the scheduler API to wakeup tasks, as the scheduler could be running on another core causing a race condition. In single core architectures you don't technically need to put a ''FastGlobalLockFromIrq'' in interrupt handlers. If you do it will be optimized away as it's not required. Since there's no performance penalty, you may as well take the habit of always using ''FastGlobalLockFromIrq'', just in case your driver gets reused in a multicore chip.

Inside a critical section taking the GIL you should not call functions that cause a preemption, such as almost all high-level function form the C++ standard library (including ''printf()'', '''malloc()/new''' and filesystem-related functions). Also, the only functions that are part of the Miosix kernel API that are safe to be called with the GIL locked are prefixed with IRQ. Why IRQ and not GIL you may say? It's because of older version of the kernel, before multicore support was introduced.

More importantly, all functions of the kernel that are prefixed with IRQ are '''only''' safe to be called if you're holding the GIL.

Some functions have both an IRQ and non IRQ version, such as ''miosix::getTime()'' and miosix::IRQgetTime()''.

== The PK lock ==
The PauseKernelLock or "PK". This lock disables preemption. This means that the code fragment taking the lock cannot be preempted by other threads, but can be interrupted by interrupts. On multicore architectures, only up to '''one''' core can take the PK at any given time. If a second core attempts to take the PK while another core has already taken it, it will block execution until the core holding the PK has released it. Note that on multicore architectures, it is allowed for one core can take the GIL, while another core can take the PK.

If the time spent with preemption disabled exceeds the thread's timeslice a preemption will occur immediately when releasing the lock.

Despite faster than a mutex, these synchronization primitives carry some heavy restrictions, and are mostly used to implement parts of the kernel itself. The main isssue is that you must never force a preemption when the kernel is paused. If this happens, the kernel will likely lock up badly. Of course, this means you can't call ''Thread::yield()'' when the kernel is paused, but there are many more subtler ways to cause a preemption.

In general, inside a critical section taking the GIL you should not call functions that cause a preemption, such as almost all high-level function form the C++ standard library (including ''printf()'' and filesystem-related functions). Also, the only functions that are part of the Miosix kernel API that are safe to be called with the PK locked are prefixed with PK.

All in all, you won't find much need to use the PK synchronization primitive, unless you're writing kernel code. At that point, you'll find it useful. Miosix uses it internally to make regular mutexes and condition variables work.

== Summarizing it all ==
The following table summarizes what you can do depending on what low level synchronization primitive you are using, as well as when you are writing the code of an interrupt service routine.

Although it may seem complicated, it is because it contains all possible cases, most of which are rather uncommon. In most cases you'll be writing code while not being into the scope of any low level lock, so you can do everything but call functions prefixed with IRQ or PK. When you are within an interrupt or take the GIL, the other most common case, you will usually not need to call any function besides the kernel API prefixed with IRQ.

{| class="wikitable"
|
| file related operations
| printf, scanf, cin, cout
| Thread::yield(), Thread::sleep(), usleep()
| call kernel functions with no prefix
| call kernel functions with PK prefix
| call kernel functions with IRQ prefix
| allocate memory
| throw C++ exceptions
| delayMs() and delayUs()
|-
| Normal code
| style="background-color: #80ff80;" | Yes
| style="background-color: #80ff80;" | Yes
| style="background-color: #80ff80;" | Yes
| style="background-color: #80ff80;" | Yes
| style="background-color: #ff8080;" | No
| style="background-color: #ff8080;" | No
| style="background-color: #80ff80;" | Yes
| style="background-color: #80ff80;" | Yes
| style="background-color: #80ff80;" | Yes
|-
| Within a PauseKernelLock
| style="background-color: #ff8080;" | No
| style="background-color: #ff8080;" | No
| style="background-color: #ff8080;" | No
| style="background-color: #ff8080;" | No
| style="background-color: #80ff80;" | Yes
| style="background-color: #ff8080;" | No
| style="background-color: #80ff80;" | Yes
| style="background-color: #80ff80;" | Yes
| style="background-color: #80ff80;" | Yes
|-
| Within an GlobalIrqLock
| style="background-color: #ff8080;" | No
| style="background-color: #ff8080;" | No
| style="background-color: #ff8080;" | No
| style="background-color: #ff8080;" | No
| style="background-color: #ff8080;" | No
| style="background-color: #80ff80;" | Yes
| style="background-color: #ff8080;" | No **
| style="background-color: #ff8080;" | No **
| style="background-color: #80ff80;" | Yes
|-
| Within a FastGlobalIrqLock
| style="background-color: #ff8080;" | No
| style="background-color: #ff8080;" | No
| style="background-color: #ff8080;" | No
| style="background-color: #ff8080;" | No
| style="background-color: #ff8080;" | No
| style="background-color: #ffff80;" | Yes *
| style="background-color: #ff8080;" | No
| style="background-color: #ff8080;" | No
| style="background-color: #80ff80;" | Yes
|-
| Within an interrupt service routine (taking FastGlobalLockFromIrq in the multicore case)
| style="background-color: #ff8080;" | No
| style="background-color: #ff8080;" | No
| style="background-color: #ff8080;" | No
| style="background-color: #ff8080;" | No
| style="background-color: #ff8080;" | No
| style="background-color: #ffff80;" | Yes *
| style="background-color: #ff8080;" | No
| style="background-color: #ff8080;" | No
| style="background-color: #80ff80;" | Yes
|-
|}
<nowiki>*</nowiki> = Most IRQ-prefixed functions can be called both with interrupts disabled (either within an ''GlobalIrqLock'', ''FastGlobalIrqLockLock'' or ''FastGlobalLockFromIrq'') and within an interrupt routine. The only exception being ''IRQregisterIrq'' and ''IRQunregisterIrq'' which are used for registering/unregistering interrupts, that cannot be called from within an interrupt handler and forcedly require a ''GlobalIrqLock''. Refer to the doxygen documentation of the individual function when unsure.

<nowiki>**</nowiki> = Used to be possible from Miosix v1.61 to Miosix v2.81, no longer possible since Miosix v2.99 due to multicore support. Now that a core can take the GIL and another core the PK, we must enforce that taking both locks can only be done by first taking the PK and then "upgrading" to the GIL. Doing the reverse would cause deadlocks, and since malloc/new take the PK, it's no longer possible to first take the GIL and then malloc.

[[Category:API]]

Synchronization primitives

2026-05-15T16:02:28Z

Fede.tft:

Miosix provides synchronization primitives, both high and low level. High level synchronization primitives are standard mutexes and condition variables that are familiar to programmers of multithreaded applications. This page addresses in more detail the low level synchronization primitives which are Miosix-specific, and is most useful when developing low level code, especially device drivers, on Miosix.

= High level synchronization primitives =
For what concerns high level synchronization primitives, Miosix provides the ususal mutexes and condition variables, accessible through three APIs:
* The C++11 classes such as ''std::thread'', ''std::mutex'' and ''std::condition_variable'' through the C++ standard library
* The POSIX thread functions and opaque data types such as ''pthread_t'', ''pthread_mutex_t'' and ''pthread_cond_t'' through the C standard library
* The native Miosix API which is the underlying implementation of all the other APIs. This is a C++ API including class ''Thread'' which is the actual Task Control Block (TCB) used by the scheduler, and classes ''Mutex'', ''FastMutex'', ''KernelMutex'' and ''ConditionVariable''

The use for these synchronization primitives is to protect data structures from concurrent access by multiple threads. These synchronization primitives are very easy to use, with almost no preconditions or special requirements, but cannot be used for more low-level tasks, such as synchronizing between threads and interrupt routines.

Both the mutex and the condition variable are optimized for speed, for example a lock/unlock pair of function calls to an uncontended mutex take around 100 clock cycles on an architecture such as the Cortex-M. Recursive mutexes are supported, and so are mutexes with priority inheritance, as well as timed waits on condition variables.

Just like the standard C++, RAII-style mutex locking is recommended also with the native API, through the provided ''Lock<T>'' and ''Unlock<T>'' classes.
Compare this example using directly the ''Mutex'' member functions

<source lang="CPP">
class Foo
{
int x;
Mutex m;
public:
void decIfPositive()
{
m.lock();
if(x<=0) return;
x--;
m.unlock();
}
};
</source>

As you can see, the code contains an error: the return in the middle of the function does not unlock the mutex, something that will likely cause problems.

On the other hand, if a ''Lock''' is used

<source lang="CPP">
class Foo
{
int x;
Mutex m;
public:
void decIfPositive()
{
Lock<Mutex> l(m);
if(x<=0) return;
x--;
}
};
</source>

you don't have to worry about that. When considering that functions can return due to a propagation of a C++ exception, using locks is the only way to write exception-safe C++ code.

If you need to temporarily unlock a mutex from within a scope where a ''Lock'' is in effect, this is made possible by creating an inner scope and using an ''Unlock'' object, like this:

<source lang="CPP">
Mutex m;
{
Lock<Mutex> l(m);
//Now the Mutex is locked
{
Unlock<Mutex> u(l);
//Now the mutex is unlocked
}
//Now the Mutex is again locked
}
</source>

Note how to create an ''Unlock'' object you have to pass a ''Lock'' to its constructor. This prevents you from trying to unlock a mutex you have not locked.

For what concerns the ''ConditionVariable'' class, it provides the ''wait()'', ''signal()'' and ''broadcast()'' member functions as you'd expect. Moreover, there's an overload of ''wait()'' taking a ''Lock'' instead of a bare mutex for convenience.

= Low level synchronization primitives =

Miosix provides two low-level synchronization primitives, the GlobalIrqLock or "GIL" and the PauseKernelLock or "PK".

== The GIL lock ==

The GlobalIrqLock or "GIL". On single core architectures, this lock disables interrupts and makes the code fragment taking this lock uninterruptible, not even by interrupt handlers. On multicore architectures, this lock disables interrupts on the core taking the lock, making the code fragment using it uninterruptible, not even by interrupt handlers. Additionally, only up to '''one''' core can take the GIL at any given time. If a second core attempts to take the GIL while another core has already taken it, it will block execution until the core holding the GIL has released it. Taking the GIL must be done using one of three [https://en.wikipedia.org/wiki/RAII RAII] C++ classes: ''GlobalIrqLock'', which is recursive, thus allowing to take the lock multiple times, ''FastGlobalIrqLock'', a faster but non-recursive version, or ''FastGlobalLockFromIrq'', the only version that can be used to take the GIL from an interrupt handler (this version is not recursive).

The GIL is used to implement device drivers that make use of interrupts, as well as inside the kernel, by the scheduler which also runs from inside an interrupt. Since both use the same lock, it's possible for an interrupt handler in a device driver to wakeup a thread from within an interrupt handler without corrupting the scheduler data structures.

The reason why a regular mutex cannot be used for this purpose is because interrupts are by their very nature asymmetric. An interrupt can interrupt the code of a thread, but a thread cannot interrupt an interrupt. This means that when you're writing device drivers and you need to synchronize between an interrupt and normal code a mutex won't do the job. If the mutex is already locked when the interrupt code starts, trying to lock it within the interrupt will attempt to block the interrupt till the thread unlocks it, and as you can imagine, this won't end up well.

To synchronize in such cases you have to temporarily disable interrupts from within your thread or main program, so that the thread and the interrupt won't try to access some data structure at the same time.

There's nothing new in that, if you've programmed microcontrollers before without an OS, you've accustomed to disabling interrupts as a mean of synchronization. The only difference is that in multicore architectures, you'll have to remember to take the ''FastGlobalLockFromIrq'' also from within interrupt handlers before calling the scheduler API to wakeup tasks, as the scheduler could be running on another core causing a race condition. In single core architectures you don't technically need to put a ''FastGlobalLockFromIrq'' in interrupt handlers. If you do it will be optimized away as it's not required. Since there's no performance penalty, you may as well take the habit of always using ''FastGlobalLockFromIrq'', just in case your driver gets reused in a multicore chip.

Inside a critical section taking the GIL you should not call functions that cause a preemption, such as almost all high-level function form the C++ standard library (including ''printf()'', '''malloc()/new''' and filesystem-related functions). Also, the only functions that are part of the Miosix kernel API that are safe to be called with the GIL locked are prefixed with IRQ. Why IRQ and not GIL you may say? It's because of older version of the kernel, before multicore support was introduced.

More importantly, all functions of the kernel that are prefixed with IRQ are '''only''' safe to be called if you're holding the GIL.

Some functions have both an IRQ and non IRQ version, such as ''miosix::getTime()'' and miosix::IRQgetTime()''.

== The PK lock ==
The PauseKernelLock or "PK". This lock disables preemption. This means that the code fragment taking the lock cannot be preempted by other threads, but can be interrupted by interrupts. On multicore architectures, only up to '''one''' core can take the PK at any given time. If a second core attempts to take the PK while another core has already taken it, it will block execution until the core holding the PK has released it. Note that on multicore architectures, it is allowed for one core can take the GIL, while another core can take the PK.

If the time spent with preemption disabled exceeds the thread's timeslice a preemption will occur immediately when releasing the lock.

Despite faster than a mutex, these synchronization primitives carry some heavy restrictions, and are mostly used to implement parts of the kernel itself. The main isssue is that you must never force a preemption when the kernel is paused. If this happens, the kernel will likely lock up badly. Of course, this means you can't call ''Thread::yield()'' when the kernel is paused, but there are many more subtler ways to cause a preemption.

In general, inside a critical section taking the GIL you should not call functions that cause a preemption, such as almost all high-level function form the C++ standard library (including ''printf()'' and filesystem-related functions). Also, the only functions that are part of the Miosix kernel API that are safe to be called with the PK locked are prefixed with PK.

All in all, you won't find much need to use the PK synchronization primitive, unless you're writing kernel code. At that point, you'll find it useful. Miosix uses it internally to make regular mutexes and condition variables work.

== Summarizing it all ==
The following table summarizes what you can do depending on what low level synchronization primitive you are using, as well as when you are writing the code of an interrupt service routine.

Although it may seem complicated, it is because it contains all possible cases, most of which are rather uncommon. In most cases you'll be writing code while not being into the scope of any low level lock, so you can do everything but call functions prefixed with IRQ or PK. When you are within an interrupt or take the GIL, the other most common case, you will usually not need to call any function besides the kernel API prefixed with IRQ.

{| class="wikitable"
|
| file related operations
| printf, scanf, cin, cout
| Thread::yield(), Thread::sleep(), usleep()
| call kernel functions with no prefix
| call kernel functions with PK prefix
| call kernel functions with IRQ prefix
| allocate memory
| throw C++ exceptions
| delayMs() and delayUs()
|-
| Normal code
| style="background-color: #80ff80;" | Yes
| style="background-color: #80ff80;" | Yes
| style="background-color: #80ff80;" | Yes
| style="background-color: #80ff80;" | Yes
| style="background-color: #ff8080;" | No
| style="background-color: #ff8080;" | No
| style="background-color: #80ff80;" | Yes
| style="background-color: #80ff80;" | Yes
| style="background-color: #80ff80;" | Yes
|-
| Within a PauseKernelLock
| style="background-color: #ff8080;" | No
| style="background-color: #ff8080;" | No
| style="background-color: #ff8080;" | No
| style="background-color: #ff8080;" | No
| style="background-color: #80ff80;" | Yes
| style="background-color: #ff8080;" | No
| style="background-color: #80ff80;" | Yes
| style="background-color: #80ff80;" | Yes
| style="background-color: #80ff80;" | Yes
|-
| Within an GlobalIrqLock
| style="background-color: #ff8080;" | No
| style="background-color: #ff8080;" | No
| style="background-color: #ff8080;" | No
| style="background-color: #ff8080;" | No
| style="background-color: #ff8080;" | No
| style="background-color: #80ff80;" | Yes
| style="background-color: #ff8080;" | No **
| style="background-color: #ff8080;" | No **
| style="background-color: #80ff80;" | Yes
|-
| Within a FastGlobalIrqLock
| style="background-color: #ff8080;" | No
| style="background-color: #ff8080;" | No
| style="background-color: #ff8080;" | No
| style="background-color: #ff8080;" | No
| style="background-color: #ff8080;" | No
| style="background-color: #ffff80;" | Yes *
| style="background-color: #ff8080;" | No
| style="background-color: #ff8080;" | No
| style="background-color: #80ff80;" | Yes
|-
| Within an interrupt service routine (taking FastGlobalLockFromIrq in the multicore case)
| style="background-color: #ff8080;" | No
| style="background-color: #ff8080;" | No
| style="background-color: #ff8080;" | No
| style="background-color: #ff8080;" | No
| style="background-color: #ff8080;" | No
| style="background-color: #ffff80;" | Yes *
| style="background-color: #ff8080;" | No
| style="background-color: #ff8080;" | No
| style="background-color: #80ff80;" | Yes
|-
|}
<nowiki>*</nowiki> = Most IRQ-prefixed functions can be called both with interrupts disabled (either within an ''GlobalIrqLock'', ''FastGlobalIrqLockLock'' or ''FastGlobalLockFromIrq'') and within an interrupt routine. The only exception being ''IRQregisterIrq'' and ''IRQunregisterIrq'' which are used for registering/unregistering interrupts, that cannot be called from within an interrupt handler and forcedly require a ''GlobalIrqLock''. Refer to the doxygen documentation of the individual function when unsure.

<nowiki>**</nowiki> = USed to be possible from Miosix v1.61 to Miosix v2.81, no longer possible due to multicore support. Now that a core can take the GIL and another core the PK, we must enforce that taking both locks can only be done by first taking the PK and then "upgrading" to the GIL. Doing the reverse would cause deadlocks, and since malloc/new take the PK, it's no longer possible to first take the GIL and then malloc.

[[Category:API]]

Synchronization primitives

2026-05-15T15:50:51Z

Fede.tft:

Miosix provides synchronization primitives, both high and low level. High level synchronization primitives are standard mutexes and condition variables that are familiar to programmers of multithreaded applications. This page addresses in more detail the low level synchronization primitives which are Miosix-specific, and is most useful when developing low level code, especially device drivers, on Miosix.

= High level synchronization primitives =
For what concerns high level synchronization primitives, Miosix provides the ususal mutexes and condition variables, accessible through three APIs:
* The C++11 classes such as ''std::thread'', ''std::mutex'' and ''std::condition_variable'' through the C++ standard library
* The POSIX thread functions and opaque data types such as ''pthread_t'', ''pthread_mutex_t'' and ''pthread_cond_t'' through the C standard library
* The native Miosix API which is the underlying implementation of all the other APIs. This is a C++ API including class ''Thread'' which is the actual Task Control Block (TCB) used by the scheduler, and classes ''Mutex'', ''FastMutex'', ''KernelMutex'' and ''ConditionVariable''

The use for these synchronization primitives is to protect data structures from concurrent access by multiple threads. These synchronization primitives are very easy to use, with almost no preconditions or special requirements, but cannot be used for more low-level tasks, such as synchronizing between threads and interrupt routines.

Both the mutex and the condition variable are optimized for speed, for example a lock/unlock pair of function calls to an uncontended mutex take around 100 clock cycles on an architecture such as the Cortex-M. Recursive mutexes are supported, and so are mutexes with priority inheritance, as well as timed waits on condition variables.

Just like the standard C++, RAII-style mutex locking is recommended also with the native API, through the provided ''Lock<T>'' and ''Unlock<T>'' classes.
Compare this example using directly the ''Mutex'' member functions

<source lang="CPP">
class Foo
{
int x;
Mutex m;
public:
void decIfPositive()
{
m.lock();
if(x<=0) return;
x--;
m.unlock();
}
};
</source>

As you can see, the code contains an error: the return in the middle of the function does not unlock the mutex, something that will likely cause problems.

On the other hand, if a ''Lock''' is used

<source lang="CPP">
class Foo
{
int x;
Mutex m;
public:
void decIfPositive()
{
Lock<Mutex> l(m);
if(x<=0) return;
x--;
}
};
</source>

you don't have to worry about that. When considering that functions can return due to a propagation of a C++ exception, using locks is the only way to write exception-safe C++ code.

If you need to temporarily unlock a mutex from within a scope where a ''Lock'' is in effect, this is made possible by creating an inner scope and using an ''Unlock'' object, like this:

<source lang="CPP">
Mutex m;
{
Lock<Mutex> l(m);
//Now the Mutex is locked
{
Unlock<Mutex> u(l);
//Now the mutex is unlocked
}
//Now the Mutex is again locked
}
</source>

Note how to create an ''Unlock'' object you have to pass a ''Lock'' to its constructor. This prevents you from trying to unlock a mutex you have not locked.

For what concerns the ''ConditionVariable'' class, it provides the ''wait()'', ''signal()'' and ''broadcast()'' member functions as you'd expect. Moreover, there's an overload of ''wait()'' taking a ''Lock'' instead of a bare mutex for convenience.

= Low level synchronization primitives =

Miosix provides two low-level synchronization primitives, the GlobalIrqLock or "GIL" and the PauseKernelLock or "PK".

== The GIL lock ==

The GlobalIrqLock or "GIL". On single core architectures, this lock disables interrupts and makes the code fragment taking this lock uninterruptible, not even by interrupt handlers. On multicore architectures, this lock disables interrupts on the core taking the lock, making the code fragment using it uninterruptible, not even by interrupt handlers. Additionally, only up to '''one''' core can take the GIL at any given time. If a second core attempts to take the GIL while another core has already taken it, it will block execution until the core holding the GIL has released it. Taking the GIL must be done using one of three [https://en.wikipedia.org/wiki/RAII RAII] C++ classes: ''GlobalIrqLock'', which is recursive, thus allowing to take the lock multiple times, ''FastGlobalIrqLock'', a faster but non-recursive version, or ''FastGlobalLockFromIrq'', the only version that can be used to take the GIL from an interrupt handler (this version is not recursive).

The GIL is used to implement device drivers that make use of interrupts, as well as inside the kernel, by the scheduler which also runs from inside an interrupt. Since both use the same lock, it's possible for an interrupt handler in a device driver to wakeup a thread from within an interrupt handler without corrupting the scheduler data structures.

The reason why a regular mutex cannot be used for this purpose is because interrupts are by their very nature asymmetric. An interrupt can interrupt the code of a thread, but a thread cannot interrupt an interrupt. This means that when you're writing device drivers and you need to synchronize between an interrupt and normal code a mutex won't do the job. If the mutex is already locked when the interrupt code starts, trying to lock it within the interrupt will attempt to block the interrupt till the thread unlocks it, and as you can imagine, this won't end up well.

To synchronize in such cases you have to temporarily disable interrupts from within your thread or main program, so that the thread and the interrupt won't try to access some data structure at the same time.

There's nothing new in that, if you've programmed microcontrollers before without an OS, you've accustomed to disabling interrupts as a mean of synchronization. The only difference is that in multicore architectures, you'll have to remember to take the ''FastGlobalLockFromIrq'' also from within interrupt handlers before calling the scheduler API to wakeup tasks, as the scheduler could be running on another core causing a race condition. In single core architectures you don't technically need to put a ''FastGlobalLockFromIrq'' in interrupt handlers. If you do it will be optimized away as it's not required. Since there's no performance penalty, you may as well take the habit of always using ''FastGlobalLockFromIrq'', just in case your driver gets reused in a multicore chip.

Inside a critical section taking the GIL you should not call functions that cause a preemption, such as almost all high-level function form the C++ standard library (including ''printf()'' and filesystem-related functions). Also, the only functions that are part of the Miosix kernel API that are safe to be called with the GIL locked are prefixed with IRQ. Why IRQ and not GIL you may say? It's because of older version of the kernel, before multicore support was introduced.

More importantly, all functions of the kernel that are prefixed with IRQ are '''only''' safe to be called if you're holding the GIL.

Some functions have both an IRQ and non IRQ version, such as ''miosix::getTime()'' and miosix::IRQgetTime()''.

== The PK lock ==
The PauseKernelLock or "PK". This lock disables preemption. This means that the code fragment taking the lock cannot be preempted by other threads, but can be interrupted by interrupts. On multicore architectures, only up to '''one''' core can take the PK at any given time. If a second core attempts to take the PK while another core has already taken it, it will block execution until the core holding the PK has released it. Note that on multicore architectures, it is allowed for one core can take the GIL, while another core can take the PK.

If the time spent with preemption disabled exceeds the thread's timeslice a preemption will occur immediately when releasing the lock.

Despite faster than a mutex, these synchronization primitives carry some heavy restrictions, and are mostly used to implement parts of the kernel itself. The main isssue is that you must never force a preemption when the kernel is paused. If this happens, the kernel will likely lock up badly. Of course, this means you can't call ''Thread::yield()'' when the kernel is paused, but there are many more subtler ways to cause a preemption.

In general, inside a critical section taking the GIL you should not call functions that cause a preemption, such as almost all high-level function form the C++ standard library (including ''printf()'', '''malloc()/new''' and filesystem-related functions). Also, the only functions that are part of the Miosix kernel API that are safe to be called with the PK locked are prefixed with PK.

All in all, you won't find much need to use the PK synchronization primitive, unless you're writing kernel code. At that point, you'll find it useful. Miosix uses it internally to make regular mutexes and condition variables work.

== Summarizing it all ==
The following table summarizes what you can do depending on what low level synchronization primitive you are using, as well as when you are writing the code of an interrupt service routine.

Although it may seem complicated, it is because it contains all possible cases, most of which are rather uncommon. In most cases you'll be writing code while not being into the scope of any low level lock, so you can do everything but call functions prefixed with IRQ or PK. When you are within an interrupt or inside a lock to disable interrupts, the other most common case, you will usually not need to call any function, but just modify some of your own data structures.

{| class="wikitable"
|
| file related operations
| printf, scanf, cin, cout
| Thread::yield(), Thread::sleep(), usleep()
| call kernel functions with no prefix
| call kernel functions with PK prefix
| call kernel functions with IRQ prefix
| allocate memory
| throw C++ exceptions
| delayMs() and delayUs()
|-
| Normal code
| style="background-color: #80ff80;" | Yes
| style="background-color: #80ff80;" | Yes
| style="background-color: #80ff80;" | Yes
| style="background-color: #80ff80;" | Yes
| style="background-color: #ff8080;" | No
| style="background-color: #ff8080;" | No
| style="background-color: #80ff80;" | Yes
| style="background-color: #80ff80;" | Yes
| style="background-color: #80ff80;" | Yes
|-
| Within a PauseKernelLock
| style="background-color: #ff8080;" | No
| style="background-color: #ff8080;" | No
| style="background-color: #ff8080;" | No
| style="background-color: #ff8080;" | No
| style="background-color: #80ff80;" | Yes
| style="background-color: #ff8080;" | No
| style="background-color: #80ff80;" | Yes
| style="background-color: #80ff80;" | Yes
| style="background-color: #80ff80;" | Yes
|-
| Within an InterruptDisableLock
| style="background-color: #ff8080;" | No
| style="background-color: #ff8080;" | No
| style="background-color: #ff8080;" | No
| style="background-color: #ff8080;" | No
| style="background-color: #ff8080;" | No
| style="background-color: #ffff80;" | Yes *
| style="background-color: #80ff80;" | Yes **
| style="background-color: #80ff80;" | Yes **
| style="background-color: #80ff80;" | Yes
|-
| Within a FastInterruptDisableLock
| style="background-color: #ff8080;" | No
| style="background-color: #ff8080;" | No
| style="background-color: #ff8080;" | No
| style="background-color: #ff8080;" | No
| style="background-color: #ff8080;" | No
| style="background-color: #ffff80;" | Yes *
| style="background-color: #ff8080;" | No
| style="background-color: #ff8080;" | No
| style="background-color: #80ff80;" | Yes
|-
| Within an interrupt service routine
| style="background-color: #ff8080;" | No
| style="background-color: #ff8080;" | No
| style="background-color: #ff8080;" | No
| style="background-color: #ff8080;" | No
| style="background-color: #ff8080;" | No
| style="background-color: #ffff80;" | Yes *
| style="background-color: #ff8080;" | No
| style="background-color: #ff8080;" | No
| style="background-color: #80ff80;" | Yes
|-
|}
<nowiki>*</nowiki> = Most IRQ-prefixed functions can be called both with interrupts disabled (either within an ''InterruptDisableLock'' or ''FastInterruptDisableLock'') and within an interrupt routine. A few of them can only be called with interrupts disabled but not within an interrupt routine, and one of them, ''IRQfindNextThread()'' which is the scheduler, can only be called inside an interrupt routine but not with interrupts disabled. Refer to the doxygen documentation of the individual function when unsure.

<nowiki>**</nowiki> = Starting from Miosix v1.61

[[Category:API]]

GPIO tutorial

2026-05-15T15:08:39Z

Fede.tft:

Include statements and namespace required to use this library
<source lang="CPP">
#include <miosix.h>
using namespace miosix;
</source>
This is a C++ library, it cannot be used from a C source file.

A [https://en.wikipedia.org/wiki/GPIO GPIO] or general purpose input-output is a software-controllable pin of a microcontroller. To be able to control multiple GPIOs at the same time, most microcontrollers group GPIOs in ports, so GPIOs are specified by a port name, and a pin number within the port. The STM32 use letters to identify ports, so the GPIO 0 of port A is called PA0. The GPIO port and number are often specified at the pin headers on development boards such as the [[stm32f407vg_stm32f4discovery|STM32F4 Discovery]], in order to make it easy to connect wires to the correct GPIO. On the contrary, NXP uses numbers also for the ports, so the GPIO 0 of port 1 is called P1.0.

== Declaring GPIOs ==

A GPIO in Miosix is accessed using a C++ template class, the rationale behind this choice can be found [http://www.webalice.it/fede.tft/stm32/stm32_gpio_and_template_metaprogramming.html in this article], but in short it provides both optimal performance and a high-level API.

As an example, assume there is a blue LED connected to GPIO PD15 and a button connected to PA0, to control them in software you first have to declare the GPIOs using the following syntax

<source lang="CPP">
using blueLed=Gpio<PD,15>;
using button=Gpio<PA,0>;
</source>

A declaration like this can appear both inside a function, if you are going to use the GPIO only inside that function, or be put at the top of a source file, to access the GPIO from all the functions of that file. It ca also appear in a header, allowing to ''#include'' GPIO definitions in multiple source files. Notice how PD means that this is a GPIO of port D, and 15 is the GPIO number within the port. This declaration introduces a template named blueLed that can later be used to access the GPIO.

A common mistake is to declare the GPIO like this

<source lang="CPP">
/* DON'T WRITE CODE LIKE THIS */
using pd15=Gpio<GPIOD_BASE,15>;
using pa0=Gpio<GPIOA_BASE,0>;
</source>

While the following code will work, it is discouraged to choose the GPIO name as just the port and number. It is way better to try using a name related to the function that the GPIO will be used for, as it leads to code that is easier to read and understand. For example, the first GPIO is connected to a blue LED, so blueLed is an appropriate name.

== Configuring GPIOs ==

Once you have declared a GPIO, you need to to configure it before using it. The most basic level of configuration is to select the GPIO ''direction'', i.e, whether it is going to be used as an output, or an input.

If a GPIO is configured as an output software can control the voltage at that pin, by selecting between a logic level 0, which corresponds to 0V, or a logic 1, whose voltage is VDD, which is the voltage used to power the microcontroller, in most cases 3.3V for the typical microcontrollers supported by Miosix.

If a GPIO is configured as an input, software can sense the logic level at the pin, reading a logic level 0 if the voltage is close to 0V, or a logic 1 if it is close to VDD. Note that if the voltage is closed to hald of VDD, or if the GPIO is not connected to anything, the reading could be either 0 or 1, see the discussion about [https://en.wikipedia.org/wiki/Pull-up_resistor pull-up resistors] on Wikipedia for that.

To configure the GPIO you can use the ''mode()'' member function of the GPIO class. For example, in your ''main()'' function you can do

<source lang="CPP">
int main()
{
blueLed::mode(Mode::OUTPUT);
button::mode(Mode::INPUT);
}
</source>

Note that all boards supported by Miosix have the ''OUTPUT'' and ''INPUT'' modes, but may have more options.

Some for example, may have software controllable on-chip pull-up and/or pull-down resistors, or an analog input mode connected to an ADC to read analog voltages. The list of supported modes can be found in the gpio_impl.h file of your microcontroller. For example, for the STM32F4 chips, the file is in [https://github.com/fedetft/miosix-kernel/blob/master/miosix/arch/drivers/gpio/stm32_gpio.h miosix/arch/drivers/gpio/stm32_gpio.h].

A noteworty example is the ALTERNATE function mode, that when selected connects the GPIO to some device-dependent hardware peripheral, such as an SPI, I2C or UART peripheral. In such a case, the pin stops being a GPIO in the sense that it is no longer software controllable, but is instead driven by the hardware peripheral. This is often used to implement communication protocols like SPI or I2C.

However, these device-specific extensions are not discussed further here.

== GPIO Writing ==

To write to an OUTPUT configured GPIO, you can used the ''high()'' and ''low()'' member functions, as shown in this example that blinks a LED

<source lang="CPP">
#include <thread>
#include <miosix.h>

using namespace std;
using namespace miosix;

using blueLed=Gpio<GPIOD_BASE,15>;

int main()
{
blueLed::mode(Mode::OUTPUT);
for(;;)
{
blueLed::high(); //Turn the LED on
this_thread::sleep_for(500ms);
blueLed::low(); //Turn the LED off
this_thread::sleep_for(500ms);
}
}
</source>

== GPIO Reading ==

Reading from an INPUT configured GPIO is performed by using the ''value()'' member function, as shown in this example that polls a button every 10ms and turns on a LED for 10 seconds once it detects it is pressed.

<source lang="CPP">
#include <thread>
#include <miosix.h>

using namespace std;
using namespace miosix;

using blueLed=Gpio<GPIOD_BASE,15>;
using button=Gpio<GPIOA_BASE,0>;

int main()
{
blueLed::mode(Mode::OUTPUT);
button::mode(Mode::INPUT);
for(;;)
{
//Poll the button every 10ms until it is pressed
while(button::value()==0) this_thread::sleep_for(10ms);

blueLed::high(); //Turn the LED on
this_thread::sleep_for(10s);
blueLed::low(); //Turn the LED off
}
}
</source>

A common mistake is to forget the sleep when polling for the button, resulting in a code like this

<source lang="CPP">
/* DON'T WRITE CODE LIKE THIS */
for(;;)
{
//Poll the button until it is pressed
while(button::value()==0) ;

blueLed::high(); //Turn the LED on
Thread::sleep(10000); //Wait 10s
blueLed::low(); //Turn the LED off
}
</source>

Although this code will work, it is bad. To see why, consider that Miosix is a multithreaded OS, so in the general case there will be other threads running other than your code, so it is not polite to spin in a while loop that may take an undefined time to complete chewing up 100% of the CPU. This will for sure prevent the kernel from putting the CPU in sleep resulting in a higher power consumption, and may slow down other threads that can have more important tasks to do than spinning on a GPIO.

But you may be thinking that your application needs to be notified of the button being pressed ''as soon as possible'' and even a few milliseconds of delay are too much. In this case, this code is '''even more wrong''', because Miosix is a timesharing system, so your code can and will be preempted by the operating system to prevent other threads from starving. If the event that you need to be notified about happens while your code is preempted, there will be a delay of up to a few milliseconds between the actual event and when you notice it anyway.

To deal with situations where you need to be notified of pin change events events as soon as possible you need something more complicated, such as an [[Interrupt on pin change]] that will call an interrupt routine in response to an event, usually offering a time determinism of a few tens of microseconds, or a [[Timer input capture]] channel that provides a timestamp of an event with an accuracy of a few tens of nanoseconds.

== Thread safety considerations ==

All microcontroller, for self-evident reasons, provide hardware support to allow writing to GPIOs configured as OUTPUT in a thread-safe way, so you are free to call the ''high()'' and ''low()'' (and ''value()'' as well) from multiple threads.

Unfortunately, configuring GPIOs is on most microcontrollers not thread-safe. That is, if you call ''mode()'' concurrently from multiple threads on the same GPIO port, you may inadvertently misconfigure some of the pins in that port.

There are two ways to work around that, configuring all GPIOs in the ''main()'' before spawning any thread, and disabling interrupts while configuring GPIOs.

=== Configuring GPIOs in the main() ===

If you configure all the GPIOs in the ''main()'', before spawning any thread, and later you no longer call ''mode()'' there are no way two threads could call ''mode()'' concurrently, and so there is no problem. However, this often goes against code modularity, and in some circumstances you may need to change a GPIO configuration at runtime.

=== Disabling interrupts while configuring GPIOs ===

To allow ''mode()'' to be freely called, you have to make sure no two concurrent calls to ''mode()'' can happen. Considering that configuring a GPIO is a very fast operation, it requires just a few clock cycles, this can be achieved by disabling interrupts while configuring the GPIOs. Keep in mind that disabling interrupts must be done with care, and striving as much as possible to minimize the amount of time spent with interrupts disabled, so as not to interfere with the real-time capabilities of the Miosix kernel.

<source lang="CPP">
void someFunction()
{
[...] //Some code

{
FastGlobalIrqLock dLock;
blueLed::mode(Mode::OUTPUT);
button::mode(Mode::INPUT);
}

[...] //Some other code
}
</source>

Note the two curly braces surrounding the dLock object, that create a [https://en.wikipedia.org/wiki/Scope_%28computer_science%29 scope] delimiting the lines of code where interrupts are disabled.

As a last note, you could also use a global [https://en.wikipedia.org/wiki/Mutex mutex] instead of disabling interrupts, but as previously mentioned configuring a GPIO is a very fast operation, it requires just a few clock cycles, so using a mutex would introduce more overhead.

== Accessing GPIOs from multiple source files ==

When dealing with large projects, it is common to split them in multiple source files. To access the GPIO definitions from multiple source files it is common practice in Miosix to declare them in a C++ header file, and ''#include'' it where needed. If that file contains all the GPIOs of a specific board, is is often called ''hwmapping.h''. In such a case, [https://en.wikipedia.org/wiki/Namespace#Examples namespaces] can be used to group GPIOs by function. For an example, see the ''hwmapping.h'' file for the Sony smartwatch board [https://github.com/fedetft/miosix-kernel/blob/master/miosix/arch/board/stm32f205rg_sony-newman/interfaces-impl/hwmapping.h miosix/arch/board/stm32f205rg_sony-newman/interfaces-impl/hwmapping.h].

== Related pages ==
* [[Example: Blinking led|Blinking led]]

[[Category:API]]

Miosix and git workflow

2026-05-15T14:52:00Z

Fede.tft:

= The Miosix git repository =

Miosix uses the git version control system to manage the kernel source code. To download and use the kernel you have to clone its git repository. The main Miosix git repository is hosted on this website, miosix.org, but we have no web page where you can browse the kernel sources. For this, we use a [https://github.com/fedetft/miosix-kernel github mirror] and the two repositories will be always kept in sync.

As the kernel is under active development, users are advised to periodically ''git fetch'' or check the [https://github.com/fedetft/miosix-kernel kernel page on github] to look for new features and bug fixes, and pull the changes if required.

Cloning the kernel repository from miosix.org can be done with:

<source lang="bash">
git clone https://miosix.org/git-public/miosix-kernel.git
</source>

While cloning the github mirror with:

<source lang="bash">
git clone https://github.com/fedetft/miosix-kernel.git
</source>

== Branches ==

By default, when cloning a repository, git will download the ''master'' branch. Miosix offers two additional branches, ''testing'' and ''unstable'', and you should be aware of the conventions we use for how we manage branches:
* The ''master'' branch contains the stable kernel, it is updated infrequently, usually once a year when a new release is made. Sometimes, a few minor releases are updated in short order.
* The ''testing'' branch contains the in-development code that we consider almost ready. Use this branch to get more bleeding edge features.
* The ''unstable'' branch is where the Miosix development team is working. It's meant to be used only by people in contact with the development team, as we occasionally rebase and force-push changes, so you may have a hard time keeping your git repository in sync with ours (the commit you downloaded today may no longer exist after a force push). If you're writing applications, it's best to ignore this branch and wait for the desired change to trickle to testing.

To checkout a specific branch, once you have cloned the git repository, use the following command
<source lang="bash">
cd miosix-kernel
git checkout testing
</source>

= Using Miosix in your projects =

The rest of this page explains how to set up a software project making use of the Miosix kernel. There are basically two ways to do so:

* Using out of git tree projects: this is the suggested workflow for developing applications using Miosix. Your application directory (and optionally git repo) stay separate from the kernel directory and git repo. The kernel can be a git submodule of your project.
* Forking the Miosix kernel git repository. This is the suggested workflow for extending the kernel, such as adding new board support packages (BSPs).

The two workflows can be combined, for example you may want to fork the kernel to add your BSPs, and then use the forked kernel as submodule for developing your applications.

= Out of git tree projects =

Out of git tree projects allow you to write applications in a directory that stays separate from the Miosix kernel directory. When we say ''out of git tree'', we mean that your project is developed outside of the ''Miosix'' git tree. Your project can be a git repository too, but that is up to you to decide.

Additionally, a key part of an out of git tree project is that it allows to perform the kernel configuration (that requires editing configuration files) without the need to make changes to files within the Miosix git repo ''at all''. This last point is important both to have the Miosix git repository as a [http://www.git-scm.com/book/en/Git-Tools-Submodules git submodule] of your application's git repository, and to allow sharing the same downloaded copy of the Miosix kernel across different applications, each with its own configuration. The kernel source code size on the hard drive has grown bigger in recent years due to the inclusion of headers with peripheral registers definitions in the [https://github.com/fedetft/miosix-kernel/tree/master/miosix/arch/CMSIS CMSIS] directory, so you may want to share a single downloaded copy of the kernel across several projects.

Note that the ability to develop applications without making changes to the kernel directory is currently limited to the use case of configuring the kernel for one of the available BSPs. If you need to add BSPs to the kernel, then you'll most likely also have to fork the kernel repository. The ''most likely'' is due to ''generic'' BSPs in the kernel, which can be identified in the list of boards in [https://github.com/fedetft/miosix-kernel/blob/master/miosix/config/Makefile.inc Makefile.inc] as ''<chip name>_generic'' such as ''stm32f103xb_generic''. If you're writing an application for a board that has a chip with a generic BSP in the kernel, you can (unless you ''really'' need to run some custom code during boot) get away with selecting the generic BSP without forking the kernel. If there's no generic BSP for your chip, or need to add support for an entirely new chip, then you'll have to fork the kernel to add it.

== Organizing your out of git tree projects ==

For an out of git tree project, you need to create a directory in your computer that will contain your project. The ''miosix-kernel'' directory (and git repo) can either be a subdirectory of your project's directory (common option when adding the Miosix kernel as a git submodule to your project):

[[File:Out-of-tree-subdirectory.png]]

Or you can organize your projects side by side to the kernel (common when sharing a single kernel among multiple projects):

[[File:Out-of-tree-shared.png]]

The only constraint (it's a limitation in the Makefile build systems), is that the ''relative'' path from your project directory to the kernel should not contain spaces. This practically means that you should not give your project directories names with spaces.

== Adding Miosix as a submodule to your git project ==

Suppose you have a git repository called myapplication, which is the repo of your application, and you would like to download the miosix-kernel repository as a git submodule. Then open a shell in the test repository and type:

<source lang="bash">
git submodule init
git submodule add https://miosix.org/git-public/miosix-kernel.git miosix-kernel
git commit -m "Added miosix-kernel as a git submodule"
</source>

== Initializing an out of git tree project ==

Using out of git tree projects implies having a build system in your project directory that can both compile the source code of your application and the Miosix kernel. Miosix provides two build systems, Makefiles and [[CMake]]. In this tutorial we'll use Makefiles.

Miosix projects start from a template that you can find in the ''miosix-kernel/templates'' directory. You can copy the template yourself from the kernel source tree to your project directory, but in that case, you'll need to fix the relative paths in the build system. Alternatively, you can use the ''init_project_out_of_git_tree.pl'' script to initialize a project.

Additionally, the kernel configuration directory needs to be copied to your project. This is necessary because you'll need to make changes to those files to select kernel build options, at minimum which board you want to compile the kernel for.
As you may know, git submodules work well if you never make changes in the submodule directory, otherwise you will have to basically fork the submodule, or you will find yourself making changes to a repository in a detached head state and risk losing them at the next git pull.
For this reason, we'll copy the config directory to your project and make changes there. The ''init_project_out_of_git_tree.pl'' performs also this action for you.

=== Initialize a project using ''init_project_out_of_git_tree.pl'' ===

Just open a shell in your project directory and invoke the perl script in the kernel:

<source lang=bash>
perl <path to the kernel>tools/init_project_out_of_git_tree.pl
</source>

Thus for the case when the kernel is a subdirectory of your project that would be:
<source lang=bash>
perl miosix-kernel/tools/init_project_out_of_git_tree.pl
</source>

While for the side-by-side case:
<source lang=bash>
perl ../miosix-kernel/tools/init_project_out_of_git_tree.pl
</source>

Note that you have to run the script without moving the current directory away from the one of your project. This means you can't ''cd'' to the ''miosix-kernel/tools'' directory, run the script there, and then ''cd'' back. The script withes the project files to the current directory it's been invoked from.

If all goes well you'll get a message similar to:
<source lang=bash>
Successfully created Miosix project
Target directory: myapplication
Kernel directory: myapplication/miosix-kernel/miosix
</source>

and your project should now contain the ''config'' directory and the ''main.cpp'', ''Makefile'' and ''CMakeLists.txt'' files.

From there, you'll need to edit the configuration as desired, and start building your application starting from ''main.cpp''.

=== Manually copying a template ===

The perl script is convienient, but not necessary. It's possible to do the configuration manually by copying and editing files.

To do so, there are 3 steps involved.

First, copy the ''miosix-kernel/miosix/config'' directory to your project.

Second, copy a template form the ''miosix-kernel/templates'' directory to your project. The ''simple'' template configures the kernel as a unikernel and will run your application in kernelspace. The ''processes'' template will allow you to develop (part of) your application in a userspace process with memory protection, bu that's a more advanced topic realted to the [[fliod kernel]] concept.

You shouldn't copy the template directory, rather its content, so the ''main.cpp'', ''Makefile'' and ''CMakeLists.txt'' files in the case of the ''simple'' template.

Third and final step, you should edit the build system to point to the correct kernel and config directory. This step was done automatically by the perl script, in this case you'll have to do it manually.

Open the ''Makefile'' file, and edit the following lines:

<source lang=bash>
KPATH := ../../miosix
CONFPATH := $(KPATH)
</source>

The first line, defining the KPATH variable should be assigned to the relative path from your project directory to the kernel directory. If your ''miosix-kernel'' is a subdirectory of your project that should be:

<source lang=bash>
KPATH := miosix-kernel/miosix
</source>

The second line defines the CONFPATH variable, and since you want to the kernel to find the ''config'' directory in your project , and '''not''' the one in the ''miosix-kernel/miosix/config'' directory, you'll have to chege it to the current directory, or ''.'':

<source lang=bash>
CONFPATH := .
</source>

Finally, open ''CMakeLists.txt''. Also in this case you'll have to tell it where is the kernel directory, and to use the ''config'' directory in your project. The kernel directory is specified by replacing:

<source lang=bash>
set(MIOSIX_KPATH ${CMAKE_SOURCE_DIR}/../../miosix)
</source>

with:

<source lang=bash>
set(MIOSIX_KPATH ${CMAKE_SOURCE_DIR}/miosix-kernel/miosix)
</source>

Whiel to tell CMake to use the config directory in your project, uncomment the following line:

<source lang=bash>
set(MIOSIX_USER_CONFIG_PATH ${CMAKE_SOURCE_DIR}/config)
</source>

= Forking the Miosix git repository =

Forking the Miosix git repository simply means cloning the kernel repository and start making changes within the kernel. To clone the git repository you simply type the following commands:

<source lang="bash">
git clone https://miosix.org/git-public/miosix-kernel.git
cd miosix-kernel
git checkout testing
</source>

The Miosix top-level directory contains the following files and subdirectories:

[[File:Miosix-top-level-directory.png]]

The [https://github.com/fedetft/miosix-kernel/blob/master/README.md README.md] file contains more detailed information on how the kernel source code directory tree is structured, but a quick overview is that the entire kernel code is in the ''miosix'' subdirectory, ''templates'' contains application templates you can copy out of the kernel directory to create your out of tree projects, ''examples'' contains some demos of the Miosix APIs, wile ''tools'' contains scripts and support code that does not get compiled into the kernel. It also contains the scripts and patches used to build the [[Miosix Toolchain]], the GCC-based cross compiler used to build the kernel.

== Making changes ==

Once you start making changes you can simply commit in the cloned git repository. If you need to share your changes, perhaps because there are multiple developers, git allows to have multiple remotes for a repository, so you can leave the default remote to periodically pull updates and bugfixes from the upstream Miosix repository, as well as push and pull from your personal remote repository.

== Testing changes ==

Once you start making changes to the kernel, you'll most likely want to quickly test to see if they work, which entails compiling the kernel to check for compile-time errors, and flash it to a board to check the code works at run-time.

To do so you can set up a Miosix out of git tree project as described earlier that points to your cloned kernel, but there's a quicker way: building the templates from within the kernel tree.

To do so, you'll need to select the board you want to build directly in the [https://github.com/fedetft/miosix-kernel/blob/master/miosix/config/Makefile.inc miosix/config/Makefile.inc] inside the kernel source tree, and select additional options (if needed) directly in the [https://github.com/fedetft/miosix-kernel/blob/master/miosix/config/miosix_settings.h miosix/config/miosix_settings.h] inside the kernel source tree.

Ad this point, you can ''cd'' to the ''templates/simple'' (or any other template directory) and type

<source lang=bash>
make
make program
</source>

from that directory.

Although convenient, this comes with two caveats that you should be careful about:
* If you also use the kernel for making out of tree projects, the scripts such as ''init_project_out_of_git_tree.pl'', when copying the configuration and template directory to initialize a out of tree project, will also copy the testing code with it. This is often just a minor inconvenience, which can easily be solved in many ways, such as by using ''git stash'' before running an ''init_project_out_of_git_tree.pl'' script to temporarily stash those changes.
* You should remember to '''not commit''' these changes to configuration files, especially when you plan to contribute patches upstream. The list of boards in Makefile.inc should by default have all the available boards commented out, so as to let users select the board they want by uncommenting it.

== Running the Miosix regression testsuite ==

Miosix comes with a regression test suite that exercises most of the kernel code and is useful when making changes to the kernel to verify the absence of regressions.

To compile the testsuite you should follow the instructions above to moddify the kernel's ''miosix/config'' directory to select the board you want to run the testsuite on, and then compile the testuite that is in the ''tools/testsuite'' directory.

<source lang=bash>
cd tools/testsuite
make
make program
</source>

Note that compiled firmware of the testsuite is quite large since it contains every function of the kernel, especially if compiled with support for the filesystem and userspace processes.

Making it easier to run the testsuite on small microcontrollers with little FLASH and RAM memory is a work in progress, he Miosix development team "chops" the testsuite in smaller pieces by commenting out part of it and running it one piece at a time, this is a tip worth knowing if you need to run it on very small microcontrollers.

== Contributing to Miosix ==

Miosix uses a shared ownership model, meaning that you retain the copyright for the contributions you add to the kernel. Your contributions should however be licensed with the same license of the rest of the kernel:

<source lang=CPP>
/***************************************************************************
* Copyright (C) <year> by <your name> *
* *
* This program is free software; you can redistribute it and/or modify *
* it under the terms of the GNU General Public License as published by *
* the Free Software Foundation; either version 2 of the License, or *
* (at your option) any later version. *
* *
* This program is distributed in the hope that it will be useful, *
* but WITHOUT ANY WARRANTY; without even the implied warranty of *
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
* GNU General Public License for more details. *
* *
* As a special exception, if other files instantiate templates or use *
* macros or inline functions from this file, or you compile this file *
* and link it with other works to produce a work based on this file, *
* this file does not by itself cause the resulting work to be covered *
* by the GNU General Public License. However the source code for this *
* file must still be made available in accordance with the GNU General *
* Public License. This exception does not invalidate any other reasons *
* why a work based on this file might be covered by the GNU General *
* Public License. *
* *
* You should have received a copy of the GNU General Public License *
* along with this program; if not, see <http://www.gnu.org/licenses/> *
***************************************************************************/
</source>

Be sure to add the copyright notice to all nontrivial source files. An example of a trivial source file would be a forwarding header such as [https://github.com/fedetft/miosix-kernel/blob/master/miosix/arch/cpu/armv8m/interfaces-impl/endianness_impl.h this one].

If you wrote the file you want to add from scratch, just add your name to the copyright notice. If instead you copy-pasted the file from another one already present in the kernel and modified it (this often happens when making BSPs as there's almost always a similar BSP in the kernel to take inspiration from), just append your name to the list of authors of the file you copied.

Since we use github only as a mirror to our repository that we host on miosix.org, we do not accept pull requests. You will instead be required to make a [https://git-scm.com/docs/git-format-patch format-patch] with the changes you want to be pushed upstream and send it via email to fede.tft&&miosix.org (s/&&/@/). It may be a good idea to get in contact first to discuss the changes you want pushed upstream, especially if they include modifications to the kernel itself rather than being simply new BSPs.

When submitting patches for inclusion, please make sure that commits are small and self-contained, in order to simplify the integration process.

Your changes should apply to the latest ''testing'' branch. If changes are related to the kernel itself, we may request to rebase them on top of ''unstable''.

[[Category:Installation and Configuration]]

Miosix and git workflow

2026-05-15T14:34:44Z

Fede.tft:

= The Miosix git repository =

Miosix uses the git version control system to manage the kernel source code. To download and use the kernel you have to clone its git repository. The main Miosix git repository is hosted on this website, miosix.org, but we have no web page where you can browse the kernel sources. For this, we use a [https://github.com/fedetft/miosix-kernel github mirror] and the two repositories will be always kept in sync.

As the kernel is under active development, users are advised to periodically ''git fetch'' or check the [https://github.com/fedetft/miosix-kernel kernel page on github] to look for new features and bug fixes, and pull the changes if required.

Cloning the kernel repository from miosix.org can be done with:

<source lang="bash">
git clone https://miosix.org/git-public/miosix-kernel.git
</source>

While cloning the github mirror with:

<source lang="bash">
git clone https://github.com/fedetft/miosix-kernel.git
</source>

== Branches ==

By default, when cloning a repository, git will download the ''master'' branch. Miosix offers two additional branches, ''testing'' and ''unstable'', and you should be aware of the conventions we use for how we manage branches:
* The ''master'' branch contains the stable kernel, it is updated infrequently, usually once a year when a new release is made. Sometimes, a few minor releases are updated in short order.
* The ''testing'' branch contains the in-development code that we consider almost ready. Use this branch to get more bleeding edge features.
* The ''unstable'' branch is where the Miosix development team is working. It's meant to be used only by people in contact with the development team, as we occasionally rebase and force-push changes, so you may have a hard time keeping your git repository in sync with ours (the commit you downloaded today may no longer exist after a force push). If you're writing applications, it's best to ignore this branch and wait for the desired change to trickle to testing.

To checkout a specific branch, once you have cloned the git repository, use the following command
<source lang="bash">
cd miosix-kernel
git checkout testing
</source>

= Using Miosix in your projects =

The rest of this page explains how to set up a software project making use of the Miosix kernel. There are basically two ways to do so:

* Using out of git tree projects: this is the suggested workflow for developing applications using Miosix. Your application directory (and optionally git repo) stay separate from the kernel directory and git repo. The kernel can be a git submodule of your project.
* Forking the Miosix kernel git repository. This is the suggested workflow for extending the kernel, such as adding new board support packages (BSPs).

The two workflows can be combined, for example you may want to fork the kernel to add your BSPs, and then use the forked kernel as submodule for developing your applications.

= Out of git tree projects =

Out of git tree projects allow you to write applications in a directory that stays separate from the Miosix kernel directory. When we say ''out of git tree'', we mean that your project is developed outside of the ''Miosix'' git tree. Your project can be a git repository too, but that is up to you to decide.

Additionally, a key part of an out of git tree project is that it allows to perform the kernel configuration (that requires editing configuration files) without the need to make changes to files within the Miosix git repo ''at all''. This last point is important both to have the Miosix git repository as a [http://www.git-scm.com/book/en/Git-Tools-Submodules git submodule] of your application's git repository, and to allow sharing the same downloaded copy of the Miosix kernel across different applications, each with its own configuration. The kernel source code size on the hard drive has grown bigger in recent years due to the inclusion of headers with peripheral registers definitions in the [https://github.com/fedetft/miosix-kernel/tree/master/miosix/arch/CMSIS CMSIS] directory, so you may want to share a single downloaded copy of the kernel across several projects.

Note that the ability to develop applications without making changes to the kernel directory is currently limited to the use case of configuring the kernel for one of the available BSPs. If you need to add BSPs to the kernel, then you'll most likely also have to fork the kernel repository. The ''most likely'' is due to ''generic'' BSPs in the kernel, which can be identified in the list of boards in [https://github.com/fedetft/miosix-kernel/blob/master/miosix/config/Makefile.inc Makefile.inc] as ''<chip name>_generic'' such as ''stm32f103xb_generic''. If you're writing an application for a board that has a chip with a generic BSP in the kernel, you can (unless you ''really'' need to run some custom code during boot) get away with selecting the generic BSP without forking the kernel. If there's no generic BSP for your chip, or need to add support for an entirely new chip, then you'll have to fork the kernel to add it.

== Organizing your out of git tree projects ==

For an out of git tree project, you need to create a directory in your computer that will contain your project. The ''miosix-kernel'' directory (and git repo) can either be a subdirectory of your project's directory (common option when adding the Miosix kernel as a git submodule to your project):

[[File:Out-of-tree-subdirectory.png]]

Or you can organize your projects side by side to the kernel (common when sharing a single kernel among multiple projects):

[[File:Out-of-tree-shared.png]]

The only constraint (it's a limitation in the Makefile build systems), is that the ''relative'' path from your project directory to the kernel should not contain spaces. This practically means that you should not give your project directories names with spaces.

== Adding Miosix as a submodule to your git project ==

Suppose you have a git repository called myapplication, which is the repo of your application, and you would like to download the miosix-kernel repository as a git submodule. Then open a shell in the test repository and type:

<source lang="bash">
git submodule init
git submodule add https://miosix.org/git-public/miosix-kernel.git miosix-kernel
git commit -m "Added miosix-kernel as a git submodule"
</source>

== Initializing an out of git tree project ==

Using out of git tree projects implies having a build system in your project directory that can both compile the source code of your application and the Miosix kernel. Miosix provides two build systems, Makefiles and [[CMake]]. In this tutorial we'll use Makefiles.

Miosix projects start from a template that you can find in the ''miosix-kernel/templates'' directory. You can copy the template yourself from the kernel source tree to your project directory, but in that case, you'll need to fix the relative paths in the build system. Alternatively, you can use the ''init_project_out_of_git_tree.pl'' script to initialize a project.

Additionally, the kernel configuration directory needs to be copied to your project. This is necessary because you'll need to make changes to those files to select kernel build options, at minimum which board you want to compile the kernel for.
As you may know, git submodules work well if you never make changes in the submodule directory, otherwise you will have to basically fork the submodule, or you will find yourself making changes to a repository in a detached head state and risk losing them at the next git pull.
For this reason, we'll copy the config directory to your project and make changes there. The ''init_project_out_of_git_tree.pl'' performs also this action for you.

=== Initialize a project using ''init_project_out_of_git_tree.pl'' ===

Just open a shell in your project directory and invoke the perl script in the kernel:

<source lang=bash>
perl <path to the kernel>tools/init_project_out_of_git_tree.pl
</source>

Thus for the case when the kernel is a subdirectory of your project that would be:
<source lang=bash>
perl miosix-kernel/tools/init_project_out_of_git_tree.pl
</source>

While for the side-by-side case:
<source lang=bash>
perl ../miosix-kernel/tools/init_project_out_of_git_tree.pl
</source>

Note that you have to run the script without moving the current directory away from the one of your project. This means you can't ''cd'' to the ''miosix-kernel/tools'' directory, run the script there, and then ''cd'' back. The script withes the project files to the current directory it's been invoked from.

If all goes well you'll get a message similar to:
<source lang=bash>
Successfully created Miosix project
Target directory: myapplication
Kernel directory: myapplication/miosix-kernel/miosix
</source>

and your project should now contain the ''config'' directory and the ''main.cpp'', ''Makefile'' and ''CMakeLists.txt'' files.

=== Manually copying a template ===

= Forking the Miosix git repository =

Forking the Miosix git repository simply means cloning the kernel repository and start making changes within the kernel. To clone the git repository you simply type the following commands:

<source lang="bash">
git clone https://miosix.org/git-public/miosix-kernel.git
cd miosix-kernel
git checkout testing
</source>

The Miosix top-level directory contains the following files and subdirectories:

[[File:Miosix-top-level-directory.png]]

The [https://github.com/fedetft/miosix-kernel/blob/master/README.md README.md] file contains more detailed information on how the kernel source code directory tree is structured, but a quick overview is that the entire kernel code is in the ''miosix'' subdirectory, ''templates'' contains application templates you can copy out of the kernel directory to create your out of tree projects, ''examples'' contains some demos of the Miosix APIs, wile ''tools'' contains scripts and support code that does not get compiled into the kernel. It also contains the scripts and patches used to build the [[Miosix Toolchain]], the GCC-based cross compiler used to build the kernel.

== Making changes ==

Once you start making changes you can simply commit in the cloned git repository. If you need to share your changes, perhaps because there are multiple developers, git allows to have multiple remotes for a repository, so you can leave the default remote to periodically pull updates and bugfixes from the upstream Miosix repository, as well as push and pull from your personal remote repository.

== Testing changes ==

Once you start making changes to the kernel, you'll most likely want to quickly test to see if they work, which entails compiling the kernel to check for compile-time errors, and flash it to a board to check the code works at run-time.

To do so you can set up a Miosix out of git tree project as described earlier that points to your cloned kernel, but there's a quicker way: building the templates from within the kernel tree.

To do so, you'll need to select the board you want to build directly in the [https://github.com/fedetft/miosix-kernel/blob/master/miosix/config/Makefile.inc miosix/config/Makefile.inc] inside the kernel source tree, and select additional options (if needed) directly in the [https://github.com/fedetft/miosix-kernel/blob/master/miosix/config/miosix_settings.h miosix/config/miosix_settings.h] inside the kernel source tree.

Ad this point, you can ''cd'' to the ''templates/simple'' (or any other template directory) and type

<source lang=bash>
make
make program
</source>

from that directory.

Although convenient, this comes with two caveats that you should be careful about:
* If you also use the kernel for making out of tree projects, the scripts such as ''init_project_out_of_git_tree.pl'', when copying the configuration and template directory to initialize a out of tree project, will also copy the testing code with it. This is often just a minor inconvenience, which can easily be solved in many ways, such as by using ''git stash'' before running an ''init_project_out_of_git_tree.pl'' script to temporarily stash those changes.
* You should remember to '''not commit''' these changes to configuration files, especially when you plan to contribute patches upstream. The list of boards in Makefile.inc should by default have all the available boards commented out, so as to let users select the board they want by uncommenting it.

== Running the Miosix regression testsuite ==

Miosix comes with a regression test suite that exercises most of the kernel code and is useful when making changes to the kernel to verify the absence of regressions.

To compile the testsuite you should follow the instructions above to moddify the kernel's ''miosix/config'' directory to select the board you want to run the testsuite on, and then compile the testuite that is in the ''tools/testsuite'' directory.

<source lang=bash>
cd tools/testsuite
make
make program
</source>

Note that compiled firmware of the testsuite is quite large since it contains every function of the kernel, especially if compiled with support for the filesystem and userspace processes.

Making it easier to run the testsuite on small microcontrollers with little FLASH and RAM memory is a work in progress, he Miosix development team "chops" the testsuite in smaller pieces by commenting out part of it and running it one piece at a time, this is a tip worth knowing if you need to run it on very small microcontrollers.

== Contributing to Miosix ==

Miosix uses a shared ownership model, meaning that you retain the copyright for the contributions you add to the kernel. Your contributions should however be licensed with the same license of the rest of the kernel:

<source lang=CPP>
/***************************************************************************
* Copyright (C) <year> by <your name> *
* *
* This program is free software; you can redistribute it and/or modify *
* it under the terms of the GNU General Public License as published by *
* the Free Software Foundation; either version 2 of the License, or *
* (at your option) any later version. *
* *
* This program is distributed in the hope that it will be useful, *
* but WITHOUT ANY WARRANTY; without even the implied warranty of *
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
* GNU General Public License for more details. *
* *
* As a special exception, if other files instantiate templates or use *
* macros or inline functions from this file, or you compile this file *
* and link it with other works to produce a work based on this file, *
* this file does not by itself cause the resulting work to be covered *
* by the GNU General Public License. However the source code for this *
* file must still be made available in accordance with the GNU General *
* Public License. This exception does not invalidate any other reasons *
* why a work based on this file might be covered by the GNU General *
* Public License. *
* *
* You should have received a copy of the GNU General Public License *
* along with this program; if not, see <http://www.gnu.org/licenses/> *
***************************************************************************/
</source>

Be sure to add the copyright notice to all nontrivial source files. An example of a trivial source file would be a forwarding header such as [https://github.com/fedetft/miosix-kernel/blob/master/miosix/arch/cpu/armv8m/interfaces-impl/endianness_impl.h this one].

If you wrote the file you want to add from scratch, just add your name to the copyright notice. If instead you copy-pasted the file from another one already present in the kernel and modified it (this often happens when making BSPs as there's almost always a similar BSP in the kernel to take inspiration from), just append your name to the list of authors of the file you copied.

Since we use github only as a mirror to our repository that we host on miosix.org, we do not accept pull requests. You will instead be required to make a [https://git-scm.com/docs/git-format-patch format-patch] with the changes you want to be pushed upstream and send it via email to fede.tft&&miosix.org (s/&&/@/). It may be a good idea to get in contact first to discuss the changes you want pushed upstream, especially if they include modifications to the kernel itself rather than being simply new BSPs.

When submitting patches for inclusion, please make sure that commits are small and self-contained, in order to simplify the integration process.

Your changes should apply to the latest ''testing'' branch. If changes are related to the kernel itself, we may request to rebase them on top of ''unstable''.

[[Category:Installation and Configuration]]

File:Out-of-tree-shared.png

2026-05-15T14:08:58Z

Fede.tft:

Out-of-tree-shared

File:Out-of-tree-subdirectory.png

2026-05-15T14:07:15Z

Fede.tft:

Out-of-tree-subdirectory

Miosix and git workflow

2026-05-15T09:44:27Z

Fede.tft:

= The Miosix git repository =

Miosix uses the git version control system to manage the kernel source code. To download and use the kernel you have to clone its git repository. The main Miosix git repository is hosted on this website, miosix.org, but we have no web page where you can browse the kernel sources. For this, we use a [https://github.com/fedetft/miosix-kernel github mirror] and the two repositories will be always kept in sync.

As the kernel is under active development, users are advised to periodically ''git fetch'' or check the [https://github.com/fedetft/miosix-kernel kernel page on github] to look for new features and bug fixes, and pull the changes if required.

By default, when cloning a repository, git will download the ''master'' branch. Miosix offers two additional branches, ''testing'' and ''unstable'', and you should be aware of the conventions we use for how we manage branches:
* The ''master'' branch contains the stable kernel, it is updated infrequently, usually once a year when a new release is made. Sometimes, a few minor releases are updated in short order.
* The ''testing'' branch contains the in-development code that we consider almost ready. Use this branch to get more bleeding edge features.
* The ''unstable'' branch is where the Miosix development team is working. It's meant to be used only by people in contact with the development team, as we occasionally rebase and force-push changes, so you may have a hard time keeping your git repository in sync with ours (the commit you downloaded today may no longer exist after a force push). If you're writing applications, it's best to ignore this branch and wait for the desired change to trickle to testing.

Cloning the kernel repository from miosix.org can be done with:

<source lang="bash">
git clone https://miosix.org/git-public/miosix-kernel.git
</source>

While cloning the github mirror with:

<source lang="bash">
git clone https://github.com/fedetft/miosix-kernel.git
</source>

To checkout a specific branch, once you have cloned the git repository, use the following command
<source lang="bash">
cd miosix-kernel
git checkout testing
</source>

The rest of this page explains how to set up a software project making use of the Miosix kernel, that can later allow updating the kernel through git without creating problems. There are basically two ways to do so:

* Setting up out an out of git tree project: this is the suggested workflow for developing applications using Miosix. Your application directory and git repo stay separate from the kernel directory and git repo. The kernel can be a git submodule of your project.
* Forking the Miosix kernel git repository. This is the suggested workflow for extending the kernel, such as adding new board support packages (BSPs).

The two workflows can be combined, for example you may want to fork the kernel to add your BSPs, and then use the forked kernel as submodule for developing your applications.

= Setting up an out of git tree project =

Out of git tree projects allow you to write applications in a directory that stays separate from the Miosix kernel directory. Additionally, they allow to perform the kernel configuration (that requires editing configuration files) without the need to make changes to files within the Miosix git repo ''at all''. This last point is important both to have the Miosix git repository as a [http://www.git-scm.com/book/en/Git-Tools-Submodules git submodule] of your application's git repository, and to allow sharing the same downloaded copy of the Miosix kernel across different applications, each with its own configuration. The kernel source code size on the hard drive has grown bigger in recent years due to the inclusion of headers with peripheral registers definitions in the [https://github.com/fedetft/miosix-kernel/tree/master/miosix/arch/CMSIS CMSIS] directory, so you may want to share a single downloaded copy of the kernel across several projects.

Note that the ability to develop applications without making changes to the kernel directory is currently limited to the use case of configuring the kernel for one of the available BSPs. If you need to add BSPs to the kernel, then you'll most likely also have to fork the kernel repository. The ''most likely'' is due to ''generic'' BSPs in the kernel, which can be identified in the list of boards in [https://github.com/fedetft/miosix-kernel/blob/master/miosix/config/Makefile.inc Makefile.inc] as ''<chip name>_generic'' such as ''stm32f103xb_generic''. If you're writing an application for a board that has a chip with a generic BSP in the kernel, you can (unless you ''really'' need to run some custom code during boot) get away with selecting the generic BSP without forking the kernel. If there's no generic BSP for your chip, or need to add support for an entirely new chip, then you'll have to fork the kernel to add it.

Suppose you have a git repository called test, which is the repo of your application, and you would like to download the miosix-kernel repository as a git submodule. Then open a shell in the test repository and type

<source lang="bash">
git submodule init
git submodule add https://miosix.org/git-public/miosix-kernel.git miosix-kernel
cd miosix-kernel
git fetch origin
cd ..
git commit -a -m "Added miosix-kernel as a git submodule"
</source>

This solves the problem from the git side, now let's solve the problem from the Miosix side. As you may know, git submodules work well if you never make changes in the submodule directory, otherwise you will have to basically fork the submodule, or you will find yourself making changes to a repository in a detached head state and risk losing them at the next git pull.

However, the ''Makefile'' for Miosix, as well as configuration files such as [[Makefile.inc|miosix/config/Makefile.inc]] and [[miosix_settings.h|miosix/config/miosix_settings.h]] are within the submodule directory, so how are you going to make use of the kernel without touching files in the submodule directory?

The solution is out of git tree projects, a new feature added in Miosix 2.0 that basically moves the ''main.cpp'', ''Makefile'', ''config'' directory, and the Netbeans IDE project directory outside of the git repository, using tweaks to the ''Makefile'' paths so that the kernel will find the ''config'' directory outside of the kernel, not the one inside it.

To get started with out of git tree projects, there is a perl script that is used to easily set everything up. For example, suppose you are in the directory of your git repository where you have added the ''miosix-kernel'' submodule, and want to set up an out of git tree project there, open a shell and type

<source lang="bash">
perl miosix-kernel/miosix/_tools/init_project_out_of_git_tree.pl
</source>

The script will create a Miosix out of git tree project in the directory it is called, basically creating a ''config'' directory with a copy of the configuration files you can edit, a ''Makefile'' and a ''main.cpp'' as usual, as well as a new ''miosix_np_2'' directory with a Netbeans IDE project.

The main advantage of this solution is that it keeps your application and the kernel in two separate git repositories. The disadvantage is that if you need to make changes to the kernel other than to configuration files, you will need to clone the miosix-kernel repository anyway, as well as having to manage the complexity of having two git repositories.

= Forking the Miosix git repository =

Forking the Miosix git repository simply means cloning the kernel repository and start making changes within the kernel. To clone the git repository you simply type the following commands:

<source lang="bash">
git clone https://miosix.org/git-public/miosix-kernel.git
cd miosix-kernel
git checkout testing
</source>

The Miosix top-level directory contains the following files and subdirectories:

[[File:Miosix-top-level-directory.png]]

The [https://github.com/fedetft/miosix-kernel/blob/master/README.md README.md] file contains more detailed information on how the kernel source code directory tree is structured, but a quick overview is that the entire kernel code is in the ''miosix'' subdirectory, ''templates'' contains application templates you can copy out of the kernel directory to create your out of tree projects, ''examples'' contains some demos of the Miosix APIs, wile ''tools'' contains scripts and support code that does not get compiled into the kernel. It also contains the scripts and patches used to build the [[Miosix Toolchain]], the GCC-based cross compiler used to build the kernel.

== Making changes ==

Once you start making changes you can simply commit in the cloned git repository. If you need to share your changes, perhaps because there are multiple developers, git allows to have multiple remotes for a repository, so you can leave the default remote to periodically pull updates and bugfixes from the upstream Miosix repository, as well as push and pull from your personal remote repository.

== Testing changes ==

Once you start making changes to the kernel, you'll most likely want to quickly test to see if they work, which entails compiling the kernel to check for compile-time errors, and flash it to a board to check the code works at run-time.

To do so you can set up a Miosix out of git tree project as described earlier that points to your cloned kernel, but there's a quicker way: building the templates from within the kernel tree.

To do so, you'll need to select the board you want to build directly in the [https://github.com/fedetft/miosix-kernel/blob/master/miosix/config/Makefile.inc miosix/config/Makefile.inc] inside the kernel source tree, and select additional options (if needed) directly in the [https://github.com/fedetft/miosix-kernel/blob/master/miosix/config/miosix_settings.h miosix/config/miosix_settings.h] inside the kernel source tree.

Ad this point, you can ''cd'' to the ''templates/simple'' (or any other template directory) and type

<source lang=bash>
make
make program
</source>

from that directory.

Although convenient, this comes with two caveats that you should be careful about:
* If you also use the kernel for making out of tree projects, the scripts such as ''init_project_out_of_git_tree.pl'', when copying the configuration and template directory to initialize a out of tree project, will also copy the testing code with it. This is often just a minor inconvenience, which can easily be solved in many ways, such as by using ''git stash'' before running an ''init_project_out_of_git_tree.pl'' script to temporarily stash those changes.
* You should remember to '''not commit''' these changes to configuration files, especially when you plan to contribute patches upstream. The list of boards in Makefile.inc should by default have all the available boards commented out, so as to let users select the board they want by uncommenting it.

== Running the Miosix regression testsuite ==

Miosix comes with a regression test suite that exercises most of the kernel code and is useful when making changes to the kernel to verify the absence of regressions.

To compile the testsuite you should follow the instructions above to moddify the kernel's ''miosix/config'' directory to select the board you want to run the testsuite on, and then compile the testuite that is in the ''tools/testsuite'' directory.

<source lang=bash>
cd tools/testsuite
make
make program
</source>

Note that compiled firmware of the testsuite is quite large since it contains every function of the kernel, especially if compiled with support for the filesystem and userspace processes.

Making it easier to run the testsuite on small microcontrollers with little FLASH and RAM memory is a work in progress, he Miosix development team "chops" the testsuite in smaller pieces by commenting out part of it and running it one piece at a time, this is a tip worth knowing if you need to run it on very small microcontrollers.

== Contributing to Miosix ==

Miosix uses a shared ownership model, meaning that you retain the copyright for the contributions you add to the kernel. Your contributions should however be licensed with the same license of the rest of the kernel:

<source lang=CPP>
/***************************************************************************
* Copyright (C) <year> by <your name> *
* *
* This program is free software; you can redistribute it and/or modify *
* it under the terms of the GNU General Public License as published by *
* the Free Software Foundation; either version 2 of the License, or *
* (at your option) any later version. *
* *
* This program is distributed in the hope that it will be useful, *
* but WITHOUT ANY WARRANTY; without even the implied warranty of *
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
* GNU General Public License for more details. *
* *
* As a special exception, if other files instantiate templates or use *
* macros or inline functions from this file, or you compile this file *
* and link it with other works to produce a work based on this file, *
* this file does not by itself cause the resulting work to be covered *
* by the GNU General Public License. However the source code for this *
* file must still be made available in accordance with the GNU General *
* Public License. This exception does not invalidate any other reasons *
* why a work based on this file might be covered by the GNU General *
* Public License. *
* *
* You should have received a copy of the GNU General Public License *
* along with this program; if not, see <http://www.gnu.org/licenses/> *
***************************************************************************/
</source>

Be sure to add the copyright notice to all nontrivial source files. An example of a trivial source file would be a forwarding header such as [https://github.com/fedetft/miosix-kernel/blob/master/miosix/arch/cpu/armv8m/interfaces-impl/endianness_impl.h this one].

If you wrote the file you want to add from scratch, just add your name to the copyright notice. If instead you copy-pasted the file from another one already present in the kernel and modified it (this often happens when making BSPs as there's almost always a similar BSP in the kernel to take inspiration from), just append your name to the list of authors of the file you copied.

Since we use github only as a mirror to our repository that we host on miosix.org, we do not accept pull requests. You will instead be required to make a [https://git-scm.com/docs/git-format-patch format-patch] with the changes you want to be pushed upstream and send it via email to fede.tft&&miosix.org (s/&&/@/). It may be a good idea to get in contact first to discuss the changes you want pushed upstream, especially if they include modifications to the kernel itself rather than being simply new BSPs.

When submitting patches for inclusion, please make sure that commits are small and self-contained, in order to simplify the integration process.

Your changes should apply to the latest ''testing'' branch. If changes are related to the kernel itself, we may request to rebase them on top of ''unstable''.

[[Category:Installation and Configuration]]

Miosix and git workflow

2026-05-15T08:56:53Z

Fede.tft:

File:Miosix-top-level-directory.png

2026-05-15T08:37:35Z

Fede.tft:

Miosix-top-level-directory

Miosix and git workflow

2026-05-15T08:15:52Z

Fede.tft:

Miosix and git workflow

2026-05-15T08:13:20Z

Fede.tft:

Miosix and git workflow

2026-05-15T08:09:25Z

Fede.tft:

Miosix and git workflow

2026-05-15T08:05:27Z

Fede.tft:

Miosix and git workflow

2026-05-15T08:04:41Z

Fede.tft:

Miosix and git workflow

2026-05-15T07:47:03Z

Fede.tft:

Miosix and git workflow

2026-05-15T07:41:12Z

Fede.tft:

MacOS Quick Start

2026-05-15T07:37:29Z

Fede.tft:

{{DISPLAYTITLE:macOS Quick Start}}
To be able to compile the Miosix kernel and your application, you need a patched version of the GCC compiler called [[Miosix Toolchain]]. This page explains how to install the precompiled Miosix Toolchain. If you prefer compiling GCC from sources, see [[Building GCC from sources]].

Both macOS and Linux are POSIX-conformant Unix-like systems, therefore the steps required to get started with Miosix are very similar on both operating systems. This guide only covers the differences between the steps outlined in [[Linux Quick Start]] and the steps needed for macOS. Therefore reading the [[Linux Quick Start]] page first is recommended.

== Before you begin ==

=== Installing the Command Line Tools ===

macOS provides essentials tools for developing software ([https://clang.llvm.org clang]-based C and C++ compilers, [https://git-scm.com git], and more) in a separate package called the ''Command Line Tools for Xcode''. Despite the name, these tools do not require Xcode to be also installed, and since Xcode is a multi-gigabyte application which eats up quite the amount of disk space, you should '''not''' install Xcode, unless you are sure you need it for some other non-Miosix-related reason.

To install the Command Line Tools open Terminal.app and then run the following command:

<syntaxhighlight>
xcode-select --install
</syntaxhighlight>

Then follow the instructions on screen to complete the installation.

=== Installing STM32-specific tools ===

STM32 microcontrollers are the most important target for Miosix, and programming them requires specialized tools which on Linux are often installed through a package manager.

In contrast to Linux but similarly to Windows, macOS does not provide a system package manager. However, thanks to community efforts, there are two third-party package managers for macOS that provide a similar experience to Linux for easily installing tools and programs on the command line: [https://brew.sh Homebrew] and [https://www.macports.org MacPorts]. Both of them provide all packages you need to get started with development on STM32 MCUs.

In the following discussion we will assume you have Homebrew available and installed on your system. If you prefer MacPorts, you can search the same packages (or 'ports') on the [https://ports.macports.org MacPorts port index].

With Homebrew, installing st-flash and stm32flash can be performed through the following commands:

<syntaxhighlight>
brew install stlink
brew install stm32flash
</syntaxhighlight>

==== Homebrew, macOS, and filesystem permissions ====

Homebrew specifically forbids being run with elevated privileges using <code>sudo</code> when installing packages. This is different than what all other package managers (on Linux and macOS) do.

[https://docs.brew.sh/FAQ#why-does-homebrew-say-sudo-is-bad According to Homebrew's developers], this approach purportedly has the advantage of reducing the attack surface of a hypothetic malware that modifies Homebrew's executables for malicious purposes, but it makes it possible for malware to modify all of the files installed by Homebrew easily (as executable distributed by Homebrew are often not signed).

Other package managers such as MacPorts (or all Linux-based package managers for the various distributions) run as root (or as a specialized user with reduced privileges) in order to make it more difficult for malware to tamper any file in the package manager's prefix, and to prevent un-authorized users from modifying the set of packages installed.

However tampering files installed by a package manager on macOS does not appear to be a popular attack vector for malware, thanks to the additional restrictions imposed on top of the standard Unix user permission system by the TCC subsystem in macOS ([https://eclecticlight.co/2023/02/11/permissions-sip-and-tcc-whos-controlling-access/ read this article] if you don't know what we are talking about). As a result the field importance of the security implications of Homebrew's choice about the ownership of all installed packages is not entirely clear.

However, being aware of the tradeoff being made is something to be aware of before you choose to install Homebrew or MacPorts, depending on your security-related preferences.

=== Serial port setup ===

Serial port devices are available in <code>/dev</code> just like in Linux, however macOS sets the permissions of the device files such that read and write access are available for all groups and users. There is no need to add you user to the <code>dialup</code> group like on Linux.

macOS ships with <code>screen</code> built-in, there is no need to install it separately. If you find <code>screen</code> uncomfortable to use for accessing serial ports, we recommend you use [https://github.com/tio/tio tio], which can be installed via Homebrew with this command:

<syntaxhighlight>
brew install tio
</syntaxhighlight>

== Install the Miosix Toolchain ==

Download the latest version of the toolchain from the link provided in the [[Miosix Toolchain]] page. Choose the appropriate version to your Mac architecture, as newer Macs use ARM processors, while older ones use Intel processors. We provide native builds of the Miosix toolchain for both architectures. Make sure to install the macOS installable package, and not the Linux or Windows ones. Then you can install the toolchain by double-clicking the downloaded .pkg file.

If the installer does not open and the following dialog box shows up:

[[File:MacOS unidentified developer.png|The dialog box shown when Gatekeeper prevents opening an installer package.]]

click with the right mouse button on the installer package (or click while pressing the ''control'' key on the keyboard) and select Open from the contextual menu. The dialog box will now let you open the package.

Follow the steps presented by the assistant to install the Miosix toolchain on your system.

== Get, configure, and compile the Miosix kernel sources ==

At this point you can start following the steps outlined in [[Linux Quick Start#Configuring and compiling the kernel]] without modifications.

Remember that there is no need to install ''git'' as it has been already installed as part of the Command Line Tools (if you have been following this guide to the letter).

Linux Debugger configuration

2026-05-10T21:44:46Z

Fede.tft:

The debugging of Miosix on Linux can be done through [http://openocd.org/ OpenOCD], that creates a bridge between GDB and the JTAG device.

= Setting up OpenOCD =

== Install OpenOCD ==
<source lang="bash">
sudo apt install openocd # Install OpenOCD for Ubuntu/Debian
</source>

== Run OpenOCD ==
The OpenOCD configuration is included in the official Miosix distribution for most of the supported boards under the path 'miosix/arch/board/<board name>/openocd.cfg'. For example for the stm32f429zi_stm32f4discovery board:
<source lang="bash">
openocd -f miosix/arch/board/stm32f429zi_stm32f4discovery/openocd.cfg
</source>

OpenOCD provides built-in configuration files for many boards, chips and debugging adapters. You can see the entire range of files in the directory <code>/usr/share/openocd/scripts</code>. If Miosix does not provide a configuration file for you, in most cases there will be appropriate scripts available together with OpenOCD.

'''If breakpoints don't work on your board''' you can try adding the option <code>-c 'gdb_breakpoint_override hard'</code> to the OpenOCD invocation. This option disables GDB software breakpoints and always forces the use of hardware breakpoints, which might be needed if OpenOCD provides an incomplete memory map to GDB.

= Debugging with GDB =
The GDB used is provided by the official [[Miosix_Toolchain|Miosix Toolchain]]. Although the board is flashed with the ''.bin'' file, you'll have to pass the corresponding ''.elf'' file, since this file format includes debugging symbols.
<source lang="bash">
arm-miosix-eabi-gdb main.elf
</source>

== Connect GDB ==
OpenOCD provide a network interface for connect the debugger, the follow command is necessary for establish the connection:
<source lang="bash">
(gdb) target remote <ip>:<port>
</source>

The default socket is listening on port 3333 in the loopback interface of your computer. So you can use the default command:
<source lang="bash">
(gdb) target extended-remote :3333
</source>

== Reset the board ==
After the connection (and after each change of configuration) you must reset the board in a safe state:
<source lang="bash">
(gdb) monitor reset halt
</source>

== Using gdb ==

This is not a full tutorial on using GDB, information can be found online. Here we only list the basics:

Setting breakpoints can be done with the ''break'' command followed by the function name or source code line:
<source lang="bash">
(gdb) break main
</source>

or

<source lang="bash">
(gdb) break main.cpp:30
</source>

Running the board can be done with the ''run'' command, which will run till the first breakpoint is hit.

Note that when in-circuit debugging there is only a limited number of hardware breakpoints you can set. If you exceed the number you can remove all breakpoints with:

<source lang="bash">
(gdb) del break
</source>

and start over.

== Flash a new firmware ==
If you want to upload to the board a new firmware version you can made it through gdb and OpenOCD, you must indicate the binary file and the address of the flash memory of your board:
<source lang="bash">
(gdb) monitor reset halt
(gdb) monitor flash write_image erase main.bin 0x08000000
</source>
Flashing while the board is running of course does not work, so you need to ''reset halt'' first. You'll also want to delete the old breakpoints, as they will not be in random locations.

[[Category:Installation and Configuration]]

Linux Debugger configuration

2026-05-10T21:42:54Z

Fede.tft:

The debugging of Miosix on Linux can be done through [http://openocd.org/ OpenOCD], that creates a bridge between GDB and the JTAG device.

= Setting up OpenOCD =

== Install OpenOCD ==
<source lang="bash">
sudo apt install openocd # Install OpenOCD for Ubuntu/Debian
</source>

== Run OpenOCD ==
The OpenOCD configuration is included in the official Miosix distribution for most of the supported boards under the path 'miosix/arch/board/<board name>/openocd.cfg'. For example for the stm32f429zi_stm32f4discovery board:
<source lang="bash">
openocd -f miosix/arch/board/stm32f429zi_stm32f4discovery/openocd.cfg
</source>

OpenOCD provides built-in configuration files for many boards, chips and debugging adapters. You can see the entire range of files in the directory <code>/usr/share/openocd/scripts</code>. If Miosix does not provide a configuration file for you, in most cases there will be appropriate scripts available together with OpenOCD.

'''If breakpoints don't work on your board''' you can try adding the option <code>-c 'gdb_breakpoint_override hard'</code> to the OpenOCD invocation. This option disables GDB software breakpoints and always forces the use of hardware breakpoints, which might be needed if OpenOCD provides an incomplete memory map to GDB.

= Debugging with GDB =
The GDB used is provided by the official [[Miosix_Toolchain|Miosix Toolchain]]. Although the board is flashed with the ''.bin'' file, you'll have to pass the corresponding ''.elf'' file, since this file format includes debugging symbols.
<source lang="bash">
arm-miosix-eabi-gdb main.elf
</source>

== Connect GDB ==
OpenOCD provide a network interface for connect the debugger, the follow command is necessary for establish the connection:
<source lang="bash">
(gdb) target remote <ip>:<port>
</source>

The default socket is listening on port 3333 in the loopback interface of your computer. So you can use the default command:
<source lang="bash">
(gdb) target extended-remote :3333
</source>

== Reset the board ==
After the connection (and after each change of configuration) you must reset the board in a safe state:
<source lang="bash">
(gdb) monitor reset halt
</source>

== Using gdb ==

This is not a full tutorial on using GDB, information can be found online. Here we only list the basics:

Setting breakpoints can be done with the ''break'' command followed by the function name or source code line:
<source lang="bash">
(gdb) break main
</source>

or

<source lang="bash">
(gdb) break main.cpp:30
</source>

Running the board can be done with the ''run'' command, which will run till the first breakpoint is hit.

Note that when in-circuit debugging there is only a limited number of hardware breakpoints you can set. If you exceed the number you can remove all breakpoints with:

<source lang="bash">
(gdb) del break
</source>

and start over.

== Flash a new firmware ==
If you want to upload to the board a new firmware version you can made it through gdb and OpenOCD, you must indicate the binary file and the address of the flash memory of your board:
<source lang="bash">
(gdb) monitor flash write_image erase main.bin 0x08000000
</source>
It's often necessary to perform a reset of the board before and after the firmware upload.

[[Category:Installation and Configuration]]

Debugging

2026-05-10T21:31:41Z

Fede.tft:

Miosix supports multiple debugging methods, useful in different use cases.

= Enabling assertions in the kernel =

A proactive tool to check for potential errors in using the kernel API is to enable optional assertions in the kernel in [https://github.com/fedetft/miosix-kernel/blob/master/miosix/config/miosix_settings.h config/miosix_settings.h]:

<source lang=CPP>
/// Enable additional assertions useful for debugging but adding more run-time
/// overhead. Three levels are implemented
/// None: Do not add extra checks, leading to fastest code. This is the default.
/// Application: Only add checks that are useful to debug kernel-level
/// application programming errors. Useful during application code debugging.
/// Kernel: Also add checks that are useful to debug kernel code. Useful
/// during kernel code debugging. Adds significant run-time overhead!
enum class ExtraChecks { None, Application, Kernel };
constexpr auto extraChecks=ExtraChecks::None;
</source>

The default is to disable optional assertions. This configuration, useful for a release build only performs minimal assertions in places where there is no impact on performance. You can change the assertion level by declaring the ''extraChecks'' variable to be ''Application'', which is useful to add extra checks looking for wrong use of kernel APIs from applications. The ''Kernel'' choice is mainly meant for kernel development and mostly adds invariant checks in some kernel data structures, often causing considerable performance impact, such as turning some O(1) algorithms into O(N).

= ''printf()'' debugging =

On almost all boards, Miosix configures a serial port during the boot stage, which the kernel immediately uses to print boot logs. Here's an example:

<source>
Starting Kernel... Ok
Miosix v3.01 (stm32h755zi_nucleo, May 9 2026 16:53:23, gcc 15.2.0-mp4.2)
Mounting MountpointFs as / ... Ok
Mounting DevFs as /dev ... Ok
Mounting Fat32Fs as /sd ... Ok
OS Timer freq = 200000000 Hz
Available heap 511744 out of 519760 Bytes
</source>

When the boot completes and the kernelspace ''main()'' starts, the serial port is available to applications for any use, including ''printf()'' debugging. Note that also ''stdin'' (''scanf()'' etc.) is configured and working. More information can be found in the [[Serial ports and printf/scanf]] page.

If processes are spawned, they inherit ''stdin'', ''stdout'' and ''stderr'' from the kernel, so unless redirections are made, also the spawned processes will by default share the same serial port I/O as the kernel, and they too can use it for ''printf()'' debugging.

On the minority of boards where a serial port is not available, it is sometimes possible to use the ARM DCC (Debug Comminication Channel) to redirect ''printf()'' through the SWD debugging interface and access it with gdb/openocd. DCC support is for ''stdout'' (''printf()'') only, there's no ''stdin'' (''scanf()'').

Further reading for DCC support:
* [https://github.com/fedetft/miosix-kernel/blob/master/miosix/arch/drivers/dcc.h miosix/arch/drivers/dcc.h]
* [https://github.com/fedetft/miosix-kernel/blob/master/miosix/arch/board/nrf52840_generic/openocd.cfg miosix/arch/board/nrf52840_generic/openocd.cfg]

= In-circuit debugging =

In-circuit debugging usually takes longer to set-up, but is invaluable when debugging kernelspace application crashes and bugs that corrupt memory.

An in-circuit debugger allows to physically halt the CPU inside a microcontroller, single-step it and view all the variables at any given time. It is a powerful tool to debug software running on a microcontroller.

The only limitation of in-circuit debuggers is that they cannot be used to debug code that has to interact in real-time, as stopping the CPU blocks every activity of the kernel, including unrelated kernel threads and interrupt handlers.

When you install the [[Miosix Toolchain]], it includes a precompiled gdb (''arm-miosix-eabi-gdb'' for ARM microcontrollers) with support for remote debugging.

An additional tool is needed to bridge gdb and the debugger hardware, usually [http://openocd.sourceforge.net openocd]. The following guides explain how to set up in-circuit debugging.

* [[Linux Debugger configuration]]
* [[Windows Debugger configuration]]

= Debugging unexpected kernel crashes =

This method allows to get a head start of unexpected bugs by tracing the source code line when it happens the first time, avoiding in some cases the need to attach a debugger and wait for the bug to trigger again.

Modern CPUs provide a fault reporting mechanism, usually through special interrupts that trigger when unexpected conditions occur, such as certain types of memory corruptions, undefined instructions, division by zero etc.

The Miosix kernel, upon encountering such fault conditions, attempts to print the program counter value at the moment of the fault, and then reboot (note that in some architectures such as ARM Cortex, bugs that corrupt the stack to a point where it becomes impossible for the CPU to save the processor state upon entering the fault interrupt leave the kernel with no program counter information, in that case the error message mentions the program counter is missing).

Applications running in kernelspace that cause such types of fault will thus cause a kernel reboot.

Here's an example of a Miosix fault handler:

<source>
***Unexpected UsageFault @ 0x08004874
Divide by zero
</source>

If you still have access to the exact elf file (main.elf) of the kernel that was flashed on the board, it's possible to trace the source code line that caused the fault from the fault address. Note that the result may not be fully precise as optimizations blur the mapping between the addresses of assembly instructions and source code lines. Rebuilding the kernel with optimizations disabled solves the issue, but you'd better off just attaching an in-circuit debugger in this case. Some architectures also employ a write buffer, so a write instruction to a nonexistent address will only be caught by the architecture a few instructions later. The kernel will try to warn you when the printed address is imprecise.

Once you have the address of the fault and the kernel elf file, tracing the source code line can be done by combining two tools which are part of the [[Miosix Toolchain]], ''arm-miosix-eabi-addr2line'' and ''arm-miosix-eabi-c++filt'' (replace 0x08004874 with the address of your fault):

<source lang="bash">
$ arm-miosix-eabi-addr2line 0x08004874 -e main.elf -f | arm-miosix-eabi-c++filt
main()
main.cpp:30
</source>

Reference:
* [https://github.com/fedetft/miosix-kernel/blob/master/doc/textdoc/Error%20debug.txt Error debug.txt]

= Debugging unexpected process crashes =

Whenever a userspace process crashes, the kernel will by default print an error message to the default serial port, similar to a kernel fault handler. However, the kernel will not reboot as memory protection allows the kernel to keep running even in case of memory corruptions in userspace processes.

A similar technique can be used combining ''arm-miosix-eabi-addr2line'' and ''arm-miosix-eabi-c++filt'' to trace the source code line from the fault address.

TODO: a tutorial is needed

= Using gdb with userspace processes =

Using an in-circuit debugger to debug userspace processes is known not to work, as the fluid kernel memory model is not understood by debuggers. Moreover, an in-circuit debugger halts the entire kernel which is often undesirable as it interferes with interrupt handlers and makes it impossible to debug code that has to interact in real-time.

'''Coming soon''': We are currently developing an in-kernel gdb server that will allow to debug individual processes while leaving the kernel running and able to keep processing real-time code.

Debugging

2026-05-10T21:28:06Z

Fede.tft:

Miosix supports multiple debugging methods, useful in different use cases.

= Enabling assertions in the kernel =

A proactive tool to check for potential errors in using the kernel API is to enable optional assertions in the kernel in [https://github.com/fedetft/miosix-kernel/blob/master/miosix/config/miosix_settings.h config/miosix_settings.h]:

<source lang=CPP>
/// Enable additional assertions useful for debugging but adding more run-time
/// overhead. Three levels are implemented
/// None: Do not add extra checks, leading to fastest code. This is the default.
/// Application: Only add checks that are useful to debug kernel-level
/// application programming errors. Useful during application code debugging.
/// Kernel: Also add checks that are useful to debug kernel code. Useful
/// during kernel code debugging. Adds significant run-time overhead!
enum class ExtraChecks { None, Application, Kernel };
constexpr auto extraChecks=ExtraChecks::None;
</source>

The default is to disable optional assertions. This configuration, useful for a release build only performs minimal assertions in places where there is no impact on performance. You can change the assertion level by declaring the ''extraChecks'' variable to be ''Application'', which is useful to add extra checks looking for wrong use of kernel APIs from applications. The ''Kernel'' choice is mainly meant for kernel development and mostly adds invariant checks in some kernel data structures, often causing considerable performance impact, such as turning some O(1) algorithms into O(N).

= ''printf()'' debugging =

On almost all boards, Miosix configures a serial port during the boot stage, which the kernel immediately uses to print boot logs. Here's an example:

<source>
Starting Kernel... Ok
Miosix v3.01 (stm32h755zi_nucleo, May 9 2026 16:53:23, gcc 15.2.0-mp4.2)
Mounting MountpointFs as / ... Ok
Mounting DevFs as /dev ... Ok
Mounting Fat32Fs as /sd ... Ok
OS Timer freq = 200000000 Hz
Available heap 511744 out of 519760 Bytes
</source>

When the boot completes and the kernelspace ''main()'' starts, the serial port is available to applications for any use, including ''printf()'' debugging. Note that also ''stdin'' (''scanf()'' etc.) is configured and working. More information can be found in the [[Serial ports and printf/scanf]] page.

If processes are spawned, they inherit ''stdin'', ''stdout'' and ''stderr'' from the kernel, so unless redirections are made, also the spawned processes will by default share the same serial port I/O as the kernel, and they too can use it for ''printf()'' debugging.

On the minority of boards where a serial port is not available, it is sometimes possible to use the ARM DCC (Debug Comminication Channel) to redirect ''printf()'' through the SWD debugging interface and access it with gdb/openocd. DCC support is for ''stdout'' (''printf()'') only, there's no ''stdin'' (''scanf()'').

Further reading for DCC support:
* [https://github.com/fedetft/miosix-kernel/blob/master/miosix/arch/drivers/dcc.h miosix/arch/drivers/dcc.h]
* [https://github.com/fedetft/miosix-kernel/blob/master/miosix/arch/board/nrf52840_generic/openocd.cfg miosix/arch/board/nrf52840_generic/openocd.cfg]

= In-circuit debugging =

In-circuit debugging usually takes longer to set-up, but is invaluable when debugging kernelspace application crashes and bugs that corrupt memory.

An in-circuit debugger allows to physically halt the CPU inside a microcontroller, single-step it and view all the variables at any given time. It is a powerful tool to debug software running on a microcontroller.

The only limitation of in-circuit debuggers is that they cannot be used to debug code that has to interact in real-time, as stopping the CPU blocks every activity of the kernel, including unrelated kernel threads and interrupt handlers.

When you install the [[Miosix Toolchain]], it includes a precompiled gdb (''arm-miosix-eabi-gdb'' for ARM microcontrollers) with support for remote debugging.

An additional tool is needed to bridge gdb and the debugger hardware, usually [http://openocd.sourceforge.net openocd]. The following guides explain how to set up in-circuit debugging.

* [[Linux Debugger configuration]]
* [[Windows Debugger configuration]]

= Debugging unexpected kernel crashes =

This method allows to get a head start of unexpected bugs by tracing the source code line when it happens the first time, avoiding in some cases the need to attach a debugger and wait for the bug to trigger again.

Modern CPUs provide a fault reporting mechanism, usually through special interrupts that trigger when unexpected conditions occur, such as certain types of memory corruptions, undefined instructions, division by zero etc.

The Miosix kernel, upon encountering such fault conditions, attempts to print the program counter value at the moment of the fault, and then reboot (note that in some architectures such as ARM Cortex, bugs that corrupt the stack to a point where it becomes impossible for the CPU to save the processor state upon entering the fault interrupt leave the kernel with no program counter information, in that case the error message mentions the program counter is missing).

Applications running in kernelspace that cause such types of fault will thus cause a kernel reboot.

Here's an example of a Miosix fault handler:

<source>
***Unexpected UsageFault @ 0x08004874
Divide by zero
</source>

If you still have access to the exact elf file (main.elf) of the kernel that was flashed on the board, it's possible to trace the source code line that caused the fault from the fault address. Note that the result may not be fully precise as optimizations blur the mapping between the addresses of assembly instructions and source code lines. Rebuilding the kernel with optimizations disabled solves the issue, but you'd better off just attaching an in-circuit debugger in this case. Some architectures also employ a write buffer, so a write instruction to a nonexistent address will only be caught by the architecture a few instructions later. The kernel will try to warn you when the printed address is imprecise.

Once you have the address of the fault and the kernel elf file, tracing the source code line can be done by combining two tools which are part of the [[Miosix Toolchain]], ''arm-miosix-eabi-addr2line'' and ''arm-miosix-eabi-c++filt'' (replace 0x08004874 with the address of your fault):

<source lang="bash">
$ arm-miosix-eabi-addr2line 0x08004874 -e main.elf -f | arm-miosix-eabi-c++filt
main()
main.cpp:30
</source>

Reference:
* [[https://github.com/fedetft/miosix-kernel/blob/master/doc/textdoc/Error%20debug.txt | Error debug]]

= Debugging unexpected process crashes =

Whenever a userspace process crashes, the kernel will by default print an error message to the default serial port, similar to a kernel fault handler. However, the kernel will not reboot as memory protection allows the kernel to keep running even in case of memory corruptions in userspace processes.

A similar technique can be used combining ''arm-miosix-eabi-addr2line'' and ''arm-miosix-eabi-c++filt'' to trace the source code line from the fault address.

TODO: a tutorial is needed

= Using gdb with userspace processes =

Using an in-circuit debugger to debug userspace processes is known not to work, as the fluid kernel memory model is not understood by debuggers. Moreover, an in-circuit debugger halts the entire kernel which is often undesirable as it interferes with interrupt handlers and makes it impossible to debug code that has to interact in real-time.

'''Coming soon''': We are currently developing an in-kernel gdb server that will allow to debug individual processes while leaving the kernel running and able to keep processing real-time code.

Debugging

2026-05-10T21:26:50Z

Fede.tft:

Miosix supports multiple debugging methods, useful in different use cases.

= Enabling assertions in the kernel =

A proactive tool to check for potential errors in using the kernel API is to enable optional assertions in the kernel in [https://github.com/fedetft/miosix-kernel/blob/master/miosix/config/miosix_settings.h config/miosix_settings.h]:

<source lang=CPP>
/// Enable additional assertions useful for debugging but adding more run-time
/// overhead. Three levels are implemented
/// None: Do not add extra checks, leading to fastest code. This is the default.
/// Application: Only add checks that are useful to debug kernel-level
/// application programming errors. Useful during application code debugging.
/// Kernel: Also add checks that are useful to debug kernel code. Useful
/// during kernel code debugging. Adds significant run-time overhead!
enum class ExtraChecks { None, Application, Kernel };
constexpr auto extraChecks=ExtraChecks::None;
</source>

The default is to disable optional assertions. This configuration, useful for a release build only performs minimal assertions in places where there is no impact on performance. You can change the assertion level by declaring the ''extraChecks'' variable to be ''Application'', which is useful to add extra checks looking for wrong use of kernel APIs from applications. The ''Kernel'' choice is mainly meant for kernel development and mostly adds invariant checks in some kernel data structures, often causing considerable performance impact, such as turning some O(1) algorithms into O(N).

= ''printf()'' debugging =

On almost all boards, Miosix configures a serial port during the boot stage, which the kernel immediately uses to print boot logs. Here's an example:

<source>
Starting Kernel... Ok
Miosix v3.01 (stm32h755zi_nucleo, May 9 2026 16:53:23, gcc 15.2.0-mp4.2)
Mounting MountpointFs as / ... Ok
Mounting DevFs as /dev ... Ok
Mounting Fat32Fs as /sd ... Ok
OS Timer freq = 200000000 Hz
Available heap 511744 out of 519760 Bytes
</source>

When the boot completes and the kernelspace ''main()'' starts, the serial port is available to applications for any use, including ''printf()'' debugging. Note that also ''stdin'' (''scanf()'' etc.) is configured and working. More information can be found in the [[Serial ports and printf/scanf]] page.

If processes are spawned, they inherit ''stdin'', ''stdout'' and ''stderr'' from the kernel, so unless redirections are made, also the spawned processes will by default share the same serial port I/O as the kernel, and they too can use it for ''printf()'' debugging.

On the minority of boards where a serial port is not available, it is sometimes possible to use the ARM DCC (Debug Comminication Channel) to redirect ''printf()'' through the SWD debugging interface and access it with gdb/openocd. DCC support is for ''stdout'' (''printf()'') only, there's no ''stdin'' (''scanf()'').

Further reading for DCC support:
* [https://github.com/fedetft/miosix-kernel/blob/master/miosix/arch/drivers/dcc.h miosix/arch/drivers/dcc.h]
* [https://github.com/fedetft/miosix-kernel/blob/master/miosix/arch/board/nrf52840_generic/openocd.cfg miosix/arch/board/nrf52840_generic/openocd.cfg]

= In-circuit debugging =

In-circuit debugging usually takes longer to set-up, but is invaluable when debugging kernelspace application crashes and bugs that corrupt memory.

An in-circuit debugger allows to physically halt the CPU inside a microcontroller, single-step it and view all the variables at any given time. It is a powerful tool to debug software running on a microcontroller.

The only limitation of in-circuit debuggers is that they cannot be used to debug code that has to interact in real-time, as stopping the CPU blocks every activity o the kernel, including unrelated kernel threads and interrupt handlers.

When you install the [[Miosix Toolchain]], it includes a precompiled gdb (''arm-miosix-eabi-gdb'' for ARM microcontrollers) with support for remote debugging.

An additional tool is needed to bridge gdb and the debugger hardware, usually [http://openocd.sourceforge.net openocd]. The following guides explain how to set up in-circuit debugging.

* [[Linux Debugger configuration]]
* [[Windows Debugger configuration]]

= Debugging unexpected kernel crashes =

This method allows to get a head start of unexpected bugs by tracing the source code line when it happens the first time, avoiding in some cases the need to attach a debugger and wait for the bug to trigger again.

Modern CPUs provide a fault reporting mechanism, usually through special interrupts that trigger when unexpected conditions occur, such as certain types of memory corruptions, undefined instructions, division by zero etc.

The Miosix kernel, upon encountering such fault conditions, attempts to print the program counter value at the moment of the fault, and then reboot (note that in some architectures such as ARM Cortex, bugs that corrupt the stack to a point where it becomes impossible for the CPU to save the processor state upon entering the fault interrupt leave the kernel with no program counter information, in that case the error message mentions the program counter is missing).

Applications running in kernelspace that cause such types of fault will thus cause a kernel reboot.

Here's an example of a Miosix fault handler:

<source>
***Unexpected UsageFault @ 0x08004874
Divide by zero
</source>

If you still have access to the exact elf file (main.elf) of the kernel that was flashed on the board, it's possible to trace the source code line that caused the fault from the fault address. Note that the result may not be fully precise as optimizations blur the mapping between the addresses of assembly instructions and source code lines. Rebuilding the kernel with optimizations disabled solves the issue, but you'd better off just attaching an in-circuit debugger in this case. Some architectures also employ a write buffer, so a write instruction to a nonexistent address will only be caught by the architecture a few instructions later. The kernel will try to warn you when the printed address is imprecise.

Once you have the address of the fault and the kernel elf file, tracing the source code line can be done by combining two tools which are part of the [[Miosix Toolchain]], ''arm-miosix-eabi-addr2line'' and ''arm-miosix-eabi-c++filt'' (replace 0x08004874 with the address of your fault):

<source lang="bash">
$ arm-miosix-eabi-addr2line 0x08004874 -e main.elf -f | arm-miosix-eabi-c++filt
main()
main.cpp:30
</source>

Reference:
* [[https://github.com/fedetft/miosix-kernel/blob/master/doc/textdoc/Error%20debug.txt | Error debug]]

= Debugging unexpected process crashes =

Whenever a userspace process crashes, the kernel will by default print an error message to the default serial port, similar to a kernel fault handler. However, the kernel will not reboot as memory protection allows the kernel to keep running even in case of memory corruptions in userspace processes.

A similar technique can be used combining ''arm-miosix-eabi-addr2line'' and ''arm-miosix-eabi-c++filt'' to trace the source code line from the fault address.

TODO: a tutorial is needed

= Using gdb with userspace processes =

Using an in-circuit debugger to debug userspace processes is known not to work, as the fluid kernel memory model is not understood by debuggers. Moreover, an in-circuit debugger halts the entire kernel which is often undesirable as it interferes with interrupt handlers and makes it impossible to debug code that has to interact in real-time.

'''Coming soon''': We are currently developing an in-kernel gdb server that will allow to debug individual processes while leaving the kernel running and able to keep processing real-time code.

Debugging

2026-05-10T21:25:25Z

Fede.tft:

Miosix supports multiple debugging methods, useful in different use cases.

= Enabling assertions in the kernel =

A proactive tool to check for potential errors in using the kernel API is to enable optional assertions in the kernel.

<source lang=CPP>
/// Enable additional assertions useful for debugging but adding more run-time
/// overhead. Three levels are implemented
/// None: Do not add extra checks, leading to fastest code. This is the default.
/// Application: Only add checks that are useful to debug kernel-level
/// application programming errors. Useful during application code debugging.
/// Kernel: Also add checks that are useful to debug kernel code. Useful
/// during kernel code debugging. Adds significant run-time overhead!
enum class ExtraChecks { None, Application, Kernel };
constexpr auto extraChecks=ExtraChecks::None;
</source>

The default is to disable optional assertions. This configuration, useful for a release build only performs minimal assertions in places where there is no impact on performance. You can change the assertion level by declaring the ''extraChecks'' variable to be ''Application'', which is useful to add extra checks looking for wrong use of kernel APIs from applications. The ''Kernel'' choice is mainly meant for kernel development and mostly adds invariant checks in some kernel data structures, often causing considerable performance impact, such as turning some O(1) algorithms into O(N).

= ''printf()'' debugging =

On almost all boards, Miosix configures a serial port during the boot stage, which the kernel immediately uses to print boot logs. Here's an example:

<source>
Starting Kernel... Ok
Miosix v3.01 (stm32h755zi_nucleo, May 9 2026 16:53:23, gcc 15.2.0-mp4.2)
Mounting MountpointFs as / ... Ok
Mounting DevFs as /dev ... Ok
Mounting Fat32Fs as /sd ... Ok
OS Timer freq = 200000000 Hz
Available heap 511744 out of 519760 Bytes
</source>

When the boot completes and the kernelspace ''main()'' starts, the serial port is available to applications for any use, including ''printf()'' debugging. Note that also ''stdin'' (''scanf()'' etc.) is configured and working. More information can be found in the [[Serial ports and printf/scanf]] page.

If processes are spawned, they inherit ''stdin'', ''stdout'' and ''stderr'' from the kernel, so unless redirections are made, also the spawned processes will by default share the same serial port I/O as the kernel, and they too can use it for ''printf()'' debugging.

On the minority of boards where a serial port is not available, it is sometimes possible to use the ARM DCC (Debug Comminication Channel) to redirect ''printf()'' through the SWD debugging interface and access it with gdb/openocd. DCC support is for ''stdout'' (''printf()'') only, there's no ''stdin'' (''scanf()'').

Further reading for DCC support:
* [https://github.com/fedetft/miosix-kernel/blob/master/miosix/arch/drivers/dcc.h miosix/arch/drivers/dcc.h]
* [https://github.com/fedetft/miosix-kernel/blob/master/miosix/arch/board/nrf52840_generic/openocd.cfg miosix/arch/board/nrf52840_generic/openocd.cfg]

= In-circuit debugging =

In-circuit debugging usually takes longer to set-up, but is invaluable when debugging kernelspace application crashes and bugs that corrupt memory.

An in-circuit debugger allows to physically halt the CPU inside a microcontroller, single-step it and view all the variables at any given time. It is a powerful tool to debug software running on a microcontroller.

The only limitation of in-circuit debuggers is that they cannot be used to debug code that has to interact in real-time, as stopping the CPU blocks every activity o the kernel, including unrelated kernel threads and interrupt handlers.

When you install the [[Miosix Toolchain]], it includes a precompiled gdb (''arm-miosix-eabi-gdb'' for ARM microcontrollers) with support for remote debugging.

An additional tool is needed to bridge gdb and the debugger hardware, usually [http://openocd.sourceforge.net openocd]. The following guides explain how to set up in-circuit debugging.

* [[Linux Debugger configuration]]
* [[Windows Debugger configuration]]

= Debugging unexpected kernel crashes =

This method allows to get a head start of unexpected bugs by tracing the source code line when it happens the first time, avoiding in some cases the need to attach a debugger and wait for the bug to trigger again.

Modern CPUs provide a fault reporting mechanism, usually through special interrupts that trigger when unexpected conditions occur, such as certain types of memory corruptions, undefined instructions, division by zero etc.

The Miosix kernel, upon encountering such fault conditions, attempts to print the program counter value at the moment of the fault, and then reboot (note that in some architectures such as ARM Cortex, bugs that corrupt the stack to a point where it becomes impossible for the CPU to save the processor state upon entering the fault interrupt leave the kernel with no program counter information, in that case the error message mentions the program counter is missing).

Applications running in kernelspace that cause such types of fault will thus cause a kernel reboot.

Here's an example of a Miosix fault handler:

<source>
***Unexpected UsageFault @ 0x08004874
Divide by zero
</source>

If you still have access to the exact elf file (main.elf) of the kernel that was flashed on the board, it's possible to trace the source code line that caused the fault from the fault address. Note that the result may not be fully precise as optimizations blur the mapping between the addresses of assembly instructions and source code lines. Rebuilding the kernel with optimizations disabled solves the issue, but you'd better off just attaching an in-circuit debugger in this case. Some architectures also employ a write buffer, so a write instruction to a nonexistent address will only be caught by the architecture a few instructions later. The kernel will try to warn you when the printed address is imprecise.

Once you have the address of the fault and the kernel elf file, tracing the source code line can be done by combining two tools which are part of the [[Miosix Toolchain]], ''arm-miosix-eabi-addr2line'' and ''arm-miosix-eabi-c++filt'' (replace 0x08004874 with the address of your fault):

<source lang="bash">
$ arm-miosix-eabi-addr2line 0x08004874 -e main.elf -f | arm-miosix-eabi-c++filt
main()
main.cpp:30
</source>

Reference:
* [[https://github.com/fedetft/miosix-kernel/blob/master/doc/textdoc/Error%20debug.txt | Error debug]]

= Debugging unexpected process crashes =

Whenever a userspace process crashes, the kernel will by default print an error message to the default serial port, similar to a kernel fault handler. However, the kernel will not reboot as memory protection allows the kernel to keep running even in case of memory corruptions in userspace processes.

A similar technique can be used combining ''arm-miosix-eabi-addr2line'' and ''arm-miosix-eabi-c++filt'' to trace the source code line from the fault address.

TODO: a tutorial is needed

= Using gdb with userspace processes =

Using an in-circuit debugger to debug userspace processes is known not to work, as the fluid kernel memory model is not understood by debuggers. Moreover, an in-circuit debugger halts the entire kernel which is often undesirable as it interferes with interrupt handlers and makes it impossible to debug code that has to interact in real-time.

'''Coming soon''': We are currently developing an in-kernel gdb server that will allow to debug individual processes while leaving the kernel running and able to keep processing real-time code.

Debugging

2026-05-10T21:22:49Z

Fede.tft:

Miosix supports multiple debugging methods, useful in different use cases.

= Enabling assertions in the kernel =

A proactive tool to check for potential errors in using the kernel API is to enable optional assertions in the kernel.

<source lang=CPP>
/// Enable additional assertions useful for debugging but adding more run-time
/// overhead. Three levels are implemented
/// None: Do not add extra checks, leading to fastest code. This is the default.
/// Application: Only add checks that are useful to debug kernel-level
/// application programming errors. Useful during application code debugging.
/// Kernel: Also add checks that are useful to debug kernel code. Useful
/// during kernel code debugging. Adds significant run-time overhead!
enum class ExtraChecks { None, Application, Kernel };
constexpr auto extraChecks=ExtraChecks::None;
</source>

The default is to disable optional assertions. This configuration, useful for a release build only performs minimal assertions in places where there is no impact on performance. You can change the assertion level by declaring the ''extraChecks'' variable to be ''Application'', which is useful to add extra checks looking for wrong use of kernel APIs from applications. The ''Kernel'' choice is mainly meant for kernel development and mostly adds invariant checks in some kernel data structures, often causing considerable performance impact, such as turning some O(1) algorithms into O(N).

= ''printf()'' debugging =

On almost all boards, Miosix configures a serial port during the boot stage, which the kernel immediately uses to print boot logs. Here's an example:

<source>
Starting Kernel... Ok
Miosix v3.01 (stm32h755zi_nucleo, May 9 2026 16:53:23, gcc 15.2.0-mp4.2)
Mounting MountpointFs as / ... Ok
Mounting DevFs as /dev ... Ok
Mounting Fat32Fs as /sd ... Ok
OS Timer freq = 200000000 Hz
Available heap 511744 out of 519760 Bytes
</source>

When the boot completes and the kernelspace ''main()'' starts, the serial port is available to applications for any use, including ''printf()'' debugging. Note that also ''stdin'' (''scanf()'' etc.) is configured and working. More information can be found in the [[Serial ports and printf/scanf]] page.

If processes are spawned, they inherit ''stdin'', ''stdout'' and ''stderr'' from the kernel, so unless redirections are made, also the spawned processes will by default share the same serial port I/O as the kernel, and they too can use it for ''printf()'' debugging.

On the minority of boards where a serial port is not available, it is sometimes possible to use the ARM DCC (Debug Comminication Channel) to redirect ''printf()'' through the SWD debugging interface and access it with gdb/openocd. DCC support is for ''stdout'' (''printf()'') only, there's no ''stdin'' (''scanf()'').

Further reading for DCC support:
* [[https://github.com/fedetft/miosix-kernel/blob/master/miosix/arch/drivers/dcc.h miosix/arch/drivers/dcc.h]]
* [[https://github.com/fedetft/miosix-kernel/blob/master/miosix/arch/board/nrf52840_generic/openocd.cfg miosix/arch/board/nrf52840_generic/openocd.cfg]]

= In-circuit debugging =

In-circuit debugging usually takes longer to set-up, but is invaluable when debugging kernelspace application crashes and bugs that corrupt memory.

An in-circuit debugger allows to physically halt the CPU inside a microcontroller, single-step it and view all the variables at any given time. It is a powerful tool to debug software running on a microcontroller.

The only limitation of in-circuit debuggers is that they cannot be used to debug code that has to interact in real-time, as stopping the CPU blocks every activity o the kernel, including unrelated kernel threads and interrupt handlers.

When you install the [[Miosix Toolchain]], it includes a precompiled gdb (''arm-miosix-eabi-gdb'' for ARM microcontrollers) with support for remote debugging.

An additional tool is needed to bridge gdb and the debugger hardware, usually [http://openocd.sourceforge.net openocd]. The following guides explain how to set up in-circuit debugging.

* [[Linux Debugger configuration]]
* [[Windows Debugger configuration]]

= Debugging unexpected kernel crashes =

This method allows to get a head start of unexpected bugs by tracing the source code line when it happens the first time, avoiding in some cases the need to attach a debugger and wait for the bug to trigger again.

Modern CPUs provide a fault reporting mechanism, usually through special interrupts that trigger when unexpected conditions occur, such as certain types of memory corruptions, undefined instructions, division by zero etc.

The Miosix kernel, upon encountering such fault conditions, attempts to print the program counter value at the moment of the fault, and then reboot (note that in some architectures such as ARM Cortex, bugs that corrupt the stack to a point where it becomes impossible for the CPU to save the processor state upon entering the fault interrupt leave the kernel with no program counter information, in that case the error message mentions the program counter is missing).

Applications running in kernelspace that cause such types of fault will thus cause a kernel reboot.

Here's an example of a Miosix fault handler:

<source>
***Unexpected UsageFault @ 0x08004874
Divide by zero
</source>

If you still have access to the exact elf file (main.elf) of the kernel that was flashed on the board, it's possible to trace the source code line that caused the fault from the fault address. Note that the result may not be fully precise as optimizations blur the mapping between the addresses of assembly instructions and source code lines. Rebuilding the kernel with optimizations disabled solves the issue, but you'd better off just attaching an in-circuit debugger in this case. Some architectures also employ a write buffer, so a write instruction to a nonexistent address will only be caught by the architecture a few instructions later. The kernel will try to warn you when the printed address is imprecise.

Once you have the address of the fault and the kernel elf file, tracing the source code line can be done by combining two tools which are part of the [[Miosix Toolchain]], ''arm-miosix-eabi-addr2line'' and ''arm-miosix-eabi-c++filt'' (replace 0x08004874 with the address of your fault):

<source lang="bash">
$ arm-miosix-eabi-addr2line 0x08004874 -e main.elf -f | arm-miosix-eabi-c++filt
main()
main.cpp:30
</source>

Reference:
* [[https://github.com/fedetft/miosix-kernel/blob/master/doc/textdoc/Error%20debug.txt | Error debug]]

= Debugging unexpected process crashes =

Whenever a userspace process crashes, the kernel will by default print an error message to the default serial port, similar to a kernel fault handler. However, the kernel will not reboot as memory protection allows the kernel to keep running even in case of memory corruptions in userspace processes.

A similar technique can be used combining ''arm-miosix-eabi-addr2line'' and ''arm-miosix-eabi-c++filt'' to trace the source code line from the fault address.

TODO: a tutorial is needed

= Using gdb with userspace processes =

Using an in-circuit debugger to debug userspace processes is known not to work, as the fluid kernel memory model is not understood by debuggers. Moreover, an in-circuit debugger halts the entire kernel which is often undesirable as it interferes with interrupt handlers and makes it impossible to debug code that has to interact in real-time.

'''Coming soon''': We are currently developing an in-kernel gdb server that will allow to debug individual processes while leaving the kernel running and able to keep processing real-time code.

Miosix code size optimization

2026-05-10T21:10:47Z

Fede.tft:

Miosix is designed with the idea to be an "unix on a chip", so it was built with the idea of packing as much standard compliance as possible, without cutting corners. Things like full support to the C and C++ standard libraries, including full support for the C++ STL, thread-safe exception handling, and seldom used features of the C standard libraries, including stdout redirection via
<source lang="CPP">
fclose(stdout);
stdout=fopen("/sd/log.txt","w");
puts("writing to a file\n");
fflush(stdout);
</source>
are supported. This obviously comes with a code size penalty, especially considering that some features are enabled by default.
However, the kernel is very modular, so you don't have to pay the code size cost of unused features in your application.

This guide lists a number of tips to adapt the Miosix kernel to the needs of code-size constrained embedded applications. The exact figures presented here may change as the kernel is developed further, but the tips are expected to remain valid. In this page we'll use as example the [[stm32f411ce_blackpill]] board but the tips presented here are generally applicable. For the application, we'll use an empty ''main()'' to focus on the size of the components of the kernel that are included by default as part of the boot phase:

<source lang="CPP">
#include <cstdio>
#include <thread>
#include <miosix.h>
#include <interfaces/bsp.h>

using namespace std;
using namespace miosix;

int main()
{
return 0;
}
</source>

With the default settings and, at the time of writing, Miosix version 3.01, the kernel size is a little over 40KB: 41304 bytes. With this guide it is possible to reduce code size down to 13KB with configuration options alone, and down to 8KB by slimming also the board support package.

Note that optimizations can be applied in any order, there are no dependencies between the steps presented in this page, so you can mix and match to configure a kernel that suits the needs of your application.

== Compile with Os ==

The default [http://fedetft.wordpress.com/2009/10/01/gcc-optimization-flags GCC optimization flag] used in Miosix is ''-O2'', which generates code optimized for speed. You can however choose ''-Os'' which optimizes for size by opening the file [https://github.com/fedetft/miosix-kernel/blob/master/miosix/config/Makefile.inc config/Makefile.inc], commenting out the ''-O2'' line, and uncommenting the ''-Os'' line, like this:
<source lang="bash">
#OPT_OPTIMIZATION ?= -O0
#OPT_OPTIMIZATION ?= -O2
#OPT_OPTIMIZATION ?= -O3
OPT_OPTIMIZATION ?= -Os
</source>

Remember to do a ''make clean; make'' to rebuild the entire kernel for the changes to take effect.

The code size will usually decrease as a percentage of the total code size, as this option affects how the compiler generates code. 5 to 10% decrease is a common figure. Although I haven't found benchmarks showing how much this affects execution speed, usually the impact isn't that high, and code runs definitely much faster with respect to disabling optimizations altogether (with ''-O0''), so if you are tight on code size this is an easy option that does not require to sacrifice any feature of the kernel.

With the empty ''main()'', Miosix v3.01 and the stm32f411ce_blackpill, the code size was reduced to 39368 bytes.

== Disable DevFs ==

'''Note:''' starting from Miosix 3, DevFs is disabled by default, so there's nothing to do here. This section is kept for reference.

Miosix 2 comes with an in-memory filesystem, mounted at ''/dev'' where device files can be added, similarly to how a Linux machine works. The main purpose of this is to allow [[Miosix processes|processes]] to access peripherals, since due to memory protection they can't just access the peripheral registers. However, processes are currently disabled by default because they're still an experimental feature, so you can disable DevFs too. This can be done by commenting out the ''WITH_DEVFS'' line in [https://github.com/fedetft/miosix-kernel/blob/master/miosix/config/miosix_settings.h config/miosix_settings.h], like this:

<source lang="CPP">
//#define WITH_DEVFS
</source>

== Disable the filesystem entirely ==

'''Note:''' starting from Miosix 3, the filesystem is disabled by default since only some board provide the required hardware, so there's nothing to do here. This section is kept for reference.

Miosix 2 has a completely rewritten filesystem subsystem, supporting multiple mountpoints, extensible filesystem types (currently Fat32 and DevFs), unicode UTF8 in file names, directory listing via the standard ''opendir()''/''readdir()''/''closedir()'' and more POSIX compliance, including inode emulation for Fat32. This comes at a code size cost, though. If your application does not need to read/write from files, you can disable the filesystem subsystem entirely. To do so, open [https://github.com/fedetft/miosix-kernel/blob/master/miosix/config/miosix_settings.h config/miosix_settings.h] and comment out both the ''WITH_DEVFS'' and ''WITH_FILESYSTEM'' lines.

== Use iprintf() instead of printf() in your application ==

'''Note:''' since this example focuses on an empty main, there's nothing to do here, but this tip is worth knowing when writing application code.

''iprintf()'' is a non-standard extension of the [https://www.sourceware.org/newlib newlib] C library used by Miosix. It can do all what ''printf()'' can do except printing floating point numbers, and that's why its code size is significantly lower, printing floating point numbers is quite complicated. Miosix already uses ''iprintf()'' internally, so to see the code size difference you have to write the following simple code in ''main()''

<source lang="CPP">
int main()
{
int i=0;
printf("%d\n",i);
//iprintf("%d\n",i);
}
</source>

Trying with ''iprintf()'' instead of ''printf()'', a 18KB code size reduction is observed. Note that you have to use a format string containing a % argument, such as %d to see the code size difference. If there is no % in the format string, GCC may replace ''printf()''/''iprintf()'' with a call to ''puts()'' as an optimization, and no code size difference can be seen.

== Disable the C++ exception runtime ==

The Miosix kernel is by default compiled with support for C++ exceptions, and unless you're also enabling [[Miosix processes|processes]] that depend on C++ exceptions, it is possible to disable their support. To do so, open [https://github.com/fedetft/miosix-kernel/blob/master/miosix/config/Makefile.inc config/Makefile.inc] and uncomment the following line:

<source lang="bash">
OPT_EXCEPT := -fno-exceptions -fno-rtti -D__NO_EXCEPTIONS
</source>

Remember to do a ''make clean; make'' to rebuild the entire kernel for the changes to take effect.

The code size is reduced to 24384 bytes, but comes with quite an important side effect: if the heap is full, the kernel will reboot the machine. To explain why it is so, consider that the normal behavior in Miosix to handle a full heap is that the C ''malloc()'' returns ''NULL'', while the C++ ''operator new'' throws an exception of type ''bad_alloc''. Now, when exceptions are disabled, ''new'' can no longer throw, but C++ code inside the C++ standard library doesn't check for ''NULL'', as it expects an exception, and that would result in undefined behavior. The only way to prevent undefined behavior, is to reboot the machine, and that is what Miosix does if you disable exceptions.

== Disable boot logs ==

Maybe you're not using ''printf()'' at all in your application, however in this case you're still paying for the code size of ''iprintf()'' as the kernel uses it to print boot logs and error logs. To disable them, you can open [https://github.com/fedetft/miosix-kernel/blob/master/miosix/config/miosix_settings.h config/miosix_settings.h] and comment out the lines ''#define WITH_BOOTLOG'' and ''#define WITH_ERRLOG'':

<source lang="CPP">
/// \def WITH_BOOTLOG
/// Uncomment to print bootlogs on stdout.
/// By default it is defined (bootlogs are printed)
//#define WITH_BOOTLOG

/// \def WITH_ERRLOG
/// Uncomment for debug information on stdout.
/// By default it is defined (error information is printed)
//#define WITH_ERRLOG
</source>

This allows to save the code size of iprintf, but this is only true if there's no ''printf()'' call in your code, otherewise the code size saving will be minimal.

Also, keep in mind that error logs are a powerful tool to [[Debugging|debug]] crashes of your application or the kernel during code development, so you may want to disable them only in release builds, and keep them enabled during development.

Finally, note that you can still access the serial port without using ''printf()'', by means of the POSIX calls ''write()'' and ''read()'', using ''STDOUT_FILENO'' and ''STDIN_FILENO'' as the ''fd'' argument.

With this optimization, the code size is reduced to 13084 bytes.

== One more thing, disable the serial port ==

The kernel, during the boot process, configures a serial port on nearly all the supported boards. If you really have no use for the serial port, you can disable it entirely, saving additional code size. To do so there is no configuration option, but you can edit the board support package file of your board. For the ''stm32f411ce_blackpill'' it's [https://github.com/fedetft/miosix-kernel/blob/master/miosix/arch/board/stm32f411ce_blackpill/interfaces-impl/bsp.cpp miosix-kernel/miosix/arch/board/stm32f411ce_blackpill/interfaces-impl/bsp.cpp]. Open the file and comment out the following lines in ''IRQbspInit()''

<source lang="CPP">
// IRQsetDefaultConsole(
// STM32SerialBase::get<defaultSerialTxPin,defaultSerialRxPin,
// defaultSerialRtsPin,defaultSerialCtsPin>(
// defaultSerial,defaultSerialSpeed,
// defaultSerialFlowctrl,defaultSerialDma));
</source>

as well as the following line in ''shutdown()'' and ''reboot()''

<source lang="CPP">
//ioctl(STDOUT_FILENO,IOCTL_SYNC,0);
</source>

By applying also this last tip code size can be reduced to 8436 bytes.

[[Category:Installation and Configuration]]
[[Category:Optimization]]

Miosix code size optimization

2026-05-10T21:07:54Z

Fede.tft:

Miosix is designed with the idea to be an "unix on a chip", so it was built with the idea of packing as much standard compliance as possible, without cutting corners. Things like full support to the C and C++ standard libraries, including full support for the C++ STL, thread-safe exception handling, and seldom used features of the C standard libraries, including stdout redirection via
<source lang="CPP">
fclose(stdout);
stdout=fopen("/sd/log.txt","w");
puts("writing to a file\n");
fflush(stdout);
</source>
are supported. This obviously comes with a code size penalty, especially considering that some features are enabled by default.
However, the kernel is very modular, so you don't have to pay the code size cost of unused features in your application.

This guide lists a number of tips to adapt the Miosix kernel to the needs of code-size constrained embedded applications. The exact figures presented here may change as the kernel is developed further, but the tips are expected to remain valid. In this page we'll use as example the [[stm32f411ce_blackpill]] board but the tips presented here are generally applicable. For the application, we'll use an empty ''main()'' to focus on the size of the components of the kernel that are included by default as part of the boot phase:

<source lang="CPP">
#include <cstdio>
#include <thread>
#include <miosix.h>
#include <interfaces/bsp.h>

using namespace std;
using namespace miosix;

int main()
{
return 0;
}
</source>

With the default settings and, at the time of writing, Miosix version 3.01, the kernel size is a little over 40KB: 41304 bytes. With this guide it is possible to reduce code size down to 13KB with configuration options alone, and down to 8KB by slimming also the board support package.

Note that optimizations can be applied in any order, there are no dependencies between the steps presented in this page, so you can mix and match to configure a kernel that suits the needs of your application.

== Compile with Os ==

The default [http://fedetft.wordpress.com/2009/10/01/gcc-optimization-flags GCC optimization flag] used in Miosix is ''-O2'', which generates code optimized for speed. You can however choose ''-Os'' which optimizes for size by opening the file [https://github.com/fedetft/miosix-kernel/blob/master/miosix/config/Makefile.inc config/Makefile.inc], commenting out the ''-O2'' line, and uncommenting the ''-Os'' line, like this:
<source lang="bash">
#OPT_OPTIMIZATION ?= -O0
#OPT_OPTIMIZATION ?= -O2
#OPT_OPTIMIZATION ?= -O3
OPT_OPTIMIZATION ?= -Os
</source>

Remember to do a ''make clean; make'' to rebuild the entire kernel for the changes to take effect.

The code size will usually decrease as a percentage of the total code size, as this option affects how the compiler generates code. 5 to 10% decrease is a common figure. Although I haven't found benchmarks showing how much this affects execution speed, usually the impact isn't that high, and code runs definitely much faster with respect to disabling optimizations altogether (with ''-O0''), so if you are tight on code size this is an easy option that does not require to sacrifice any feature of the kernel.

With the empty ''main()'', Miosix v3.10 and the stm32f411ce_blackpill, the code size was reduced to 39368 bytes.

== Disable DevFs ==

'''Note:''' starting from Miosix 3, DevFs is disabled by default, so there's nothing to do here. This section is kept for reference.

Miosix 2 comes with an in-memory filesystem, mounted at ''/dev'' where device files can be added, similarly to how a Linux machine works. The main purpose of this is to allow [[Miosix processes|processes]] to access peripherals, since due to memory protection they can't just access the peripheral registers. However, processes are currently disabled by default because they're still an experimental feature, so you can disable DevFs too. This can be done by commenting out the ''WITH_DEVFS'' line in [https://github.com/fedetft/miosix-kernel/blob/master/miosix/config/miosix_settings.h config/miosix_settings.h], like this:

<source lang="CPP">
//#define WITH_DEVFS
</source>

== Disable the filesystem entirely ==

'''Note:''' starting from Miosix 3, the filesystem is disabled by default since only some board provide the required hardware, so there's nothing to do here. This section is kept for reference.

Miosix 2 has a completely rewritten filesystem subsystem, supporting multiple mountpoints, extensible filesystem types (currently Fat32 and DevFs), unicode UTF8 in file names, directory listing via the standard ''opendir()''/''readdir()''/''closedir()'' and more POSIX compliance, including inode emulation for Fat32. This comes at a code size cost, though. If your application does not need to read/write from files, you can disable the filesystem subsystem entirely. To do so, open [https://github.com/fedetft/miosix-kernel/blob/master/miosix/config/miosix_settings.h config/miosix_settings.h] and comment out both the ''WITH_DEVFS'' and ''WITH_FILESYSTEM'' lines.

== Use iprintf() instead of printf() in your application ==

'''Note:''' since this example focuses on an empty main, there's nothing to do here, but this tip is worth knowing when writing application code.

''iprintf()'' is a non-standard extension of the [https://www.sourceware.org/newlib newlib] C library used by Miosix. It can do all what ''printf()'' can do except printing floating point numbers, and that's why its code size is significantly lower, printing floating point numbers is quite complicated. Miosix already uses ''iprintf()'' internally, so to see the code size difference you have to write the following simple code in ''main()''

<source lang="CPP">
int main()
{
int i=0;
printf("%d\n",i);
//iprintf("%d\n",i);
}
</source>

Trying with ''iprintf()'' instead of ''printf()'', a 18KB code size reduction is observed. Note that you have to use a format string containing a % argument, such as %d to see the code size difference. If there is no % in the format string, GCC may replace ''printf()''/''iprintf()'' with a call to ''puts()'' as an optimization, and no code size difference can be seen.

== Disable the C++ exception runtime ==

The Miosix kernel is by default compiled with support for C++ exceptions, and unless you're also enabling [[Miosix processes|processes]] that depend on C++ exceptions, it is possible to disable their support. To do so, open [https://github.com/fedetft/miosix-kernel/blob/master/miosix/config/Makefile.inc config/Makefile.inc] and uncomment the following line:

<source lang="bash">
OPT_EXCEPT := -fno-exceptions -fno-rtti -D__NO_EXCEPTIONS
</source>

Remember to do a ''make clean; make'' to rebuild the entire kernel for the changes to take effect.

The code size is reduced to 24384 bytes, but comes with quite an important side effect: if the heap is full, the kernel will reboot the machine. To explain why it is so, consider that the normal behavior in Miosix to handle a full heap is that the C ''malloc()'' returns ''NULL'', while the C++ ''operator new'' throws an exception of type ''bad_alloc''. Now, when exceptions are disabled, ''new'' can no longer throw, but C++ code inside the C++ standard library doesn't check for ''NULL'', as it expects an exception, and that would result in undefined behavior. The only way to prevent undefined behavior, is to reboot the machine, and that is what Miosix does if you disable exceptions.

== Disable boot logs ==

Maybe you're not using ''printf()'' at all in your application, however in this case you're still paying for the code size of ''iprintf()'' as the kernel uses it to print boot logs and error logs. To disable them, you can open [https://github.com/fedetft/miosix-kernel/blob/master/miosix/config/miosix_settings.h config/miosix_settings.h] and comment out the lines ''#define WITH_BOOTLOG'' and ''#define WITH_ERRLOG'':

<source lang="CPP">
/// \def WITH_BOOTLOG
/// Uncomment to print bootlogs on stdout.
/// By default it is defined (bootlogs are printed)
//#define WITH_BOOTLOG

/// \def WITH_ERRLOG
/// Uncomment for debug information on stdout.
/// By default it is defined (error information is printed)
//#define WITH_ERRLOG
</source>

This allows to save the code size of iprintf, but this is only true if there's no ''printf()'' call in your code, otherewise the code size saving will be minimal.

Also, keep in mind that error logs are a powerful tool to [[Debugging|debug]] crashes of your application or the kernel during code development, so you may want to disable them only in release builds, and keep them enabled during development.

Finally, note that you can still access the serial port without using ''printf()'', by means of the POSIX calls ''write()'' and ''read()'', using ''STDOUT_FILENO'' and ''STDIN_FILENO'' as the ''fd'' argument.

With this optimization, the code size is reduced to 13084 bytes.

== One more thing, disable the serial port ==

The kernel, during the boot process, configures a serial port on nearly all the supported boards. If you really have no use for the serial port, you can disable it entirely, saving additional code size. To do so there is no configuration option, but you can edit the board support package file of your board. For the ''stm32f411ce_blackpill'' it's [https://github.com/fedetft/miosix-kernel/blob/master/miosix/arch/board/stm32f411ce_blackpill/interfaces-impl/bsp.cpp miosix-kernel/miosix/arch/board/stm32f411ce_blackpill/interfaces-impl/bsp.cpp]. Open the file and comment out the following lines in ''IRQbspInit()''

<source lang="CPP">
// IRQsetDefaultConsole(
// STM32SerialBase::get<defaultSerialTxPin,defaultSerialRxPin,
// defaultSerialRtsPin,defaultSerialCtsPin>(
// defaultSerial,defaultSerialSpeed,
// defaultSerialFlowctrl,defaultSerialDma));
</source>

as well as the following line in ''shutdown()'' and ''reboot()''

<source lang="CPP">
//ioctl(STDOUT_FILENO,IOCTL_SYNC,0);
</source>

By applying also this last tip code size can be reduced to 8436 bytes.

[[Category:Installation and Configuration]]
[[Category:Optimization]]

Windows Quick Start

2026-05-10T21:03:18Z

Fede.tft:

= Installing the required software =

== Miosix Toolchain ==

To be able to compile the Miosix kernel and your application, you need a patched version of the GCC compiler called Miosix toolchain, you can find the link to download it [[Miosix Toolchain|here]]. At the end of the installation you will need to reboot your computer (sorry, it's Windows...)

== Git ==

To download the Miosix kernel and keep it up to date, you need the [https://en.wikipedia.org/wiki/Git_%28software%29 git] version control system.

It is recommended to install it from [http://www.git-scm.com/download/win git-scm.com]. Please '''do not''' uncheck the ''Windows Explorer integration'' feature during the installation, as you will need it to install the kernel sources.

== Perl ==

The [https://en.wikipedia.org/wiki/Perl Perl] programming language is used by the Miosix build system. Unlike on GNU/Linux computers where Perl is pre-installed, for Windows you'll need to install it separately.

[http://strawberryperl.com Strawberry perl] is the recomended Perl version for Miosix on Windows.

== Flashing tool ==

With the installed Miosix toolchain you'll be able to compile the kernel, but you'll also need a way to transfer it to your microcontroller. This operation is usually called 'flashing' the microcontroller. Miosix can work with any flashing utility that accepts as input raw binary files, and on Windows you'll usually want to install the flashing tool provided by your chip vendor.

For STM32 chips, you can use the STLink utility available [http://www.st.com/web/en/catalog/tools/PF258168# here].

== Text editor or IDE ==

It is recommended to download a better text editor than Notepad, as you will need it to edit the Miosix configuration files. [http://www.notepad-plus-plus.org/ Notepad++] is a good option, but many other options exist. Just '''don't use Notepad''', because it does not recognize Unix [https://en.wikipedia.org/wiki/Line_ending line-endings] and will show you Miosix source files as if they were composed of a single line of text.

As an alternative to Notepad++, you may want to use an [[IDEs|IDE]].

== Serial port viewer ==

Miosix redirects ''stdin''/''stdout'' to a serial port by default on most boards, so to see the boot log and the output of ''printf()'' in your application you need a program to interact with the serial port. [https://putty.org/index.html PuTTY] is an option, although old fashioned. TODO: There are likely better options for Windows too.

= Downloading and configuring the Miosix kernel =

This section is a stripped down guide with the bare minimum to get you started, we also have a full guide about [[Miosix and git workflow]]. Following the tutorial in this page, your project directory will '''not''' be under version control (git). The [[Miosix and git workflow]] page shows how to create a git repository for your project and add the Miosix kernel as a git submodule.

Before downloading the kernel, however, you first have to create '''a directory for your project''' (in this case, the hello world), and then clone the kernel '''as a subdirectory'''.

Using the Windows explorer, create a '''hello''' directory, double click on it. Then right-click on the empty directory. Select ''Git bash'' to open a git shell. This opens a shell where you can type the commands to download the kernel.

[[File:Git-bash-windows.png]]

Note that it is possible to paste commands in the shell (so as to avoid typing them, which can be tedious and lead to typos), but you have to do it one line of text at a time, and to paste you need to use the ''Shift+Ins'' shortcut, not the usual ''Ctrl+V'' one. The last command, ''exit'', will close the shell.

<source lang="bash">
git clone https://github.com/fedetft/miosix-kernel.git
exit
</source>

Note that there is also a ''Git GUI'' in the right click menu, but git is best used from a command line interface, you're on your own if you choose to use git from the GUI.

== Initializing a Miosix project ==

For reasons explained in depth in the [[Miosix and git workflow]] page, you'll need to copy the Miosix configuration directory from the kernel sources to your project directory, as well as create a template project where you can start writing code.
This can be automated with a [https://en.wikipedia.org/wiki/Perl Perl] script called ''init_project_out_of_git_tree.pl''. To run it, you need to open a Windows terminal (which is a '''different''' terminal than the git bash we used before), which can be done by ''Shift+Right click'' and selecting ''Open command window here'':

[[File:Open-terminal-windows.png]]

Then, type the following command:

<source lang="bash">
perl miosix-kernel/tools/init_project_out_of_git_tree.pl
</source>

Leave the terminal open as you'll need it later.

You should run the script from the directory where you want to initialize your empty project, such as the '''hello''' directory in this tutorial. A successful run of the script produces the following output:

<source lang="bash">
Successfully created Miosix project
Target directory: hello
Kernel directory: hello/miosix-kernel/miosix
</source>

Your project directory should now look like the following picture, with the ''miosix-kernel'' directory containing the kernel sources, the ''config'' directory with the kernel configuration, the empty ''main.cpp'' and the build files for the two alternative build systems supported by Miosix: Makefile and CMake:

[[File:Initialized-miosix-project-windows.png]]

For this tutorial, we'll use the Makefile build system, have a look at the [[CMake]] page to learn how to use CMake instead.

== Configuring the kernel ==

The minimum configuration required to compile the kernel is to '''select a board''', as the kernel needs to build the appropriate board support package for it.

The Miosix kernel has several other build-time configuration options, to enable optional components (filesystem, userspace processes), select algorithms such as the scheduler and trade feature support for code size, but these won't be covered here.
The kernel is configured by editing files in the config directory, the two most important ones are [https://github.com/fedetft/miosix-kernel/blob/master/miosix/config/Makefile.inc Makefile.inc] and [https://github.com/fedetft/miosix-kernel/blob/master/miosix/config/miosix_settings.h miosix_settings.h].

To select a board, using Notepad++ open the first one, ''config/Makefile.inc''. Look for the ''OPT_BOARD'' section of the file, which contains the list of boards officially supported by the kernel. In this section, all boards appear commented out (the ''#'' sign is a comment in Makefile syntax), so you need to uncomment the line corrsponding to your board. [[Porting]] the kernel to a new board is an advanced topic not covered here, so we'll assume you'll want to use an officially supported board. As an example, in this tutorial we'll use the stm32f746zg_nucleo board:

<source lang="bash">
...
#OPT_BOARD := stm32f469ni_stm32f469i-disco
OPT_BOARD := stm32f746zg_nucleo
#OPT_BOARD := stm32f765ii_marco_ram_board
...
</source>

If you do not yet have a board, you can follow along and get to the compiled firmware anyway. If you're looking for suggestions on which board to get, consider that most boards currently supported by Miosix are for STM32 microcontrollers. Here's a basic guide:
* '''Nucleo''' STM32 boards produced by ST are good for beginners, as they allow to power the board, flash it, debug it and access the serial port all through a single USB connection with your computer. The stm32f401re_nucleo and stm32f411re_nucleo are realtively low cost.
* '''Discovery''' STM32 boards are also good, but they don't include an USB to serial adapter so you'll have to buy it separately and you'll end up having to connect two USB cables, one for power/programming/debugging and one for the serial port.
* '''Third party''' STM32 boards such as the stm32f411ce_blackpill are cheaper and great to embed in your hardware project, but you'll have to [[https://en.wikipedia.org/wiki/Soldering solder]] the pin header yourself, and you'll need to attach a separate USB to serial adapter, and if you want in-circuit debugging you'll need an STLink adapter, so you'll end up having to run up to three separate USB cables from your computer to the board for power/programming, serial port and debugging.
* Venturing outside of STM32, the '''RP2040''' is a good choice. Also in this case, you'll need a separate USB to serial adapter and some soldering skills, though.

= Writing your first Miosix program =

== Hello world ==

With Notepad++ open the ''main.cpp'' file with your [[IDEs | IDE]] or text editor of choice, and replace its content with the following program:
<source lang="CPP">
#include <cstdio>
#include <thread>
#include <miosix.h>
#include <interfaces/bsp.h>

using namespace std;
using namespace miosix;

int main()
{
for(;;)
{
iprintf("Hello world\n");
ledOn();
this_thread::sleep_for(500ms);
ledOff();
this_thread::sleep_for(500ms);
}
}
</source>

At this point, it's good to have a quick walkthrough of this hello world program. Miosix is based on a [[Fluid kernel]] architecture: in a nutshell it's a kernel that supports writing applications both inside the kernel, and inside userspace programs. In this tutorial, we're using it as a unikernel. This means when power is applied to the board, the kernel will boot, and then start running the ''main()'' function you just wrote ''in kernelspace''. This means you have both support for C/C++ standard libraries and unrestricted hardware access.

This main() function will print "Hello world" and blink an LED approximately every second.
The printing is done with the ''iprintf()'' function. If you expected just ''printf()'' without the ''i'', the reason is that Miosix uses the [https://sourceware.org/newlib/ Newlib] C standard library that provides both ''printf()'' and ''iprintf()'', an optimized version that is smaller in code size but incapable of printing floating point numbers. So you can also use ''printf()'' if you wish, but this optimization is worth knowing from the start.

Sleeping to blink the LED is done with the [https://en.cppreference.com/cpp/thread/sleep_for sleep_for()] function from the C++ standard library. Miosix supports other sleeping APIs, such as [https://pubs.opengroup.org/onlinepubs/9699919799/functions/nanosleep.html nanosleep()] from POSIX, or ''Thread::sleep()'', a native Miosix function. All these functions do the same thing: they tell the scheduler to stop the currently running thread, run some other thread, and resume execution after a given time interval. Miosix is a preemptive multithreading operating system, so you should get comfortable with the fact that the code you're writing lives in a thread and shares the CPU with other threads.

Many (but not all!) board support packages define the ''ledOn()'' and ''ledOff()'' functions to control one of the LED on the board. This should be true for all the boards that have at least one software-accessible LED. This is true for the ''stm32f746zg_nucleo'' board we selected, but if you selected a different board with no LEDs, then compiling will fail with an error related to ''ledOn()'' and ''ledOff()''. You can comment out those two lines in this case, your hello world will only print to the serial port.

== Compiling ==

In the same terminal you used to run Perl, type ''make'' to build the kernel.

<source lang="bash">
make
</source>

If all goes well, the result should look like this.

[[File:Make-output-windows.png]]

Otherwise, compiler errors will appear in the shell. The number that appears under ''text'' in the make output is the size in bytes of your application plus the kernel. Don't worry about the 42KBytes code size, you're compiling with the default Miosix options, if you want you can play around with the options later to [[Miosix code size optimization|reduce the code size]].

== Flashing ==

The procedure to flash the microcontroller board on Windows depends on the vendor-provided flashing tool. They usually provide a GUI where you can load the ''.bin'' file and then connect to the board and flash it. For Miosix the file is named main.bin if you're not using processes, or image.bin if you are using processes. For this tutorial, look for ''main.bin'' in the '''hello''' directory.

If you correctly flashed the board, the LED will start blinking.

== Accessing the serial port ==

The USB to serial port adapter will appear on Windows as a randomly numbered COM port. To figure out the right number, you'll have to open ''Devices'' from the control panel:

[[File:Windows-list-devices.png]]

Today, on my computer, Windows decided to assign the STM32 board to COM3.

Next up, open PuTTY and configure it to open the right COM port. Starting from Miosix v3.00, all boards use by default a baud rate of 115200bit/s, so input 115200 in the ''Speed'' field:

[[File:Windows-putty-configuration.png]]

Finally, click ''Open'' and you should see the serial port messages from the microcontroller. Since the board will be already running when you connect, you can press the RESET button on the board to reboot it and see the boot logs:

[[File:Windows-putty-serial.png]]

= A note on uninstalling software =

To uninstall the Miosix Toolchain, you can find the uninstaller in the start menu under ''Miosix Toolchain''. Note that the other tools such as Git, Perl and the STLink utility have their own uninstallers.

[[Category:Installation and Configuration]]

Windows Quick Start

2026-05-10T21:00:27Z

Fede.tft:

= Installing the required software =

== Miosix Toolchain ==

To be able to compile the Miosix kernel and your application, you need a patched version of the GCC compiler called Miosix toolchain, you can find the link to download it [[Miosix Toolchain|here]]. At the end of the installation you will need to reboot your computer (sorry, it's Windows...)

== Git ==

To download the Miosix kernel and keep it up to date, you need the [https://en.wikipedia.org/wiki/Git_%28software%29 git] version control system.

It is recommended to install it from [http://www.git-scm.com/download/win git-scm.com]. Please '''do not''' uncheck the ''Windows Explorer integration'' feature during the installation, as you will need it to install the kernel sources.

== Perl ==

The [https://en.wikipedia.org/wiki/Perl Perl] programming language is used by the Miosix build system. Unlike on GNU/Linux computers where Perl is pre-installed, for Windows you'll need to install it separately.

[http://strawberryperl.com Strawberry perl] is the recomended Perl version for Miosix on Windows.

== Flashing tool ==

With the installed Miosix toolchain you'll be able to compile the kernel, but you'll also need a way to transfer it to your microcontroller. This operation is usually called 'flashing' the microcontroller. Miosix can work with any flashing utility that accepts as input raw binary files, and on Windows you'll usually want to install the flashing tool provided by your chip vendor.

For STM32 chips, you can use the STLink utility available [http://www.st.com/web/en/catalog/tools/PF258168# here].

== Text editor or IDE ==

It is recommended to download a better text editor than Notepad, as you will need it to edit the Miosix configuration files. [http://www.notepad-plus-plus.org/ Notepad++] is a good option, but many other options exist. Just '''don't use Notepad''', because it does not recognize Unix [https://en.wikipedia.org/wiki/Line_ending line-endings] and will show you Miosix source files as if they were composed of a single line of text.

As an alternative to Notepad++, you may want to use an [[IDEs|IDE]].

== Serial port viewer ==

Miosix redirects ''stdin''/''stdout'' to a serial port by default on most boards, so to see the boot log and the output of ''printf()'' in your application you need a program to interact with the serial port. [https://putty.org/index.html PuTTY] is an option, although old fashioned. TODO: There are likely better options for Windows too.

= Downloading and configuring the Miosix kernel =

This section is a stripped down guide with the bare minimum to get you started, we also have a full guide about [[Miosix and git workflow]]. Following the tutorial in this page, your project directory will '''not''' be under version control (git). The [[Miosix and git workflow]] page shows how to create a git repository for your project and add the Miosix kernel as a git submodule.

Before downloading the kernel, however, you first have to create '''a directory for your project''' (in this case, the hello world), and then clone the kernel '''as a subdirectory'''.

Using the Windows explorer, create a '''hello''' directory, double click on it. Then right-click on the empty directory. Select ''Git bash'' to open a git shell. This opens a shell where you can type the commands to download the kernel.

[[File:Git-bash-windows.png]]

Note that it is possible to paste commands in the shell (so as to avoid typing them, which can be tedious and lead to typos), but you have to do it one line of text at a time, and to paste you need to use the ''Shift+Ins'' shortcut, not the usual ''Ctrl+V'' one. The last command, ''exit'', will close the shell.

<source lang="bash">
git clone https://github.com/fedetft/miosix-kernel.git
exit
</source>

Note that there is also a ''Git GUI'' in the right click menu, but git is best used from a command line interface, you're on your own if you choose to use git from the GUI.

== Initializing a Miosix project ==

For reasons explained in depth in the [[Miosix and git workflow]] page, you'll need to copy the Miosix configuration directory from the kernel sources to your project directory, as well as create a template project where you can start writing code.
This can be automated with a [https://en.wikipedia.org/wiki/Perl Perl] script called ''init_project_out_of_git_tree.pl''. To run it, you need to open a Windows terminal (which is a '''different''' terminal than the git bash we used before), which can be done by ''Shift+Right click'' and selecting ''Open command window here'':

[[File:Open-terminal-windows.png]]

Then, type the following command:

<source lang="bash">
perl miosix-kernel/tools/init_project_out_of_git_tree.pl
</source>

Leave the terminal open as you'll need it later.

You should run the script from the directory where you want to initialize your empty project, such as the '''hello''' directory in this tutorial. A successful run of the script produces the following output:

<source lang="bash">
Successfully created Miosix project
Target directory: hello
Kernel directory: hello/miosix-kernel/miosix
</source>

Your project directory should now look like the following picture, with the ''miosix-kernel'' directory containing the kernel sources, the ''config'' directory with the kernel configuration, the empty ''main.cpp'' and the build files for the two alternative build systems supported by Miosix: Makefile and CMake:

[[File:Initialized-miosix-project-windows.png]]

For this tutorial, we'll use the Makefile build system, have a look at the [[CMake]] page to learn how to use CMake instead.

== Configuring the kernel ==

The minimum configuration required to compile the kernel is to '''select a board''', as the kernel needs to build the appropriate board support package for it.

The Miosix kernel has several other build-time configuration options, to enable optional components (filesystem, userspace processes), select algorithms such as the scheduler and trade feature support for code size, but these won't be covered here.
The kernel is configured by editing files in the config directory, the two most important ones are [https://github.com/fedetft/miosix-kernel/blob/master/miosix/config/Makefile.inc Makefile.inc] and [https://github.com/fedetft/miosix-kernel/blob/master/miosix/config/miosix_settings.h miosix_settings.h].

To select a board, using Notepad++ open the first one, ''config/Makefile.inc''. Look for the ''OPT_BOARD'' section of the file, which contains the list of boards officially supported by the kernel. In this section, all boards appear commented out (the ''#'' sign is a comment in Makefile syntax), so you need to uncomment the line corrsponding to your board. [[Porting]] the kernel to a new board is an advanced topic not covered here, so we'll assume you'll want to use an officially supported board. As an example, in this tutorial we'll use the stm32f746zg_nucleo board:

<source lang="bash">
...
#OPT_BOARD := stm32f469ni_stm32f469i-disco
OPT_BOARD := stm32f746zg_nucleo
#OPT_BOARD := stm32f765ii_marco_ram_board
...
</source>

If you do not yet have a board, you can follow along and get to the compiled firmware anyway. If you're looking for suggestions on which board to get, consider that most boards currently supported by Miosix are for STM32 microcontrollers. Here's a basic guide:
* '''Nucleo''' STM32 boards produced by ST are good for beginners, as they allow to power the board, flash it, debug it and access the serial port all through a single USB connection with your computer. The stm32f401re_nucleo and stm32f411re_nucleo are realtively low cost.
* '''Discovery''' STM32 boards are also good, but they don't include an USB to serial adapter so you'll have to buy it separately and you'll end up having to connect two USB cables, one for power/programming/debugging and one for the serial port.
* '''Third party''' STM32 boards such as the stm32f411ce_blackpill are cheaper and great to embed in your hardware project, but you'll have to [[https://en.wikipedia.org/wiki/Soldering solder]] the pin header yourself, and you'll need to attach a separate USB to serial adapter, and if you want in-circuit debugging you'll need an STLink adapter, so you'll end up having to run up to three separate USB cables from your computer to the board for power/programming, serial port and debugging.
* Venturing outside of STM32, the '''RP2040''' is a good choice. Also in this case, you'll need a separate USB to serial adapter and some soldering skills, though.

= Writing your first Miosix program =

== Hello world ==

With Notepad++ open the ''main.cpp'' file with your [[IDEs | IDE]] or text editor of choice, and replace its content with the following program:
<source lang="CPP">
#include <cstdio>
#include <thread>
#include <miosix.h>
#include <interfaces/bsp.h>

using namespace std;
using namespace miosix;

int main()
{
for(;;)
{
iprintf("Hello world\n");
ledOn();
this_thread::sleep_for(500ms);
ledOff();
this_thread::sleep_for(500ms);
}
}
</source>

At this point, it's good to have a quick walkthrough of this hello world program. Miosix is based on a [[Fluid kernel]] architecture: in a nutshell it's a kernel that supports writing applications both inside the kernel, and inside userspace programs. In this tutorial, we're using it as a unikernel. This means when power is applied to the board, the kernel will boot, and then start running the ''main()'' function you just wrote ''in kernelspace''. This means you have both support for C/C++ standard libraries and unrestricted hardware access.

This main() function will print "Hello world" and blink an LED approximately every second.
The printing is done with the ''iprintf()'' function. If you expected just ''printf()'' without the ''i'', the reason is that Miosix uses the [https://sourceware.org/newlib/ Newlib] C standard library that provides both ''printf()'' and ''iprintf()'', an optimized version that is smaller in code size but incapable of printing floating point numbers. So you can also use ''printf()'' if you wish, but this optimization is worth knowing from the start.

Sleeping to blink the LED is done with the [https://en.cppreference.com/cpp/thread/sleep_for sleep_for()] function from the C++ standard library. Miosix supports other sleeping APIs, such as [https://pubs.opengroup.org/onlinepubs/9699919799/functions/nanosleep.html nanosleep()] from POSIX, or ''Thread::sleep()'', a native Miosix function. All these functions do the same thing: they tell the scheduler to stop the currently running thread, run some other thread, and resume execution after a given time interval. Miosix is a preemptive multithreading operating system, so you should get comfortable with the fact that the code you're writing lives in a thread and shares the CPU with other threads.

Many (but not all!) board support packages define the ''ledOn()'' and ''ledOff()'' functions to control one of the LED on the board. This should be true for all the boards that have at least one software-accessible LED. This is true for the ''stm32f746zg_nucleo'' board we selected, but if you selected a different board with no LEDs, then compiling will fail with an error related to ''ledOn()'' and ''ledOff()''. You can comment out those two lines in this case, your hello world will only print to the serial port.

== Compiling ==

In the same terminal you used to run Perl, type ''make'' to build the kernel. If all goes well, the result should look like this.

[[File:Make-output-windows.png]]

Otherwise, compiler errors will appear in the shell. The number that appears under ''text'' in the make output is the size in bytes of your application plus the kernel. Don't worry about the 42KBytes code size, you're compiling with the default Miosix options, if you want you can play around with the options later to [[Miosix code size optimization|reduce the code size]].

== Flashing ==

The procedure to flash the microcontroller board on Windows depends on the vendor-provided flashing tool. They usually provide a GUI where you can load the ''.bin'' file and then connect to the board and flash it. For Miosix the file is named main.bin if you're not using processes, or image.bin if you are using processes. For this tutorial, look for ''main.bin'' in the '''hello''' directory.

If you correctly flashed the board, the LED will start blinking.

== Accessing the serial port ==

The USB to serial port adapter will appear on Windows as a randomly numbered COM port. To figure out the right number, you'll have to open ''Devices'' from the control panel:

[[File:Windows-list-devices.png]]

Today, on my computer, Windows decided to assign the STM32 board to COM3.

Next up, open PuTTY and configure it to open the right COM port. Starting from Miosix v3.00, all boards use by default a baud rate of 115200bit/s, so input 115200 in the ''Speed'' field:

[[File:Windows-putty-configuration.png]]

Finally, click ''Open'' and you should see the serial port messages from the microcontroller. Since the board will be already running when you connect, you can press the RESET button on the board to reboot it and see the boot logs:

[[File:Windows-putty-serial.png]]

= A note on uninstalling software =

To uninstall the Miosix Toolchain, you can find the uninstaller in the start menu under ''Miosix Toolchain''. Note that the other tools such as Git, Perl and the STLink utility have their own uninstallers.

[[Category:Installation and Configuration]]

Linux Quick Start

2026-05-10T20:59:00Z

Fede.tft:

= Installing the required software =

== Install the Miosix Toolchain ==

To be able to compile the Miosix kernel and your application, you need a patched version of the GCC compiler called [[Miosix Toolchain]]. This page explains how to install the precompiled Miosix Toolchain. If you prefer compiling GCC from sources, see [[Building GCC from sources]]. The commands to run are as follows, where you'll need to replace <version> with the (usually latest) version found in the [[Miosix Toolchain]] page.

<source lang="bash">
wget https://miosix.org/toolchain/MiosixToolchainInstaller<version>.run
sh MiosixToolchainInstaller<version>.run
</source>

The installer will ask for your root password to copy the compiler to the ''/opt'' directory, and put symlinks to ''/usr/bin''. If you later want to uninstall the compiler, as part of the installation process an ''uninstall.sh'' script is placed together with the compiler in ''/opt/arm-miosix-eabi''. Uninstalling the previous compiler is done automatically when upgrading to a newer version.

If you do not trust the installer and want to verify its content, or you want to install it locally (in your home folder instead of system-wide), it is possible to extract the content of the installer with the following command. This operation also extracts, without running it, the ''installer.sh'' installation script.

<source lang="bash">
sh MiosixToolchainInstaller<version>.run --noexec --keep
</source>

For a local install you will need to set the ''PATH'' environment variable to include the extracted ''arm-miosix-eabi/bin'' directory.

== Install a flashing tool ==

With the installed Miosix toolchain you'll be able to compile the kernel, but you'll also need a way to transfer it to your microcontroller. This operation is usually called 'flashing' the microcontroller. Miosix can work with any flashing utility that accepts as input raw binary files, so pick whatever your GNU/Linux distro of choice provides. Here is a list of suggestions for the most common microcontrollers used with Miosix: [[Linux flashing tools]].

== Serial port setup ==

Miosix redirects ''stdin''/''stdout'' to a serial port by default on most boards, so to see the boot log and the output of ''printf()'' in your application you need a program to interact with the serial port. A common one is ''GNU screen'', but there are alternatives such as ''minicom'' or ''tio''.

<source lang="bash">
sudo apt install screen # For Ubuntu/Debian
sudo pacman -S screen # For Arch Linux
</source>

On most GNU/Linux distros serial ports and USB to serial adapters like ''/dev/ttyUSB0'' and ''/dev/ttyACM0'' are owned by the ''dialout'' group, so to avoid the need to use ''sudo'' every time you run ''screen'' you need to add your user to that group before you can access them.

<source lang="bash">
sudo usermod -a -G dialout `id -un` # Add yourself to the dialout group
</source>

Note that you may need to reboot your computer before the change takes effect.

= Downloading and configuring the Miosix kernel =

To download the Miosix kernel you need [https://en.wikipedia.org/wiki/Git_%28software%29 git]. If you do not already have it installed you can install it now

<source lang="bash">
sudo apt install git # For Ubuntu/Debian
sudo pacman -S git # For Arch Linux
</source>

This section is a stripped down guide with the bare minimum to get you started, we also have a full guide about [[Miosix and git workflow]]. Following the tutorial in this page, your project directory will '''not''' be under version control (git). The [[Miosix and git workflow]] page shows how to create a git repository for your project and add the Miosix kernel as a git submodule.

Before downloading the kernel, however, you first have to create '''a directory for your project''' (in this case, the hello world), and then clone the kernel '''as a subdirectory'''.

<source lang="bash">
mkdir hello
cd hello
git clone https://github.com/fedetft/miosix-kernel.git
</source>

== Initializing a Miosix project ==

For reasons explained in depth in the [[Miosix and git workflow]] page, you'll need to copy the Miosix configuration directory from the kernel sources to your project directory, as well as create a template project where you can start writing code.
This can be automated with a [https://en.wikipedia.org/wiki/Perl Perl] script called ''init_project_out_of_git_tree.pl'':

<source lang="bash">
perl miosix-kernel/tools/init_project_out_of_git_tree.pl
</source>

You should run the script from the directory where you want to initialize your empty project, such as the '''hello''' directory in this tutorial. A successful run of the script produces the following output:

<source lang="bash">
Successfully created Miosix project
Target directory: hello
Kernel directory: hello/miosix-kernel/miosix
</source>

Although Perl is pre-installed in almost all GNU/Linux distros, this script depends on the ''File::Copy::Recursive'' Perl module which often is not. If you get errors running the script, install the missing module as follows and try again:

<source lang="bash">
sudo apt install libfile-copy-recursive-perl # For Ubuntu/Debian
</source>

Your project directory should now look like the following picture, with the ''miosix-kernel'' directory containing the kernel sources, the ''config'' directory with the kernel configuration, the empty ''main.cpp'' and the build files for the two alternative build systems supported by Miosix: Makefile and CMake:

[[File:Initialized-miosix-project-linux.png]]

For this tutorial, we'll use the Makefile build system, have a look at the [[CMake]] page to learn how to use CMake instead.

== Configuring the kernel ==

The minimum configuration required to compile the kernel is to '''select a board''', as the kernel needs to build the appropriate board support package for it.

The Miosix kernel has several other build-time configuration options, to enable optional components (filesystem, userspace processes), select algorithms such as the scheduler and trade feature support for code size, but these won't be covered here.
The kernel is configured by editing files in the config directory, the two most important ones are [https://github.com/fedetft/miosix-kernel/blob/master/miosix/config/Makefile.inc Makefile.inc] and [https://github.com/fedetft/miosix-kernel/blob/master/miosix/config/miosix_settings.h miosix_settings.h].

To select a board, open the first one, ''config/Makefile.inc''. Look for the ''OPT_BOARD'' section of the file, which contains the list of boards officially supported by the kernel. In this section, all boards appear commented out (the ''#'' sign is a comment in Makefile syntax), so you need to uncomment the line corrsponding to your board. [[Porting]] the kernel to a new board is an advanced topic not covered here, so we'll assume you'll want to use an officially supported board. As an example, in this tutorial we'll use the stm32f746zg_nucleo board:

<source lang="bash">
...
#OPT_BOARD := stm32f469ni_stm32f469i-disco
OPT_BOARD := stm32f746zg_nucleo
#OPT_BOARD := stm32f765ii_marco_ram_board
...
</source>

If you do not yet have a board, you can follow along and get to the compiled firmware anyway. If you're looking for suggestions on which board to get, consider that most boards currently supported by Miosix are for STM32 microcontrollers. Here's a basic guide:
* '''Nucleo''' STM32 boards produced by ST are good for beginners, as they allow to power the board, flash it, debug it and access the serial port all through a single USB connection with your computer. The stm32f401re_nucleo and stm32f411re_nucleo are realtively low cost.
* '''Discovery''' STM32 boards are also good, but they don't include an USB to serial adapter so you'll have to buy it separately and you'll end up having to connect two USB cables, one for power/programming/debugging and one for the serial port.
* '''Third party''' STM32 boards such as the stm32f411ce_blackpill are cheaper and great to embed in your hardware project, but you'll have to [https://en.wikipedia.org/wiki/Soldering solder] the pin header yourself, and you'll need to attach a separate USB to serial adapter, and if you want in-circuit debugging you'll need an STLink adapter, so you'll end up having to run up to three separate USB cables from your computer to the board for power/programming, serial port and debugging.
* Venturing outside of STM32, the '''RP2040''' is a good choice. Also in this case, you'll need a separate USB to serial adapter and some soldering skills, though.

= Writing your first Miosix program =

== Hello world ==

Open the ''main.cpp'' file with your [[IDEs | IDE]] or text editor of choice, and replace its content with the following program:
<source lang="CPP">
#include <cstdio>
#include <thread>
#include <miosix.h>
#include <interfaces/bsp.h>

using namespace std;
using namespace miosix;

int main()
{
for(;;)
{
iprintf("Hello world\n");
ledOn();
this_thread::sleep_for(500ms);
ledOff();
this_thread::sleep_for(500ms);
}
}
</source>

At this point, it's good to have a quick walkthrough of this hello world program. Miosix is based on a [[Fluid kernel]] architecture: in a nutshell it's a kernel that supports writing applications both inside the kernel, and inside userspace programs. In this tutorial, we're using it as a unikernel. This means when power is applied to the board, the kernel will boot, and then start running the ''main()'' function you just wrote ''in kernelspace''. This means you have both support for C/C++ standard libraries and unrestricted hardware access.

This main() function will print "Hello world" and blink an LED approximately every second.
The printing is done with the ''iprintf()'' function. If you expected just ''printf()'' without the ''i'', the reason is that Miosix uses the [https://sourceware.org/newlib/ Newlib] C standard library that provides both ''printf()'' and ''iprintf()'', an optimized version that is smaller in code size but incapable of printing floating point numbers. So you can also use ''printf()'' if you wish, but this optimization is worth knowing from the start.

Sleeping to blink the LED is done with the [https://en.cppreference.com/cpp/thread/sleep_for sleep_for()] function from the C++ standard library. Miosix supports other sleeping APIs, such as [https://pubs.opengroup.org/onlinepubs/9699919799/functions/nanosleep.html nanosleep()] from POSIX, or ''Thread::sleep()'', a native Miosix function. All these functions do the same thing: they tell the scheduler to stop the currently running thread, run some other thread, and resume execution after a given time interval. Miosix is a preemptive multithreading operating system, so you should get comfortable with the fact that the code you're writing lives in a thread and shares the CPU with other threads.

Many (but not all!) board support packages define the ''ledOn()'' and ''ledOff()'' functions to control one of the LED on the board. This should be true for all the boards that have at least one software-accessible LED. This is true for the ''stm32f746zg_nucleo'' board we selected, but if you selected a different board with no LEDs, then compiling will fail with an error related to ''ledOn()'' and ''ledOff()''. You can comment out those two lines in this case, your hello world will only print to the serial port.

== Compiling ==

To compile the kernel, open a terminal in the '''hello''' project directory and type:

<source lang="bash">
make -j`nproc`
</source>

The ''-j`nproc`'' is optional, it will compile faster by using the multicore CPU in your computer. If you know how many cores you have, you can also specify the number explicitly, such as ''make -j8''. If all goes well, the result should look like this:

[[File:Make-output-linux.png]]

Otherwise, compiler errors will appear in the shell. The number that appears under ''text'' in the make output is the size in bytes of your application plus the kernel. Don't worry about the 42KBytes code size, you're compiling with the default Miosix options, if you want you can play around with the options later to [[Miosix code size optimization|reduce the code size]].

== Flashing ==

To flash the board, you can use the ''make program'' Makefile rule to automatically download the kernel to the board. Connect the USB cable first, and then run:

<source lang="bash">
make program
</source>

If the operation completed successfully, then the output should be similar to this one, and the LED should blink on the board:

[[File:Make program linux.png]]

If the operation did not succeed, here are some common problems:
* You get a ''command not found'' error. You probably did not install the right flashing tool on your computer, read here [[Linux flashing tools]].
* The flashing tool starts, but throws an error such as ''Couldn't find any ST-Link devices''. You probably do not have the right permissions to access the board. Try ''sudo make program''. If that one works, you'll have to install ''udev rules'' to make the USB device of your board's programming interface accessible from your user. Unfortunately the details to installing (or writing from scratch) the correct udev rules file depend on the combination of the flashing tool and board. None of these are specific to Miosix, so look online in the documentation of your flashing tool.

Another issue in some STM32 boards is that the flashing tool leaves the board in a state where the mcirocontroller blocks either after flashing or if you press the reset button on the board. This issue is again specific to the board and flashing tool and unrelated to Miosix. If you encounter this problem after having programmed the microcontroller, it is recommended to unplug and reconnect the USB cable to powercycle the board. At that point, you should see the LED blinking.

== Accessing the serial port ==

Starting from Miosix v3.00, all boards use by default a baud rate of 115200bit/s.
If you're using a '''Nucleo''' board from ST, the USB to serial port adapter will appear on your computer as ''/dev/ttyACM0'', so use the ''screen'' program with the following parameters:

<source lang="bash">
screen /dev/ttyACM0 115200
</source>

Since the board will be already running when you connect, you can press the RESET button on the board to reboot it and see the boot logs:

[[File:Serial-view-linux.png]]

Exiting the screen program is cumbersome at first, but you'll get used to it quickly. You have to type ''Ctrl-A'', then ''k'' and ''y''. Typing ''Ctrl-C'' won't stop the program, it will just send a ''Ctrl-C'' to the microcontroller.

If you are using a board that does not have an integrated USB to serial adapter, you'll need to figure out to which pins is the default serial connected. To do so, you'll have to look for the kernel configuration file for your board. For example, for the ''stm32f411ce_blackpill'' the file is: [https://github.com/fedetft/miosix-kernel/blob/master/miosix/config/board/stm32f411ce_blackpill/board_settings.h config/board/stm32f411ce_blackpill/board_settings.h], where you'll find that the serial port TX pin is PA9, and the RX pin is PA10. Remember to cross the TX and RX pin, the TX pin of the microcontroller goes to the RX pin of the serial adapter! For reliable communication you'll also have to connect a wire between the board GND and the serial adapter GND.

Another example would be for the RP2040. In this case the configuration file is [https://github.com/fedetft/miosix-kernel/blob/master/miosix/config/board/rp2040_raspberry_pi_pico/board_settings.h config/board/rp2040_raspberry_pi_pico/board_settings.h] and the serial TX pin is P0.0, while RX is P0.1.

The most common standalone USB to serial adapters are based on the FTDI's FT232 chip, which appears on GNU/Linux as ''/dev/ttyUSB0'', so the command to access the serial port would be:

<source lang="bash">
screen /dev/ttyUSB0 115200
</source>

[[Category:Installation and Configuration]]

Linux Quick Start

2026-05-10T20:45:58Z

Fede.tft:

= Installing the required software =

== Install the Miosix Toolchain ==

To be able to compile the Miosix kernel and your application, you need a patched version of the GCC compiler called [[Miosix Toolchain]]. This page explains how to install the precompiled Miosix Toolchain. If you prefer compiling GCC from sources, see [[Building GCC from sources]]. The commands to run are as follows, where you'll need to replace <version> with the (usually latest) version found in the [[Miosix Toolchain]] page.

<source lang="bash">
wget https://miosix.org/toolchain/MiosixToolchainInstaller<version>.run
sh MiosixToolchainInstaller<version>.run
</source>

The installer will ask for your root password to copy the compiler to the ''/opt'' directory, and put symlinks to ''/usr/bin''. If you later want to uninstall the compiler, as part of the installation process an ''uninstall.sh'' script is placed together with the compiler in ''/opt/arm-miosix-eabi''. Uninstalling the previous compiler is done automatically when upgrading to a newer version.

If you do not trust the installer and want to verify its content, or you want to install it locally (in your home folder instead of system-wide), it is possible to extract the content of the installer with the following command. This operation also extracts, without running it, the ''installer.sh'' installation script.

<source lang="bash">
sh MiosixToolchainInstaller<version>.run --noexec --keep
</source>

For a local install you will need to set the ''PATH'' environment variable to include the extracted ''arm-miosix-eabi/bin'' directory.

== Install a flashing tool ==

With the installed Miosix toolchain you'll be able to compile the kernel, but you'll also need a way to transfer it to your microcontroller. This operation is usually called 'flashing' the microcontroller. Miosix can work with any flashing utility that accepts as input raw binary files, so pick whatever your GNU/Linux distro of choice provides. Here is a list of suggestions for the most common microcontrollers used with Miosix: [[Linux flashing tools]].

== Serial port setup ==

Miosix redirects ''stdin''/''stdout'' to a serial port by default on most boards, so to see the boot log and the output of ''printf()'' in your application you need a program to interact with the serial port. A common one is ''GNU screen'', but there are alternatives such as ''minicom'' or ''tio''.

<source lang="bash">
sudo apt install screen # For Ubuntu/Debian
sudo pacman -S screen # For Arch Linux
</source>

On most GNU/Linux distros serial ports and USB to serial adapters like ''/dev/ttyUSB0'' and ''/dev/ttyACM0'' are owned by the ''dialout'' group, so to avoid the need to use ''sudo'' every time you run ''screen'' you need to add your user to that group before you can access them.

<source lang="bash">
sudo usermod -a -G dialout `id -un` # Add yourself to the dialout group
</source>

Note that you may need to reboot your computer before the change takes effect.

= Downloading and configuring the Miosix kernel =

To download the Miosix kernel you need [https://en.wikipedia.org/wiki/Git_%28software%29 git]. If you do not already have it installed you can install it now

<source lang="bash">
sudo apt install git # For Ubuntu/Debian
sudo pacman -S git # For Arch Linux
</source>

This section is a stripped down guide with the bare minimum to get you started, we also have a full guide about [[Miosix and git workflow]]. Following the tutorial in this page, your project directory will '''not''' be under version control (git). The [[Miosix and git workflow]] page shows how to create a git repository for your project and add the Miosix kernel as a git submodule.

Before downloading the kernel, however, you first have to create '''a directory for your project''' (in this case, the hello world), and then clone the kernel '''as a subdirectory'''.

<source lang="bash">
mkdir hello
cd hello
git clone https://github.com/fedetft/miosix-kernel.git
</source>

== Initializing a Miosix project ==

For reasons explained in depth in the [[Miosix and git workflow]] page, you'll need to copy the Miosix configuration directory from the kernel sources to your project directory, as well as create a template project where you can start writing code.
This can be automated with a [https://en.wikipedia.org/wiki/Perl Perl] script called ''init_project_out_of_git_tree.pl'':

<source lang="bash">
perl miosix-kernel/tools/init_project_out_of_git_tree.pl
</source>

You should run the script from the directory where you want to initialize your empty project, such as the '''hello''' directory in this tutorial. A successful run of the script produces the following output:

<source lang="bash">
Successfully created Miosix project
Target directory: hello
Kernel directory: hello/miosix-kernel/miosix
</source>

Although Perl is pre-installed in almost all GNU/Linux distros, this script depends on the ''File::Copy::Recursive'' Perl module which often is not. If you get errors running the script, install the missing module as follows and try again:

<source lang="bash">
sudo apt install libfile-copy-recursive-perl # For Ubuntu/Debian
</source>

Your project directory should now look like the following picture, with the ''miosix-kernel'' directory containing the kernel sources, the ''config'' directory with the kernel configuration, the empty ''main.cpp'' and the build files for the two alternative build systems supported by Miosix: Makefile and CMake:

[[File:Initialized-miosix-project-linux.png]]

For this tutorial, we'll use the Makefile build system, have a look at the [[CMake]] page to learn how to use CMake instead.

== Configuring the kernel ==

The minimum configuration required to compile the kernel is to '''select a board''', as the kernel needs to build the appropriate board support package for it.

The Miosix kernel has several other build-time configuration options, to enable optional components (filesystem, userspace processes), select algorithms such as the scheduler and trade feature support for code size, but these won't be covered here.
The kernel is configured by editing files in the config directory, the two most important ones are [https://github.com/fedetft/miosix-kernel/blob/master/miosix/config/Makefile.inc Makefile.inc] and [https://github.com/fedetft/miosix-kernel/blob/master/miosix/config/miosix_settings.h miosix_settings.h].

To select a board, open the first one, ''config/Makefile.inc''. Look for the ''OPT_BOARD'' section of the file, which contains the list of boards officially supported by the kernel. In this section, all boards appear commented out (the ''#'' sign is a comment in Makefile syntax), so you need to uncomment the line corrsponding to your board. [[Porting]] the kernel to a new board is an advanced topic not covered here, so we'll assume you'll want to use an officially supported board. As an example, in this tutorial we'll use the stm32f746zg_nucleo board:

<source lang="bash">
...
#OPT_BOARD := stm32f469ni_stm32f469i-disco
OPT_BOARD := stm32f746zg_nucleo
#OPT_BOARD := stm32f765ii_marco_ram_board
...
</source>

If you do not yet have a board, you can follow along and get to the compiled firmware anyway. If you're looking for suggestions on which board to get, consider that most boards currently supported by Miosix are for STM32 microcontrollers. Here's a basic guide:
* '''Nucleo''' STM32 boards produced by ST are good for beginners, as they allow to power the board, flash it, debug it and access the serial port all through a single USB connection with your computer. The stm32f401re_nucleo and stm32f411re_nucleo are realtively low cost.
* '''Discovery''' STM32 boards are also good, but they don't include an USB to serial adapter so you'll have to buy it separately and you'll end up having to connect two USB cables, one for power/programming/debugging and one for the serial port.
* '''Third party''' STM32 boards such as the stm32f411ce_blackpill are cheaper and great to embed in your hardware project, but you'll have to [https://en.wikipedia.org/wiki/Soldering solder] the pin header yourself, and you'll need to attach a separate USB to serial adapter, and if you want in-circuit debugging you'll need an STLink adapter, so you'll end up having to run up to three separate USB cables from your computer to the board for power/programming, serial port and debugging.
* Venturing outside of STM32, the '''RP2040''' is a good choice. Also in this case, you'll need a separate USB to serial adapter and some soldering skills, though.

= Writing your first Miosix program =

== Hello world ==

Open the ''main.cpp'' file with your [[IDEs | IDE]] or text editor of choice, and replace its content with the following program:
<source lang="CPP">
#include <cstdio>
#include <thread>
#include <miosix.h>
#include <interfaces/bsp.h>

using namespace std;
using namespace miosix;

int main()
{
for(;;)
{
iprintf("Hello world\n");
ledOn();
this_thread::sleep_for(500ms);
ledOff();
this_thread::sleep_for(500ms);
}
}
</source>

At this point, it's good to have a quick walkthrough of this hello world program. Miosix is based on a [[Fluid kernel]] architecture: in a nutshell it's kernel that supports writing applications both inside the kernel, and inside userspace programs. In this tutorial, we're using it as a unikernel. This means when power is applied to the board, the kernel will boot, and then start running the ''main()'' function you just wrote ''in kernelspace''. This means you have both support for C/C++ standard libraries and unrestricted hardware access.

This main() function will print "Hello world" and blink an LED approximately every second.
The printing is done with the ''iprintf()'' function. If you expected just ''printf()'' without the ''i'', the reason is that Miosix uses the [https://sourceware.org/newlib/ Newlib] C standard library that provides both ''printf()'' and ''iprintf()'', an optimized version that is smaller in code size but incapable of printing floating point numbers. So you can also use ''printf()'' if you wish, but this optimization is worth knowing from the start.

Sleeping to blink the LED is done with the [https://en.cppreference.com/cpp/thread/sleep_for sleep_for()] function from the C++ standard library. Miosix supports other sleeping APIs, such as [https://pubs.opengroup.org/onlinepubs/9699919799/functions/nanosleep.html nanosleep()] from POSIX, or ''Thread::sleep()'', a native Miosix function. All these functions do the same thing: they tell the scheduler to stop the currently running thread, run some other thread, and resume execution after a given time interval. Miosix is a preemptive multithreading operating system, so you should get comfortable with the fact that the code you're writing lives in a thread and shares the CPU with other threads.

Many (but not all!) board support packages define the ''ledOn()'' and ''ledOff()'' functions to control one of the LED on the board. This should be true for all the boards that have at least one software-accessible LED. This is true for the ''stm32f746zg_nucleo'' board we selected, but if you selected a different board with no LEDs, then compiling will fail with an error related to ''ledOn()'' and ''ledOff()''. You can comment out those two lines in this case, your hello world will only print to the serial port.

== Compiling ==

To compile the kernel, open a terminal in the '''hello''' project directory and type:

<source lang="bash">
make -j`nproc`
</source>

The ''-j`nproc`'' is optional, it will compile faster by using the multicore CPU in your computer. If you know how many cores you have, you can also specify the number explicitly, such as ''make -j8''. If all goes well, the result should look like this:

[[File:Make-output-linux.png]]

Otherwise, compiler errors will appear in the shell. The number that appears under ''text'' in the make output is the size in bytes of your application plus the kernel. Don't worry about the 42KBytes code size, you're compiling with the default Miosix options, if you want you can play around with the options later to [[Miosix code size optimization|reduce the code size]].

== Flashing ==

To flash the board, you can use the ''make program'' Makefile rule to automatically download the kernel to the board. Connect the USB cable first, and then run:

<source lang="bash">
make program
</source>

If the operation completed successfully, then the output should be similar to this one, and the LED should blink on the board:

[[File:Make program linux.png]]

If the operation did not succeed, here are some common problems:
* You get a ''command not found'' error. You probably did not install the right flashing tool on your computer, read here [[Linux flashing tools]].
* The flashing tool starts, but throws an error such as ''Couldn't find any ST-Link devices''. You probably do not have the right permissions to access the board. Try ''sudo make program''. If that one works, you'll have to install ''udev rules'' to make the USB device of your board's programming interface accessible from your user. Unfortunately the details to installing (or writing from scratch) the correct udev rules file depend on the combination of the flashing tool and board. None of these are specific to Miosix, so look online in the documentation of your flashing tool.

Another issue in some STM32 boards is that the flashing tool leaves the board in a state where the mcirocontroller blocks either after flashing or if you press the reset button on the board. This issue is again specific to the board and flashing tool and unrelated to Miosix. If you encounter this problem after having programmed the microcontroller, it is recommended to unplug and reconnect the USB cable to powercycle the board. At that point, you should see the LED blinking.

== Accessing the serial port ==

Starting from Miosix v3.00, all boards use by default a baud rate of 115200bit/s.
If you're using a '''Nucleo''' board from ST, the USB to serial port adapter will appear on your computer as ''/dev/ttyACM0'', so use the ''screen'' program with the following parameters:

<source lang="bash">
screen /dev/ttyACM0 115200
</source>

Since the board will be already running when you connect, you can press the RESET button on the board to reboot it and see the boot logs:

[[File:Serial-view-linux.png]]

Exiting the screen program is cumbersome at first, but you'll get used to it quickly. You have to type ''Ctrl-A'', then ''k'' and ''y''. Typing ''Ctrl-C'' won't stop the program, it will just send a ''Ctrl-C'' to the microcontroller.

If you are using a board that does not have an integrated USB to serial adapter, you'll need to figure out to which pins is the default serial connected. To do so, you'll have to look for the kernel configuration file for your board. For example, for the ''stm32f411ce_blackpill'' the file is: [https://github.com/fedetft/miosix-kernel/blob/master/miosix/config/board/stm32f411ce_blackpill/board_settings.h config/board/stm32f411ce_blackpill/board_settings.h], where you'll find that the serial port TX pin is PA9, and the RX pin is PA10. Remember to cross the TX and RX pin, the TX pin of the microcontroller goes to the RX pin of the serial adapter! For reliable communication you'll also have to connect a wire between the board GND and the serial adapter GND.

Another example would be for the RP2040. In this case the configuration file is [https://github.com/fedetft/miosix-kernel/blob/master/miosix/config/board/rp2040_raspberry_pi_pico/board_settings.h config/board/rp2040_raspberry_pi_pico/board_settings.h] and the serial TX pin is P0.0, while RX is P0.1.

The most common standalone USB to serial adapters are based on the FTDI's FT232 chip, which appears on GNU/Linux as ''/dev/ttyUSB0'', so the command to access the serial port would be:

<source lang="bash">
screen /dev/ttyUSB0 115200
</source>

[[Category:Installation and Configuration]]

Linux Quick Start

2026-05-10T20:42:48Z

Fede.tft:

= Installing the required software =

== Install the Miosix Toolchain ==

To be able to compile the Miosix kernel and your application, you need a patched version of the GCC compiler called [[Miosix Toolchain]]. This page explains how to install the precompiled Miosix Toolchain. If you prefer compiling GCC from sources, see [[Building GCC from sources]]. The commands to run are as follows, where you'll need to replace <version> with the (usually latest) version found in the [[Miosix Toolchain]] page.

<source lang="bash">
wget https://miosix.org/toolchain/MiosixToolchainInstaller<version>.run
sh MiosixToolchainInstaller<version>.run
</source>

The installer will ask for your root password to copy the compiler to the ''/opt'' directory, and put symlinks to ''/usr/bin''. If you later want to uninstall the compiler, as part of the installation process an ''uninstall.sh'' script is placed together with the compiler in ''/opt/arm-miosix-eabi''. Uninstalling the previous compiler is done automatically when upgrading to a newer version.

If you do not trust the installer and want to verify its content, or you want to install it locally (in your home folder instead of system-wide), it is possible to extract the content of the installer with the following command. This operation also extracts, without running it, the ''installer.sh'' installation script.

<source lang="bash">
sh MiosixToolchainInstaller<version>.run --noexec --keep
</source>

For a local install you will need to set the ''PATH'' environment variable to include the extracted ''arm-miosix-eabi/bin'' directory.

== Install a flashing tool ==

With the installed Miosix toolchain you'll be able to compile the kernel, but you'll also need a way to transfer it to your microcontroller. This operation is usually called 'flashing' the microcontroller. Miosix can work with any flashing utility that accepts as input raw binary files, so pick whatever your GNU/Linux distro of choice provides. Here is a list of suggestions for the most common microcontrollers used with Miosix: [[Linux flashing tools]].

== Serial port setup ==

Miosix redirects ''stdin''/''stdout'' to a serial port by default on most boards, so to see the boot log and the output of ''printf()'' in your application you need a program to interact with the serial port. A common one is ''GNU screen'', but there are alternatives such as ''minicom'' or ''tio''.

<source lang="bash">
sudo apt install screen # For Ubuntu/Debian
sudo pacman -S screen # For Arch Linux
</source>

On most GNU/Linux distros serial ports and USB to serial adapters like ''/dev/ttyUSB0'' and ''/dev/ttyACM0'' are owned by the ''dialout'' group, so to avoid the need to use ''sudo'' every time you run ''screen'' you need to add your user to that group before you can access them.

<source lang="bash">
sudo usermod -a -G dialout `id -un` # Add yourself to the dialout group
</source>

Note that you may need to reboot your computer before the change takes effect.

= Downloading and configuring the Miosix kernel =

To download the Miosix kernel you need [https://en.wikipedia.org/wiki/Git_%28software%29 git]. If you do not already have it installed you can install it now

<source lang="bash">
sudo apt install git # For Ubuntu/Debian
sudo pacman -S git # For Arch Linux
</source>

This section is a stripped down guide with the bare minimum to get you started, we also have a full guide about [[Miosix and git workflow]]. Following the tutorial in this page, your project directory will '''not''' be under version control (git). The [[Miosix and git workflow]] page shows how to create a git repository for your project and add the Miosix kernel as a git submodule.

Before downloading the kernel, however, you first have to create '''a directory for your project''' (in this case, the hello world), and then clone the kernel '''as a subdirectory'''.

<source lang="bash">
mkdir hello
cd hello
git clone https://github.com/fedetft/miosix-kernel.git
</source>

== Initializing a Miosix project ==

For reasons explained in depth in the [[Miosix and git workflow]] page, you'll need to copy the Miosix configuration directory from the kernel sources to your project directory, as well as create a template project where you can start writing code.
This can be automated with a [https://en.wikipedia.org/wiki/Perl Perl] script called ''init_project_out_of_git_tree.pl'':

<source lang="bash">
perl miosix-kernel/tools/init_project_out_of_git_tree.pl
</source>

You should run the script from the directory where you want to initialize your empty project, such as the '''hello''' directory in this tutorial. A successful run of the script produces the following output:

<source lang="bash">
Successfully created Miosix project
Target directory: hello
Kernel directory: hello/miosix-kernel/miosix
</source>

Although Perl is pre-installed in almost all GNU/Linux distros, this script depends on the ''File::Copy::Recursive'' Perl module which often is not. If you get errors running the script, install the missing module as follows and try again:

<source lang="bash">
sudo apt install libfile-copy-recursive-perl # For Ubuntu/Debian
</source>

Your project directory should now look like the following picture, with the ''miosix-kernel'' directory containing the kernel sources, the ''config'' directory with the kernel configuration, the empty ''main.cpp'' and the build files for the two alternative build systems supported by Miosix: Makefile and CMake:

[[File:Initialized-miosix-project-linux.png]]

For this tutorial, we'll use the Makefile build system, have a look at the [[CMake]] page to learn how to use CMake instead.

== Configuring the kernel ==

The minimum configuration required to compile the kernel is to '''select a board''', as the kernel needs to build the appropriate board support package for it.

The Miosix kernel has several other build-time configuration options, to enable optional components (filesystem, userspace processes), select algorithms such as the scheduler and trade feature support for code size, but these won't be covered here.
The kernel is configured by editing files in the config directory, the two most important ones are [https://github.com/fedetft/miosix-kernel/blob/master/miosix/config/Makefile.inc Makefile.inc] and [https://github.com/fedetft/miosix-kernel/blob/master/miosix/config/miosix_settings.h miosix_settings.h].

To select a board, open the first one, ''config/Makefile.inc''. Look for the ''OPT_BOARD'' section of the file, which contains the list of boards officially supported by the kernel. In this section, all boards appear commented out (the ''#'' sign is a comment in Makefile syntax), so you need to uncomment the line corrsponding to your board. [[Porting]] the kernel to a new board is an advanced topic not covered here, so we'll assume you'll want to use an officially supported board. As an example, in this tutorial we'll use the stm32f746zg_nucleo board:

<source lang="bash">
...
#OPT_BOARD := stm32f469ni_stm32f469i-disco
OPT_BOARD := stm32f746zg_nucleo
#OPT_BOARD := stm32f765ii_marco_ram_board
...
</source>

If you do not yet have a board, you can follow along and get to the compiled firmware anyway. If you're looking for suggestions on which board to get, consider that most boards currently supported by Miosix are for STM32 microcontrollers. Here's a basic guide:
* '''Nucleo''' STM32 boards produced by ST are good for beginners, as they allow to power the board, flash it, debug it and access the serial port all through a single USB connection with your computer. The stm32f401re_nucleo and stm32f411re_nucleo are realtively low cost.
* '''Discovery''' STM32 boards are also good, but they don't include an USB to serial adapter so you'll have to buy it separately and you'll end up having to connect two USB cables, one for power/programming/debugging and one for the serial port.
* '''Third party''' STM32 boards such as the stm32f411ce_blackpill are cheaper and great to embed in your hardware project, but you'll have to [https://en.wikipedia.org/wiki/Soldering solder] the pin header yourself, and you'll need to attach a separate USB to serial adapter, and if you want in-circuit debugging you'll need an STLink adapter, so you'll end up having to run up to three separate USB cables from your computer to the board for power/programming, serial port and debugging.
* Venturing outside of STM32, the '''RP2040''' is a good choice. Also in this case, you'll need a separate USB to serial adapter and some soldering skills, though.

= Writing your first Miosix program =

== Hello world ==

Open the ''main.cpp'' file with your [[IDEs | IDE]] or text editor of choice, and replace its content with the following program:
<source lang="CPP">
#include <cstdio>
#include <thread>
#include <miosix.h>
#include <interfaces/bsp.h>

using namespace std;
using namespace miosix;

int main()
{
for(;;)
{
iprintf("Hello world\n");
ledOn();
this_thread::sleep_for(500ms);
ledOff();
this_thread::sleep_for(500ms);
}
}
</source>

At this point, it's good to have a quick walkthrough of this hello world program. Miosix is based on a [[Fluid kernel]] architecture: in a nutshell it's kernel that supports writing applications both inside the kernel, and inside userspace programs. In this tutorial, we're using it as a unikernel. This means when power is applied to the board, the kernel will boot, and then start running the ''main()'' function you just wrote ''in kernelspace''. This means you have both support for C/C++ standard libraries and unrestricted hardware access.

This main() function will print "Hello world" and blink an LED approximately every second.
The printing is done with the ''iprintf()'' function. If you expected just ''printf()'' without the ''i'', the reason is that Miosix uses the [https://sourceware.org/newlib/ Newlib] C standard library that provides both ''printf()'' and ''iprintf()'', an optimized version that is smaller in code size but incapable of printing floating point numbers. So you can also use ''printf()'' if you wish, but this optimization is worth knowing from the start.

Sleeping to blink the LED is done with the [https://en.cppreference.com/cpp/thread/sleep_for sleep_for()] function from the C++ standard library. Miosix supports other sleeping APIs, such as [https://pubs.opengroup.org/onlinepubs/9699919799/functions/nanosleep.html nanosleep()] from POSIX, or ''Thread::sleep()'', a native Miosix function. All these functions do the same thing: they tell the scheduler to stop the currently running thread, run some other thread, and resume execution after a given time interval. Miosix is a preemptive multithreading operating system, so you should get comfortable with the fact that the code you're writing lives in a thread and shares the CPU with other threads.

Many (but not all!) board support packages define the ''ledOn()'' and ''ledOff()'' functions to control one of the LED on the board. This should be true for all the boards that have at least one software-accessible LED. This is true for the ''stm32f746zg_nucleo'' board we selected, but if you selected a different board with no LEDs, then compiling will fail with an error related to ''ledOn()'' and ''ledOff()''. You can comment out those two lines in this case, your hello world will only print to the serial port.

== Compiling ==

To compile the kernel, open a terminal in the '''hello''' project directory and type:

<source lang="bash">
make -j`nproc`
</source>

The ''-j`nproc`'' is optional, it will compile faster by using the multicore CPU in your computer. If you know how many cores you have, you can also specify the number explicitly, such as ''make -j8''. If all goes well, the result should look like this:

[[File:Make-output-linux.png]]

Otherwise, compiler errors will appear in the shell. The number that appears under ''text'' in the make output is the size in bytes of your application plus the kernel. Don't worry about the 42KBytes code size, you're compiling with the default Miosix options, if you want you can play around with the options later to [[Miosix code size optimization|reduce the code size]].

== Flashing ==

To flash the board, you can use the ''make program'' Makefile rule to automatically download the kernel to the board. Connect the USB cable first, and then run:

<source lang="bash">
make program
</source>

If the operation completed successfully, the the output should be similar to this one, and the LED should blink on the board:

[[File:Make program linux.png]]

If the operation did not succeed, here are some common problems:
* You get a ''command not found'' error. You probably did not install the right flashing tool on your computer, read here [[Linux flashing tools]].
* The flashing tool starts, but throws an error such as ''Couldn't find any ST-Link devices''. You probably do not have the right permissions to access the board. Try ''sudo make program''. If that one works, you'll have to install ''udev rules'' to make the USB device of your board's programming interface accessible from your user. Unfortunately the details to installing (or writing from scratch) the correct udev rules file depend on the combination of the flashing tool and board. None of these are specific to Miosix, so look online in the documentation of your flashing tool.

Another issue in some STM32 boards is that the flashing tool leaves the board in a state where the mcirocontroller blocks either after flashing or if you press the reset button on the board. This issue is again specific to the board and flashing tool and unrelated to Miosix. If you encounter this problem after having programmed the microcontroller, it is recommended to unplug and reconnect the USB cable to powercycle the board. At that point, you should see the LED blinking.

== Accessing the serial port ==

Starting from Miosix v3.00, all boards use by default a baud rate of 115200bit/s.
If you're using a '''Nucleo''' board from ST, the USB to serial port adapter will appear on your computer as ''/dev/ttyACM0'', so use the ''screen'' program with the following parameters:

<source lang="bash">
screen /dev/ttyACM0 115200
</source>

Since the board will be already running when you connect, you can press the RESET button on the board to reboot it and see the boot logs:

[[File:Serial-view-linux.png]]

Exiting the screen program is cumbersome at first, but you'll get used to it quickly. You have to type ''Ctrl-A'', then ''k'' and ''y''. Typing ''Ctrl-C'' won't stop the program, it will just send a ''Ctrl-C'' to the microcontroller.

If you are using a board that does not have an integrated USB to serial adapter, you'll need to figure out to which pins is the default serial connected. To do so, you'll have to look for the kernel configuration file for your board. For example, for the ''stm32f411ce_blackpill'' the file is: [https://github.com/fedetft/miosix-kernel/blob/master/miosix/config/board/stm32f411ce_blackpill/board_settings.h config/board/stm32f411ce_blackpill/board_settings.h], where you'll find that the serial port TX pin is PA9, and the RX pin is PA10. Remember to cross the TX and RX pin, the TX pin of the microcontroller goes to the RX pin of the serial adapter! For reliable communication you'll also have to connect a wire between the board GND and the serial adapter GND.

Another example would be for the RP2040. In this case the configuration file is [https://github.com/fedetft/miosix-kernel/blob/master/miosix/config/board/rp2040_raspberry_pi_pico/board_settings.h config/board/rp2040_raspberry_pi_pico/board_settings.h] and the serial TX pin is P0.0, while RX is P0.1.

The most common standalone USB to serial adapters are based on the FTDI's FT232 chip, which appears on GNU/Linux as ''/dev/ttyUSB0'', so the command to access the serial port would be:

<source lang="bash">
screen /dev/ttyUSB0 115200
</source>

[[Category:Installation and Configuration]]

Windows Quick Start

2026-05-10T17:07:51Z

Fede.tft:

= Installing the required software =

== Miosix Toolchain ==

To be able to compile the Miosix kernel and your application, you need a patched version of the GCC compiler called Miosix toolchain, you can find the link to download it [[Miosix Toolchain|here]]. At the end of the installation you will need to reboot your computer (sorry, it's Windows...)

== Git ==

To download the Miosix kernel and keep it up to date, you need the [https://en.wikipedia.org/wiki/Git_%28software%29 git] version control system.

It is recommended to install it from [http://www.git-scm.com/download/win git-scm.com]. Please '''do not''' uncheck the ''Windows Explorer integration'' feature during the installation, as you will need it to install the kernel sources.

== Perl ==

The [https://en.wikipedia.org/wiki/Perl Perl] programming language is used by the Miosix build system. Unlike on GNU/Linux computers where Perl is pre-installed, for Windows you'll need to install it separately.

[http://strawberryperl.com Strawberry perl] is the recomended Perl version for Miosix on Windows.

== Flashing tool ==

With the installed Miosix toolchain you'll be able to compile the kernel, but you'll also need a way to transfer it to your microcontroller. This operation is usually called 'flashing' the microcontroller. Miosix can work with any flashing utility that accepts as input raw binary files, and on Windows you'll usually want to install the flashing tool provided by your chip vendor.

For STM32 chips, you can use the STLink utility available [http://www.st.com/web/en/catalog/tools/PF258168# here].

== Text editor or IDE ==

It is recommended to download a better text editor than Notepad, as you will need it to edit the Miosix configuration files. [http://www.notepad-plus-plus.org/ Notepad++] is a good option, but many other options exist. Just '''don't use Notepad''', because it does not recognize Unix [https://en.wikipedia.org/wiki/Line_ending line-endings] and will show you Miosix source files as if they were composed of a single line of text.

As an alternative to Notepad++, you may want to use an [[IDEs|IDE]].

== Serial port viewer ==

Miosix redirects ''stdin''/''stdout'' to a serial port by default on most boards, so to see the boot log and the output of ''printf()'' in your application you need a program to interact with the serial port. [https://putty.org/index.html PuTTY] is an option, although old fashioned. TODO: There are likely better options for Windows too.

= Downloading and configuring the Miosix kernel =

This section is a stripped down guide with the bare minimum to get you started, we also have a full guide about [[Miosix and git workflow]]. Following the tutorial in this page, your project directory will '''not''' be under version control (git). The [[Miosix and git workflow]] page shows how to create a git repository for your project and add the Miosix kernel as a git submodule.

Before downloading the kernel, however, you first have to create '''a directory for your project''' (in this case, the hello world), and then clone the kernel '''as a subdirectory'''.

Using the Windows explorer, create a '''hello''' directory, double click on it. Then right-click on the empty directory. Select ''Git bash'' to open a git shell. This opens a shell where you can type the commands to download the kernel.

[[File:Git-bash-windows.png]]

Note that it is possible to paste commands in the shell (so as to avoid typing them, which can be tedious and lead to typos), but you have to do it one line of text at a time, and to paste you need to use the ''Shift+Ins'' shortcut, not the usual ''Ctrl+V'' one. The last command, ''exit'', will close the shell.

<source lang="bash">
git clone https://github.com/fedetft/miosix-kernel.git
exit
</source>

Note that there is also a ''Git GUI'' in the right click menu, but git is best used from a command line interface, you're on your own if you choose to use git from the GUI.

== Initializing a Miosix project ==

For reasons explained in depth in the [[Miosix and git workflow]] page, you'll need to copy the Miosix configuration directory from the kernel sources to your project directory, as well as create a template project where you can start writing code.
This can be automated with a [https://en.wikipedia.org/wiki/Perl Perl] script called ''init_project_out_of_git_tree.pl''. To run it, you need to open a Windows terminal (which is a '''different''' terminal than the git bash we used before), which can be done by ''Shift+Right click'' and selecting ''Open command window here'':

[[File:Open-terminal-windows.png]]

Then, type the following command:

<source lang="bash">
perl miosix-kernel/tools/init_project_out_of_git_tree.pl
</source>

Leave the terminal open as you'll need it later.

You should run the script from the directory where you want to initialize your empty project, such as the '''hello''' directory in this tutorial. A successful run of the script produces the following output:

<source lang="bash">
Successfully created Miosix project
Target directory: hello
Kernel directory: hello/miosix-kernel/miosix
</source>

Your project directory should now look like the following picture, with the ''miosix-kernel'' directory containing the kernel sources, the ''config'' directory with the kernel configuration, the empty ''main.cpp'' and the build files for the two alternative build systems supported by Miosix: Makefile and CMake:

[[File:Initialized-miosix-project-windows.png]]

For this tutorial, we'll use the Makefile build system, have a look at the [[CMake]] page to learn how to use CMake instead.

== Configuring the kernel ==

The minimum configuration required to compile the kernel is to '''select a board''', as the kernel needs to build the appropriate board support package for it.

The Miosix kernel has several other build-time configuration options, to enable optional components (filesystem, userspace processes), select algorithms such as the scheduler and trade feature support for code size, but these won't be covered here.
The kernel is configured by editing files in the config directory, the two most important ones are [https://github.com/fedetft/miosix-kernel/blob/master/miosix/config/Makefile.inc Makefile.inc] and [https://github.com/fedetft/miosix-kernel/blob/master/miosix/config/miosix_settings.h miosix_settings.h].

To select a board, using Notepad++ open the first one, ''config/Makefile.inc''. Look for the ''OPT_BOARD'' section of the file, which contains the list of boards officially supported by the kernel. In this section, all boards appear commented out (the ''#'' sign is a comment in Makefile syntax), so you need to uncomment the line corrsponding to your board. [[Porting]] the kernel to a new board is an advanced topic not covered here, so we'll assume you'll want to use an officially supported board. As an example, in this tutorial we'll use the stm32f746zg_nucleo board:

<source lang="bash">
...
#OPT_BOARD := stm32f469ni_stm32f469i-disco
OPT_BOARD := stm32f746zg_nucleo
#OPT_BOARD := stm32f765ii_marco_ram_board
...
</source>

If you do not yet have a board, you can follow along and get to the compiled firmware anyway. If you're looking for suggestions on which board to get, consider that most boards currently supported by Miosix are for STM32 microcontrollers. Here's a basic guide:
* '''Nucleo''' STM32 boards produced by ST are good for beginners, as they allow to power the board, flash it, debug it and access the serial port all through a single USB connection with your computer. The stm32f401re_nucleo and stm32f411re_nucleo are realtively low cost.
* '''Discovery''' STM32 boards are also good, but they don't include an USB to serial adapter so you'll have to buy it separately and you'll end up having to connect two USB cables, one for power/programming/debugging and one for the serial port.
* '''Third party''' STM32 boards such as the stm32f411ce_blackpill are cheaper and great to embed in your hardware project, but you'll have to [[https://en.wikipedia.org/wiki/Soldering solder]] the pin header yourself, and you'll need to attach a separate USB to serial adapter, and if you want in-circuit debugging you'll need an STLink adapter, so you'll end up having to run up to three separate USB cables from your computer to the board for power/programming, serial port and debugging.
* Venturing outside of STM32, the '''RP2040''' is a good choice. Also in this case, you'll need a separate USB to serial adapter and some soldering skills, though.

= Writing your first Miosix program =

== Hello world ==

With Notepad++ open the ''main.cpp'' file with your [[IDEs | IDE]] or text editor of choice, and replace its content with the following program:
<source lang="CPP">
#include <cstdio>
#include <thread>
#include <miosix.h>
#include <interfaces/bsp.h>

using namespace std;
using namespace miosix;

int main()
{
for(;;)
{
iprintf("Hello world\n");
ledOn();
this_thread::sleep_for(500ms);
ledOff();
this_thread::sleep_for(500ms);
}
}
</source>

At this point, it's good to have a quick walkthrough of this hello world program. Miosix is based on a [[Fluid kernel]] architecture: in a nutshell it's kernel that supports writing applications both inside the kernel, and inside userspace programs. In this tutorial, we're using it as a unikernel. This means when power is applied to the board, the kernel will boot, and then start running the ''main()'' function you just wrote ''in kernelspace''. This means you have both support for C/C++ standard libraries and unrestricted hardware access.

This main() function will print "Hello world" and blink an LED approximately every second.
The printing is done with the ''iprintf()'' function. If you expected just ''printf()'' without the ''i'', the reason is that Miosix uses the [https://sourceware.org/newlib/ Newlib] C standard library that provides both ''printf()'' and ''iprintf()'', an optimized version that is smaller in code size but incapable of printing floating point numbers. So you can also use ''printf()'' if you wish, but this optimization is worth knowing from the start.

Sleeping to blink the LED is done with the [https://en.cppreference.com/cpp/thread/sleep_for sleep_for()] function from the C++ standard library. Miosix supports other sleeping APIs, such as [https://pubs.opengroup.org/onlinepubs/9699919799/functions/nanosleep.html nanosleep()] from POSIX, or ''Thread::sleep()'', a native Miosix function. All these functions do the same thing: they tell the scheduler to stop the currently running thread, run some other thread, and resume execution after a given time interval. Miosix is a preemptive multithreading operating system, so you should get comfortable with the fact that the code you're writing lives in a thread and shared the CPU with other threads.

Many (but not all!) board support packages define the ''ledOn()'' and ''ledOff()'' functions to control one of the LED on the board. This should be true for all the boards that have at least one software-accessible LED. This is true for the ''stm32f746zg_nucleo'' board we selected, but if you selected a different board with no LEDs, then compiling will fail with an error related to ''ledOn()'' and ''ledOff()''. You can comment out those two lines in this case, your hello world will only print to the serial port.

== Compiling ==

In the same terminal you used to run Perl, type ''make'' to build the kernel. If all goes well, the result should look like this.

[[File:Make-output-windows.png]]

Otherwise, compiler errors will appear in the shell. The number that appears under ''text'' in the make output is the size in bytes of your application plus the kernel. Don't worry about the 42KBytes code size, you're compiling with the default Miosix options, if you want you can play around with the options later to [[Miosix code size optimization|reduce the code size]].

== Flashing ==

The procedure to flash the microcontroller board on Windows depends on the vendor-provided flashing tool. They usually provide a GUI where you can load the ''.bin'' file and then connect to the board and flash it. For Miosix the file is named main.bin if you're not using processes, or image.bin if you are using processes. For this tutorial, look for ''main.bin'' in the '''hello''' directory.

If you correctly flashed the board, the LED will start blinking.

== Accessing the serial port ==

The USB to serial port adapter will appear on Windows as a randomly numbered COM port. To figure out the right number, you'll have to open ''Devices'' from the control panel:

[[File:Windows-list-devices.png]]

Today, on my computer, Windows decided to assign the STM32 board to COM3.

Next up, open PuTTY and configure it to open the right COM port. Starting from Miosix v3.00, all boards use by default a baud rate of 115200bit/s, so input 115200 in the ''Speed'' field:

[[File:Windows-putty-configuration.png]]

Finally, click ''Open'' and you should see the serial port messages from the microcontroller. Since the board will be already running when you connect, you can press the RESET button on the board to reboot it and see the boot logs:

[[File:Windows-putty-serial.png]]

= A note on uninstalling software =

To uninstall the Miosix Toolchain, you can find the uninstaller in the start menu under ''Miosix Toolchain''. Note that the other tools such as Git, Perl and the STLink utility have their own uninstallers.

[[Category:Installation and Configuration]]

Windows Quick Start

2026-05-10T17:06:31Z

Fede.tft:

= Installing the required software =

== Miosix Toolchain ==

To be able to compile the Miosix kernel and your application, you need a patched version of the GCC compiler called Miosix toolchain, you can find the link to download it [[Miosix Toolchain|here]]. At the end of the installation you will need to reboot your computer (sorry, it's Windows...)

== Git ==

To download the Miosix kernel and keep it up to date, you need the [https://en.wikipedia.org/wiki/Git_%28software%29 git] version control system.

It is recommended to install it from [http://www.git-scm.com/download/win git-scm.com]. Please '''do not''' uncheck the ''Windows Explorer integration'' feature during the installation, as you will need it to install the kernel sources.

== Perl ==

The [https://en.wikipedia.org/wiki/Perl Perl] programming language is used by the Miosix build system. Unlike on GNU/Linux computers where Perl is pre-installed, for Windows you'll need to install it separately.

[http://strawberryperl.com Strawberry perl] is the recomended Perl version for Miosix on Windows.

== Flashing tool ==

With the installed Miosix toolchain you'll be able to compile the kernel, but you'll also need a way to transfer it to your microcontroller. This operation is usually called 'flashing' the microcontroller. Miosix can work with any flashing utility that accepts as input raw binary files, and on Windows you'll usually want to install the flashing tool provided by your chip vendor.

For STM32 chips, you can use the STLink utility available [http://www.st.com/web/en/catalog/tools/PF258168# here].

== Text editor or IDE ==

It is recommended to download a better text editor than Notepad, as you will need it to edit the Miosix configuration files. [http://www.notepad-plus-plus.org/ Notepad++] is a good option, but many other options exist. Just '''don't use Notepad''', because it does not recognize Unix [https://en.wikipedia.org/wiki/Line_ending line-endings] and will show you Miosix source files as if they were composed of a single line of text.

As an alternative to Notepad++, you may want to use an [[IDEs|IDE]].

== Serial port viewer ==

Miosix redirects ''stdin''/''stdout'' to a serial port by default on most boards, so to see the boot log and the output of ''printf()'' in your application you need a program to interact with the serial port. [https://putty.org/index.html PuTTY] is an option, although old fashioned. TODO: There are likely better options for Windows too.

= Downloading and configuring the Miosix kernel =

This section is a stripped down guide with the bare minimum to get you started, we also have a full guide about [[Miosix and git workflow]]. Following the tutorial in this page, your project directory will '''not''' be under version control (git). The [[Miosix and git workflow]] page shows how to create a git repository for your project and add the Miosix kernel as a git submodule.

Before downloading the kernel, however, you first have to create '''a directory for your project''' (in this case, the hello world), and then clone the kernel '''as a subdirectory'''.

Using the Windows explorer, create a '''hello''' directory, double click on it. Then right-click on the empty directory. Select ''Git bash'' to open a git shell. This opens a shell where you can type the commands to download the kernel.

[[File:Git-bash-windows.png]]

Note that it is possible to paste commands in the shell (so as to avoid typing them, which can be tedious and lead to typos), but you have to do it one line of text at a time, and to paste you need to use the ''Shift+Ins'' shortcut, not the usual ''Ctrl+V'' one. The last command, ''exit'', will close the shell.

<source lang="bash">
git clone https://github.com/fedetft/miosix-kernel.git
exit
</source>

Note that there is also a ''Git GUI'' in the right click menu, but git is best used from a command line interface, you're on your own if you choose to use git from the GUI.

== Initializing a Miosix project ==

For reasons explained in depth in the [[Miosix and git workflow]] page, you'll need to copy the Miosix configuration directory from the kernel sources to your project directory, as well as create a template project where you can start writing code.
This can be automated with a [https://en.wikipedia.org/wiki/Perl Perl] script called ''init_project_out_of_git_tree.pl''. To run it, you need to open a Windows terminal (which is a '''different''' terminal than the git bash we used before), which can be done by ''Shift+Right click'' and selecting ''Open command window here'':

[[File:Open-terminal-windows.png]]

Then, type the following command:

<source lang="bash">
perl miosix-kernel/tools/init_project_out_of_git_tree.pl
</source>

Leave the terminal open as you'll need it later.

You should run the script from the directory where you want to initialize your empty project, such as the '''hello''' directory in this tutorial. A successful run of the script produces the following output:

<source lang="bash">
Successfully created Miosix project
Target directory: hello
Kernel directory: hello/miosix-kernel/miosix
</source>

Your project directory should now look like the following picture, with the ''miosix-kernel'' directory containing the kernel sources, the ''config'' directory with the kernel configuration, the empty ''main.cpp'' and the build files for the two alternative build systems supported by Miosix: Makefile and CMake:

[[File:Initialized-miosix-project-windows.png]]

For this tutorial, we'll use the Makefile build system, have a look at the [[CMake]] page to learn how to use CMake instead.

== Configuring the kernel ==

The minimum configuration required to compile the kernel is to '''select a board''', as the kernel needs to build the appropriate board support package for it.

The Miosix kernel has several other build-time configuration options, to enable optional components (filesystem, userspace processes), select algorithms such as the scheduler and trade feature support for code size, but these won't be covered here.
The kernel is configured by editing files in the config directory, the two most important ones are [https://github.com/fedetft/miosix-kernel/blob/master/miosix/config/Makefile.inc Makefile.inc] and [https://github.com/fedetft/miosix-kernel/blob/master/miosix/config/miosix_settings.h miosix_settings.h].

To select a board, using Notepad++ open the first one, ''config/Makefile.inc''. Look for the ''OPT_BOARD'' section of the file, which contains the list of boards officially supported by the kernel. In this section, all boards appear commented out (the ''#'' sign is a comment in Makefile syntax), so you need to uncomment the line corrsponding to your board. [[Porting]] the kernel to a new board is an advanced topic not covered here, so we'll assume you'll want to use an officially supported board. As an example, in this tutorial we'll use the stm32f746zg_nucleo board:

<source lang="bash">
...
#OPT_BOARD := stm32f469ni_stm32f469i-disco
OPT_BOARD := stm32f746zg_nucleo
#OPT_BOARD := stm32f765ii_marco_ram_board
...
</source>

If you do not yet have a board, you can follow along and get to the compiled firmware anyway. If you're looking for suggestions on which board to get, consider that most boards currently supported by Miosix are for STM32 microcontrollers. Here's a basic guide:
* '''Nucleo''' STM32 boards produced by ST are good for beginners, as they allow to power the board, flash it, debug it and access the serial port all through a single USB connection with your computer. The stm32f401re_nucleo and stm32f411re_nucleo are realtively low cost.
* '''Discovery''' STM32 boards are also good, but they don't include an USB to serial adapter so you'll have to buy it separately and you'll end up having to connect two USB cables, one for power/programming/debugging and one for the serial port.
* '''Third party''' STM32 boards such as the stm32f411ce_blackpill are cheaper and great to embed in your hardware project, but you'll have to [[https://en.wikipedia.org/wiki/Soldering solder]] the pin header yourself, and you'll need to attach a separate USB to serial adapter, and if you want in-circuit debugging you'll need an STLink adapter, so you'll end up having to run up to three separate USB cables from your computer to the board for power/programming, serial port and debugging.
* Venturing outside of STM32, the '''RP2040''' is a good choice. Also in this case, you'll need a separate USB to serial adapter and some soldering skills, though.

= Writing your first Miosix program =

== Hello world ==

With Notepad++ open the ''main.cpp'' file with your [[IDEs | IDE]] or text editor of choice, and replace its content with the following program:
<source lang="CPP">
#include <cstdio>
#include <thread>
#include <miosix.h>
#include <interfaces/bsp.h>

using namespace std;
using namespace miosix;

int main()
{
for(;;)
{
iprintf("Hello world\n");
ledOn();
this_thread::sleep_for(500ms);
ledOff();
this_thread::sleep_for(500ms);
}
}
</source>

At this point, it's good to have a quick walkthrough of this hello world program. Miosix is based on a [[Fluid kernel]] architecture: in a nutshell it's kernel that supports writing applications both inside the kernel, and inside userspace programs. In this tutorial, we're using it as a unikernel. This means when power is applied to the board, the kernel will boot, and then start running the ''main()'' function you just wrote ''in kernelspace''. This means you have both support for C/C++ standard libraries and unrestricted hardware access.

This main() function will print "Hello world" and blink an LED approximately every second.
The printing is done with the ''iprintf()'' function. If you expected just ''printf()'' without the ''i'', the reason is that Miosix uses the [https://sourceware.org/newlib/ Newlib] C standard library that provides both ''printf()'' and ''iprintf()'', an optimized version that is smaller in code size but incapable of printing floating point numbers. So you can also use ''printf()'' if you wish, but this optimization is worth knowing from the start.

Sleeping to blink the LED is done with the [https://en.cppreference.com/cpp/thread/sleep_for sleep_for()] function from the C++ standard library. Miosix supports other sleeping APIs, such as [https://pubs.opengroup.org/onlinepubs/9699919799/functions/nanosleep.html nanosleep()] from POSIX, or ''Thread::sleep()'', a native Miosix function. All these functions do the same thing: they tell the scheduler to stop the currently running thread, run some other thread, and resume execution after a given time interval. Miosix is a preemptive multithreading operating system, so you should get comfortable with the fact that the code you're writing lives in a thread and shared the CPU with other threads.

Many (but not all!) board support packages define the ''ledOn()'' and ''ledOff()'' functions to control one of the LED on the board. This should be true for all the boards that have at least one software-accessible LED. This is true for the ''stm32f746zg_nucleo'' board we selected, but if you selected a different board with no LEDs, then compiling will fail with an error related to ''ledOn()'' and ''ledOff()''. You can comment out those two lines in this case, your hello world will only print to the serial port.

== Compiling ==

In the same terminal you used to run Perl, type ''make'' to build the kernel. If all goes well, the result should look like this.

[[File:Make-output-windows.png]]

Otherwise, compiler errors will appear in the shell. The number that appears under ''text'' in the make output is the size in bytes of your application plus the kernel. Don't worry about the 42KBytes code size, you're compiling with the default Miosix options, if you want you can play around with the options later to [[Miosix code size optimization|reduce the code size]].

== Flashing ==

The procedure to flash the microcontroller board on Windows depends on the vendor-provided flashing tool. They usually provide a GUI where you can load the ''.bin'' file and then connect to the board and flash it. For Miosix the file is named main.bin if you're not using processes, or image.bin if you are using processes. For this tutorial, look for ''main.bin'' in the '''hello''' directory.

If you correctly flashed the board, the LED will start blinking.

== Accessing the serial port ==

The USB to serial port adapter will appear on Windows appears as a randomly numbered COM port. To figure out the right number, you'll have to open ''Devices'' from the control panel:

[[File:Windows-list-devices.png]]

Today, on my computer, Windows decided to assign the STM32 board to COM3.

Next up, open PuTTY and configure it to open the right COM port. Starting from Miosix v3.00, all boards use by default a baud rate of 115200bit/s, so input 115200 in the ''Speed'' field:

[[File:Windows-putty-configuration.png]]

Finally, click ''Open'' and you should see the serial port messages from the microcontroller. Since the board will be already running when you connect, you can press the RESET button on the board to reboot it and see the boot logs:

[[File:Windows-putty-serial.png]]

= A note on uninstalling software =

To uninstall the Miosix Toolchain, you can find the uninstaller in the start menu under ''Miosix Toolchain''. Note that the other tools such as Git, Perl and the STLink utility have their own uninstallers.

[[Category:Installation and Configuration]]

Windows Quick Start

2026-05-10T17:05:03Z

Fede.tft:

= Installing the required software =

== Miosix Toolchain ==

To be able to compile the Miosix kernel and your application, you need a patched version of the GCC compiler called Miosix toolchain, you can find the link to download it [[Miosix Toolchain|here]]. At the end of the installation you will need to reboot your computer (sorry, it's Windows...)

== Git ==

To download the Miosix kernel and keep it up to date, you need the [https://en.wikipedia.org/wiki/Git_%28software%29 git] version control system.

It is recommended to install it from [http://www.git-scm.com/download/win git-scm.com]. Please '''do not''' uncheck the ''Windows Explorer integration'' feature during the installation, as you will need it to install the kernel sources.

== Perl ==

The [https://en.wikipedia.org/wiki/Perl Perl] programming language is used by the Miosix build system. Unlike on GNU/Linux computers where Perl is pre-installed, for Windows you'll need to install it separately.

[http://strawberryperl.com Strawberry perl] is the recomended Perl version for Miosix on Windows.

== Flashing tool ==

With the installed Miosix toolchain you'll be able to compile the kernel, but you'll also need a way to transfer it to your microcontroller. This operation is usually called 'flashing' the microcontroller. Miosix can work with any flashing utility that accepts as input raw binary files, and on Windows you'll usually want to install the flashing tool provided by your chip vendor.

For STM32 chips, you can use the STLink utility available [http://www.st.com/web/en/catalog/tools/PF258168# here].

== Text editor or IDE ==

It is recommended to download a better text editor than Notepad, as you will need it to edit the Miosix configuration files. [http://www.notepad-plus-plus.org/ Notepad++] is a good option, but many other options exist. Just '''don't use Notepad''', because it does not recognize Unix [https://en.wikipedia.org/wiki/Line_ending line-endings] and will show you Miosix source files as if they were composed of a single line of text.

As an alternative to Notepad++, you may want to use an [[IDEs|IDE]].

== Serial port viewer ==

Miosix redirects ''stdin''/''stdout'' to a serial port by default on most boards, so to see the boot log and the output of ''printf()'' in your application you need a program to interact with the serial port. [https://putty.org/index.html PuTTY] is an option, although old fashioned. TODO: There are likely better options for Windows too.

= Downloading and configuring the Miosix kernel =

This section is a stripped down guide with the bare minimum to get you started, we also have a full guide about [[Miosix and git workflow]]. Following the tutorial in this page, your project directory will '''not''' be under version control (git). The [[Miosix and git workflow]] page shows how to create a git repository for your project and add the Miosix kernel as a git submodule.

Before downloading the kernel, however, you first have to create '''a directory for your project''' (in this case, the hello world), and then clone the kernel '''as a subdirectory'''.

Using the Windows explorer, create a '''hello''' directory, double click on it. Then right-click on the empty directory. Select ''Git bash'' to open a git shell. This opens a shell where you can type the commands to download the kernel.

[[File:Git-bash-windows.png]]

Note that it is possible to paste commands in the shell (so as to avoid typing them, which can be tedious and lead to typos), but you have to do it one line of text at a time, and to paste you need to use the ''Shift+Ins'' shortcut, not the usual ''Ctrl+V'' one. The last command, ''exit'', will close the shell.

<source lang="bash">
git clone https://github.com/fedetft/miosix-kernel.git
exit
</source>

Note that there is also a ''Git GUI'' in the right click menu, but git is best used from a command line interface, you're on your own if you choose to use git from the GUI.

== Initializing a Miosix project ==

For reasons explained in depth in the [[Miosix and git workflow]] page, you'll need to copy the Miosix configuration directory from the kernel sources to your project directory, as well as create a template project where you can start writing code.
This can be automated with a [https://en.wikipedia.org/wiki/Perl Perl] script called ''init_project_out_of_git_tree.pl''. To run it, you need to open a Windows terminal (which is a '''different''' terminal than the git bash we used before), which can be done by ''Shift+Right click'' and selecting ''Open command window here'':

[[File:Open-terminal-windows.png]]

Then, type the following command:

<source lang="bash">
perl miosix-kernel/tools/init_project_out_of_git_tree.pl
</source>

Leave the terminal open as you'll need it later.

You should run the script from the directory where you want to initialize your empty project, such as the '''hello''' directory in this tutorial. A successful run of the script produces the following output:

<source lang="bash">
Successfully created Miosix project
Target directory: hello
Kernel directory: hello/miosix-kernel/miosix
</source>

Your project directory should now look like the following picture, with the ''miosix-kernel'' directory containing the kernel sources, the ''config'' directory with the kernel configuration, the empty ''main.cpp'' and the build files for the two alternative build systems supported by Miosix: Makefile and CMake:

[[File:Initialized-miosix-project-windows.png]]

For this tutorial, we'll use the Makefile build system, have a look at the [[CMake]] page to learn how to use CMake instead.

== Configuring the kernel ==

The minimum configuration required to compile the kernel is to '''select a board''', as the kernel needs to build the appropriate board support package for it.

The Miosix kernel has several other build-time configuration options, to enable optional components (filesystem, userspace processes), select algorithms such as the scheduler and trade feature support for code size, but these won't be covered here.
The kernel is configured by editing files in the config directory, the two most important ones are [https://github.com/fedetft/miosix-kernel/blob/master/miosix/config/Makefile.inc Makefile.inc] and [https://github.com/fedetft/miosix-kernel/blob/master/miosix/config/miosix_settings.h miosix_settings.h].

To select a board, using Notepad++ open the first one, ''config/Makefile.inc''. Look for the ''OPT_BOARD'' section of the file, which contains the list of boards officially supported by the kernel. In this section, all boards appear commented out (the ''#'' sign is a comment in Makefile syntax), so you need to uncomment the line corrsponding to your board. [[Porting]] the kernel to a new board is an advanced topic not covered here, so we'll assume you'll want to use an officially supported board. As an example, in this tutorial we'll use the stm32f746zg_nucleo board:

<source lang="bash">
...
#OPT_BOARD := stm32f469ni_stm32f469i-disco
OPT_BOARD := stm32f746zg_nucleo
#OPT_BOARD := stm32f765ii_marco_ram_board
...
</source>

If you do not yet have a board, you can follow along and get to the compiled firmware anyway. If you're looking for suggestions on which board to get, consider that most boards currently supported by Miosix are for STM32 microcontrollers. Here's a basic guide:
* '''Nucleo''' STM32 boards produced by ST are good for beginners, as they allow to power the board, flash it, debug it and access the serial port all through a single USB connection with your computer. The stm32f401re_nucleo and stm32f411re_nucleo are realtively low cost.
* '''Discovery''' STM32 boards are also good, but they don't include an USB to serial adapter so you'll have to buy it separately and you'll end up having to connect two USB cables, one for power/programming/debugging and one for the serial port.
* '''Third party''' STM32 boards such as the stm32f411ce_blackpill are cheaper and great to embed in your hardware project, but you'll have to [[https://en.wikipedia.org/wiki/Soldering solder]] the pin header yourself, and you'll need to attach a separate USB to serial adapter, and if you want in-circuit debugging you'll need an STLink adapter, so you'll end up having to run up to three separate USB cables from your computer to the board for power/programming, serial port and debugging.
* Venturing outside of STM32, the '''RP2040''' is a good choice. Also in this case, you'll need a separate USB to serial adapter and some soldering skills, though.

= Writing your first Miosix program =

== Hello world ==

With Notepad++ open the ''main.cpp'' file with your [[IDEs | IDE]] or text editor of choice, and replace its content with the following program:
<source lang="CPP">
#include <cstdio>
#include <thread>
#include <miosix.h>
#include <interfaces/bsp.h>

using namespace std;
using namespace miosix;

int main()
{
for(;;)
{
iprintf("Hello world\n");
ledOn();
this_thread::sleep_for(500ms);
ledOff();
this_thread::sleep_for(500ms);
}
}
</source>

At this point, it's good to have a quick walkthrough of this hello world program. Miosix is based on a [[Fluid kernel]] architecture: in a nutshell it's kernel that supports writing applications both inside the kernel, and inside userspace programs. In this tutorial, we're using it as a unikernel. This means when power is applied to the board, the kernel will boot, and then start running the ''main()'' function you just wrote ''in kernelspace''. This means you have both support for C/C++ standard libraries and unrestricted hardware access.

This main() function will print "Hello world" and blink an LED approximately every second.
The printing is done with the ''iprintf()'' function. If you expected just ''printf()'' without the ''i'', the reason is that Miosix uses the [https://sourceware.org/newlib/ Newlib] C standard library that provides both ''printf()'' and ''iprintf()'', an optimized version that is smaller in code size but incapable of printing floating point numbers. So you can also use ''printf()'' if you wish, but this optimization is worth knowing from the start.

Sleeping to blink the LED is done with the [https://en.cppreference.com/cpp/thread/sleep_for sleep_for()] function from the C++ standard library. Miosix supports other sleeping APIs, such as [https://pubs.opengroup.org/onlinepubs/9699919799/functions/nanosleep.html nanosleep()] from POSIX, or ''Thread::sleep()'', a native Miosix function. All these functions do the same thing: they tell the scheduler to stop the currently running thread, run some other thread, and resume execution after a given time interval. Miosix is a preemptive multithreading operating system, so you should get comfortable with the fact that the code you're writing lives in a thread and shared the CPU with other threads.

Many (but not all!) board support packages define the ''ledOn()'' and ''ledOff()'' functions to control one of the LED on the board. This should be true for all the boards that have at least one software-accessible LED. This is true for the ''stm32f746zg_nucleo'' board we selected, but if you selected a different board with no LEDs, then compiling will fail with an error related to ''ledOn()'' and ''ledOff()''. You can comment out those two lines in this case, your hello world will only print to the serial port.

== Compiling ==

In the same terminal you used to run Perl, type ''make'' to build the kernel. If all goes well, the result should look like this.

[[File:Make-output-windows.png]]

Otherwise, compiler errors will appear in the shell. The number that appears under ''text'' in the make output is the size in bytes of your application plus the kernel. Don't worry about the 42KBytes code size, you're compiling with the default Miosix options, if you want you can play around with the options later to [[Miosix code size optimization|reduce the code size]].

== Flashing ==

The procedure to flash the microcontroller board on Windows depends on the vendor-provided flashing tool. The usually provide a GUI where you can load the ''.bin'' file and then connect to the board and flash it. For Miosix the file is named main.bin if you're not using processes, or image.bin if you are using processes. For this tutorial, look for ''main.bin'' in the '''hello''' directory.

If you correctly flashed the board, the LED will start blinking.

== Accessing the serial port ==

The USB to serial port adapter will appear on Windows appears as a randomly numbered COM port. To figure out the right number, you'll have to open ''Devices'' from the control panel:

[[File:Windows-list-devices.png]]

Today, on my computer, Windows decided to assign the STM32 board to COM3.

Next up, open PuTTY and configure it to open the right COM port. Starting from Miosix v3.00, all boards use by default a baud rate of 115200bit/s, so input 115200 in the ''Speed'' field:

[[File:Windows-putty-configuration.png]]

Finally, click ''Open'' and you should see the serial port messages from the microcontroller. Since the board will be already running when you connect, you can press the RESET button on the board to reboot it and see the boot logs:

[[File:Windows-putty-serial.png]]

= A note on uninstalling software =

To uninstall the Miosix Toolchain, you can find the uninstaller in the start menu under ''Miosix Toolchain''. Note that the other tools such as Git, Perl and the STLink utility have their own uninstallers.

[[Category:Installation and Configuration]]

File:Windows-putty-serial.png

2026-05-10T17:04:49Z

Fede.tft:

Windows-putty-serial

File:Windows-putty-configuration.png

2026-05-10T17:03:09Z

Fede.tft:

Windows-putty-configuration

File:Windows-list-devices.png

2026-05-10T17:01:00Z

Fede.tft:

Windows-list-devices

Windows Quick Start

2026-05-10T16:54:57Z

Fede.tft:

= Installing the required software =

== Miosix Toolchain ==

To be able to compile the Miosix kernel and your application, you need a patched version of the GCC compiler called Miosix toolchain, you can find the link to download it [[Miosix Toolchain|here]]. At the end of the installation you will need to reboot your computer (sorry, it's Windows...)

== Git ==

To download the Miosix kernel and keep it up to date, you need the [https://en.wikipedia.org/wiki/Git_%28software%29 git] version control system.

It is recommended to install it from [http://www.git-scm.com/download/win git-scm.com]. Please '''do not''' uncheck the ''Windows Explorer integration'' feature during the installation, as you will need it to install the kernel sources.

== Perl ==

The [https://en.wikipedia.org/wiki/Perl Perl] programming language is used by the Miosix build system. Unlike on GNU/Linux computers where Perl is pre-installed, for Windows you'll need to install it separately.

[http://strawberryperl.com Strawberry perl] is the recomended Perl version for Miosix on Windows.

== Flashing tool ==

With the installed Miosix toolchain you'll be able to compile the kernel, but you'll also need a way to transfer it to your microcontroller. This operation is usually called 'flashing' the microcontroller. Miosix can work with any flashing utility that accepts as input raw binary files, and on Windows you'll usually want to install the flashing tool provided by your chip vendor.

For STM32 chips, you can use the STLink utility available [http://www.st.com/web/en/catalog/tools/PF258168# here].

== Text editor or IDE ==

It is recommended to download a better text editor than Notepad, as you will need it to edit the Miosix configuration files. [http://www.notepad-plus-plus.org/ Notepad++] is a good option, but many other options exist. Just '''don't use Notepad''', because it does not recognize Unix [https://en.wikipedia.org/wiki/Line_ending line-endings] and will show you Miosix source files as if they were composed of a single line of text.

As an alternative to Notepad++, you may want to use an [[IDEs|IDE]].

== Serial port viewer ==

Miosix redirects ''stdin''/''stdout'' to a serial port by default on most boards, so to see the boot log and the output of ''printf()'' in your application you need a program to interact with the serial port. [https://putty.org/index.html PuTTY] is an option, although old fashioned. TODO: There are likely better options for Windows too.

= Downloading and configuring the Miosix kernel =

This section is a stripped down guide with the bare minimum to get you started, we also have a full guide about [[Miosix and git workflow]]. Following the tutorial in this page, your project directory will '''not''' be under version control (git). The [[Miosix and git workflow]] page shows how to create a git repository for your project and add the Miosix kernel as a git submodule.

Before downloading the kernel, however, you first have to create '''a directory for your project''' (in this case, the hello world), and then clone the kernel '''as a subdirectory'''.

Using the Windows explorer, create a '''hello''' directory, double click on it. Then right-click on the empty directory. Select ''Git bash'' to open a git shell. This opens a shell where you can type the commands to download the kernel.

[[File:Git-bash-windows.png]]

Note that it is possible to paste commands in the shell (so as to avoid typing them, which can be tedious and lead to typos), but you have to do it one line of text at a time, and to paste you need to use the ''Shift+Ins'' shortcut, not the usual ''Ctrl+V'' one. The last command, ''exit'', will close the shell.

<source lang="bash">
git clone https://github.com/fedetft/miosix-kernel.git
exit
</source>

Note that there is also a ''Git GUI'' in the right click menu, but git is best used from a command line interface, you're on your own if you choose to use git from the GUI.

== Initializing a Miosix project ==

For reasons explained in depth in the [[Miosix and git workflow]] page, you'll need to copy the Miosix configuration directory from the kernel sources to your project directory, as well as create a template project where you can start writing code.
This can be automated with a [https://en.wikipedia.org/wiki/Perl Perl] script called ''init_project_out_of_git_tree.pl''. To run it, you need to open a Windows terminal (which is a '''different''' terminal than the git bash we used before), which can be done by ''Shift+Right click'' and selecting ''Open command window here'':

[[File:Open-terminal-windows.png]]

Then, type the following command:

<source lang="bash">
perl miosix-kernel/tools/init_project_out_of_git_tree.pl
</source>

Leave the terminal open as you'll need it later.

You should run the script from the directory where you want to initialize your empty project, such as the '''hello''' directory in this tutorial. A successful run of the script produces the following output:

<source lang="bash">
Successfully created Miosix project
Target directory: hello
Kernel directory: hello/miosix-kernel/miosix
</source>

Your project directory should now look like the following picture, with the ''miosix-kernel'' directory containing the kernel sources, the ''config'' directory with the kernel configuration, the empty ''main.cpp'' and the build files for the two alternative build systems supported by Miosix: Makefile and CMake:

[[File:Initialized-miosix-project-windows.png]]

For this tutorial, we'll use the Makefile build system, have a look at the [[CMake]] page to learn how to use CMake instead.

== Configuring the kernel ==

The minimum configuration required to compile the kernel is to '''select a board''', as the kernel needs to build the appropriate board support package for it.

The Miosix kernel has several other build-time configuration options, to enable optional components (filesystem, userspace processes), select algorithms such as the scheduler and trade feature support for code size, but these won't be covered here.
The kernel is configured by editing files in the config directory, the two most important ones are [https://github.com/fedetft/miosix-kernel/blob/master/miosix/config/Makefile.inc Makefile.inc] and [https://github.com/fedetft/miosix-kernel/blob/master/miosix/config/miosix_settings.h miosix_settings.h].

To select a board, using Notepad++ open the first one, ''config/Makefile.inc''. Look for the ''OPT_BOARD'' section of the file, which contains the list of boards officially supported by the kernel. In this section, all boards appear commented out (the ''#'' sign is a comment in Makefile syntax), so you need to uncomment the line corrsponding to your board. [[Porting]] the kernel to a new board is an advanced topic not covered here, so we'll assume you'll want to use an officially supported board. As an example, in this tutorial we'll use the stm32f746zg_nucleo board:

<source lang="bash">
...
#OPT_BOARD := stm32f469ni_stm32f469i-disco
OPT_BOARD := stm32f746zg_nucleo
#OPT_BOARD := stm32f765ii_marco_ram_board
...
</source>

If you do not yet have a board, you can follow along and get to the compiled firmware anyway. If you're looking for suggestions on which board to get, consider that most boards currently supported by Miosix are for STM32 microcontrollers. Here's a basic guide:
* '''Nucleo''' STM32 boards produced by ST are good for beginners, as they allow to power the board, flash it, debug it and access the serial port all through a single USB connection with your computer. The stm32f401re_nucleo and stm32f411re_nucleo are realtively low cost.
* '''Discovery''' STM32 boards are also good, but they don't include an USB to serial adapter so you'll have to buy it separately and you'll end up having to connect two USB cables, one for power/programming/debugging and one for the serial port.
* '''Third party''' STM32 boards such as the stm32f411ce_blackpill are cheaper and great to embed in your hardware project, but you'll have to [[https://en.wikipedia.org/wiki/Soldering solder]] the pin header yourself, and you'll need to attach a separate USB to serial adapter, and if you want in-circuit debugging you'll need an STLink adapter, so you'll end up having to run up to three separate USB cables from your computer to the board for power/programming, serial port and debugging.
* Venturing outside of STM32, the '''RP2040''' is a good choice. Also in this case, you'll need a separate USB to serial adapter and some soldering skills, though.

= Writing your first Miosix program =

== Hello world ==

With Notepad++ open the ''main.cpp'' file with your [[IDEs | IDE]] or text editor of choice, and replace its content with the following program:
<source lang="CPP">
#include <cstdio>
#include <thread>
#include <miosix.h>
#include <interfaces/bsp.h>

using namespace std;
using namespace miosix;

int main()
{
for(;;)
{
iprintf("Hello world\n");
ledOn();
this_thread::sleep_for(500ms);
ledOff();
this_thread::sleep_for(500ms);
}
}
</source>

At this point, it's good to have a quick walkthrough of this hello world program. Miosix is based on a [[Fluid kernel]] architecture: in a nutshell it's kernel that supports writing applications both inside the kernel, and inside userspace programs. In this tutorial, we're using it as a unikernel. This means when power is applied to the board, the kernel will boot, and then start running the ''main()'' function you just wrote ''in kernelspace''. This means you have both support for C/C++ standard libraries and unrestricted hardware access.

This main() function will print "Hello world" and blink an LED approximately every second.
The printing is done with the ''iprintf()'' function. If you expected just ''printf()'' without the ''i'', the reason is that Miosix uses the [https://sourceware.org/newlib/ Newlib] C standard library that provides both ''printf()'' and ''iprintf()'', an optimized version that is smaller in code size but incapable of printing floating point numbers. So you can also use ''printf()'' if you wish, but this optimization is worth knowing from the start.

Sleeping to blink the LED is done with the [https://en.cppreference.com/cpp/thread/sleep_for sleep_for()] function from the C++ standard library. Miosix supports other sleeping APIs, such as [https://pubs.opengroup.org/onlinepubs/9699919799/functions/nanosleep.html nanosleep()] from POSIX, or ''Thread::sleep()'', a native Miosix function. All these functions do the same thing: they tell the scheduler to stop the currently running thread, run some other thread, and resume execution after a given time interval. Miosix is a preemptive multithreading operating system, so you should get comfortable with the fact that the code you're writing lives in a thread and shared the CPU with other threads.

Many (but not all!) board support packages define the ''ledOn()'' and ''ledOff()'' functions to control one of the LED on the board. This should be true for all the boards that have at least one software-accessible LED. This is true for the ''stm32f746zg_nucleo'' board we selected, but if you selected a different board with no LEDs, then compiling will fail with an error related to ''ledOn()'' and ''ledOff()''. You can comment out those two lines in this case, your hello world will only print to the serial port.

== Compiling ==

In the same terminal you used to run Perl, type ''make'' to build the kernel. If all goes well, the result should look like this.

[[File:Make-output-windows.png]]

Otherwise, compiler errors will appear in the shell. The number that appears under ''text'' in the make output is the size in bytes of your application plus the kernel. Don't worry about the 42KBytes code size, you're compiling with the default Miosix options, if you want you can play around with the options later to [[Miosix code size optimization|reduce the code size]].

== Flashing ==

There are two ways to program the stm32f4discovery board. One is to use QSTLink2 directly from the terminal you already have open by typing 'make program' (connect the USB cable first!), the other is through QSTLink2's GUI. You can find QSTLink2 in the start menu

[[File:Qstlink2startmenuwindows.png]]

Once you start it, you have to click on ''Connect'', and it should find your ''stm32f4discovery'' board. After that, click on ''Send'' and select the ''main.bin'' file in the Miosix top-level directory.

[[File:Qstlink2flashingwindows.png]]

Note that, regardless of using QSTLink2 form the terminal or the GUI, there is a bug that in some circumstances blocks the microcontroller until the next powercycle. Therefore, after having programmed the microcontroller, it is recomended to unplug and reconnect the USB cable to powercycle the ''stm32f4discovery'' board. At that point, you shuold see the red LED blinking.

= A note on uninstalling software =

To uninstall the Miosix Toolchain, you can find the uninstaller in the start menu under ''Miosix Toolchain''. Note that the other tools such as Git, Perl and the STLink utility have their own uninstallers.

[[Category:Installation and Configuration]]