Miosix Wiki - User contributions [en]

Adding support for a new STM32 board in Miosix

2026-04-09T17:04:58Z

Daniele.cattaneo: Outline what is yet to be written

Miosix's main target platform is, naturally, STM32 microcontrollers by ST Microelectronics, in part for historical reasons, but mainly because STM32 chips (and their clones) are extremely popular for both the industry and hobbyists.

However, the success of the STM32 line has spawned an abundance of different chips, all with different sets of built-in peripherals, Flash sizes, Ram sizes, CPU cores, and so on. Fortunately, most STM32 chips are similar enough that it is usually easy to port a new STM32 board to Miosix.

== Components of a Miosix port ==

The core of the Miosix kernel is platform-independent. The contact point between the platform-independent part of Miosix and the platform-dependent parts consist in a set of '''interfaces''' that need to be fully implemented for a board to function.

The header files that define these interfaces are in the miosix/interfaces and miosix/interfaces_private directories. The implementations are in the arch directory, split by board, chip and cpu.

The Miosix build system makes sure that the correct board/chip/cpu-specific header files and source code files for the selected board are used during the compilation.

A port of Miosix to a new board needs to provide the files required for the missing interfaces implementations.

=== Miosix interfaces ===

Miosix's interfaces are usually implemented either at CPU level, at chip level, or board level, depending on the case.

{| class="wikitable sortable"
|+ Caption text
|-
! Header !! Typical Implementation !! Private !! Description
|-
| interfaces/arch_registers.h || arch/board/<board_name>/interfaces-impl/arch_registers_impl.h || No || Register definitions for the chip.
|-
| interfaces/atomic_ops.h || arch/cpu/<cpu_name>/interfaces-impl/atomics_ops_impl.h || No || Implementation of atomic primitives
|-
| interfaces/bsp.h, interfaces_private/bsp_private.h || arch/board/<board_name>/interfaces-impl/{bsp_impl.h,bsp.cpp} || In part || Board Support Package: configuration of the board at boot, board reboot and shutdown
|-
| interfaces/cpu_const.h || arch/cpu/<cpu_name>/interfaces-impl/cpu_const_[smp_]impl.h || No || Low-level CPU architecture parameters, such as the number of CPU cores, configurables regarding the behavior during context switches, and so on. (SMP file only for SMP platforms)
|-
| interfaces/delays.h || arch/chip/<chip_name>/interfaces-impl/delays.cpp || No || Low-level delays implemented by CPU spinning (no timers allowed, used early at boot)
|-
| interfaces/endianness.h || arch/cpu/<cpu_name>/interfaces-impl/endianness_impl.h || No || Optimized implementation of byte-swapping primitives, for big endian support
|-
| interfaces/gpio.h || arch/chip/<chip_name>/interfaces-impl/gpio_impl.h || No || Gpio class implementation for this chip. Usually just includes one of the Gpio drivers in arch/drivers/gpio.
|-
| interfaces/interrupts.h || arch/cpu/<cpu_name>/interfaces-impl/interrupts_impl.h || No || Implementation of primitives for enabling or disabling interrupts, and for registering IRQ vectors.
|-
| interfaces/poweroff.h || arch/chip/<chip_name>/interfaces-impl/poweroff.cpp || No || Chip reboot and shutdown
|-
| interfaces_private/cpu.h || arch/cpu/<cpu_name>/interfaces-impl/{cpu_impl.h,cpu.cpp} || Yes || Context switching primitives
|-
| interfaces_private/os_timer.h || arch/drivers/os_timer/... || Yes || Timer driver for context switches and general kernel timekeeping
|-
| interfaces_private/sleep.h || arch/drivers/sleep/... || Yes || CPU sleep and deep sleep (deep sleep is implemented in arch/chip or arch/board)
|-
| interfaces_private/smp_locks.h || arch/chip/<chip_name>/interfaces-impl/smp_locks_impl.h || Yes || Implementation of spinlocks (SMP platforms only)
|-
| interfaces_private/smp.h || arch/chip/<chip_name>/interfaces-impl/smp.cpp || Yes || Initialization of other CPU cores and SMP primitives (SMP platforms only)
|-
| interfaces_private/userspace.h || arch/cpu/<cpu_name>/interfaces-impl/userspace_impl.h || Yes || Implementation of memory protection primitives
|}

TODO:
* what to copy past and from where, new chip vs old chip vs new chip that is similar to old
* makefiles/cmake
For new chips:
* clock configuration code & PLL
* os_timer
* gpio (sometimes)
* serial port configuration
For new boards:
* BSP init
* arch_registers (to be moved!!!)
extras:
* sdmmc

Adding support for a new STM32 board in Miosix

2026-04-09T16:58:35Z

Daniele.cattaneo: Start writing a porting guide

User:Daniele.cattaneo

2026-04-09T15:54:37Z

Daniele.cattaneo:

Hi :)

Github (work): [https://github.com/danielecattaneo]

Github (personal): Secret

MInimal Operating System with posIX

[[Miosix in emulation]]

[[arch directory restructuring]]

[[Miosix 3]]

[[Multicore]]

[[mxgui qtsimulator on windows]]

[[Adding support for a new STM32 board in Miosix]]

Linux Debugger configuration

2026-04-08T09:22:11Z

Daniele.cattaneo: Use extended-remote

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-get install openocd # Install OpenOCD for Ubuntu/Debian
</source>

=== Run OpenOCD ===
The OpenOCD configuration is included in the official Miosix distribution under the path 'miosix/arch'. You must choose the proper config file for the device in use. For example for the stm32f429zi_stm32f4discovery board:
<source lang="bash">
openocd -f miosix/arch/cortexM4_stm32f4/stm32f429zi_stm32f4discovery/stm32f4discovery.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]]. If you haven't already installed it's time to do it. The debugger must be launched on the ELF binary file.
<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>

=== 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]]

Linux Debugger configuration

2026-04-08T09:12:07Z

Daniele.cattaneo: Fix openocd link

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-get install openocd # Install OpenOCD for Ubuntu/Debian
</source>

=== Run OpenOCD ===
The OpenOCD configuration is included in the official Miosix distribution under the path 'miosix/arch'. You must choose the proper config file for the device in use. For example for the stm32f429zi_stm32f4discovery board:
<source lang="bash">
openocd -f miosix/arch/cortexM4_stm32f4/stm32f429zi_stm32f4discovery/stm32f4discovery.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]]. If you haven't already installed it's time to do it. The debugger must be launched on the ELF binary file.
<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 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>

=== 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]]

User:Daniele.cattaneo

2026-04-07T11:15:58Z

Daniele.cattaneo:

User:Daniele.cattaneo

2026-04-01T15:12:04Z

Daniele.cattaneo:

Hi :)

Github (work): [https://github.com/danielecattaneo]

Github (personal): Secret

[[Miosix in emulation]]

[[arch directory restructuring]]

[[Miosix 3]]

[[Multicore]]

[[mxgui qtsimulator on windows]]

[[Adding support for a board in Miosix]]

Mxgui qtsimulator on windows

2026-04-01T15:11:37Z

Daniele.cattaneo:

On windows, an easy way to compile the mxgui qtsimulator is to use the MSYS2 toolchain, which provides a Unix-like environment for Windows development.

== 1. Install MSYS2 ==
Download the MSYS 2 toolchain by downloading the prebuilt packages from the official site https://www.msys2.org. Then, follow the instructions on the website to install it.

=== Different toolchains in MSYS2 ===

MSYS2 itself is just a unix-like environment running on Windows, like its predecessor Cygwin. Within this environment, MSYS2 provides multiple toolchains which target different architectures (x86_64 or ARM), use different main compilers (GCC or clang), or a different C runtime library (UCRT or mingw).

The recommended toolchain by the MSYS2 project at the current time is '''UCRT64''', which targets x86_64, uses the GCC compiler and the UCRT runtime. [https://learn.microsoft.com/en-us/cpp/windows/universal-crt-deployment?view=msvc-170 UCRT] is a modern C runtime for Windows, included with the OS since Windows 10, which removes the need to install the C runtime separately when distributing a program (as previously required).

<div style="margin: 0 0; background: #e0f7e0; padding: 0 10px; border: 1px solid #c0d0c0">
'''Trivia''': Before UCRT was introduced, the previous standard C runtime for MSYS2 was mingw. However, mingw was simply a wrapper augmenting an old Microsoft C runtime (''msvcrt.dll'') which for binary compatibility reasons is frozen in time since the release of Windows 95<ref>https://devblogs.microsoft.com/oldnewthing/20140411-00/?p=1273</ref>. As a result, mingw always had serious compatibility problems and bugs.
</div>

MSYS2 adds menu items to the Start menu which launch bash shells with pre-configured paths ('''environments''') for each one of the toolchains.

<div style="clear: both">
[[File:Msys2 toolchains.png|frame|center]]
</div>

All of the following steps are intended to be executed using the shell opened by clicking on '''MSYS2 UCRT64'''.

== 2. Install build tools and prerequisites ==

Open the '''MSYS2 UCRT64''' shell and perform an upgrade:
<pre>
pacman -Syuu
</pre>
Answer Yes to all prompts. If a "base system upgrade" was needed, at this point the shell will close. In this case, just open it up again.

Install the toolchain (including gcc and binutils):
<div style="margin: 0 0; background: #f7f7e0; padding: 0 10px; border: 1px solid #d0d0c0">
'''Note''': The ''mingw-w64-ucrt-x86_64'' prefix in the package name identifies the toolchain and ''usually'' needs to be specified for all packages. Some packages that work the same way for all toolchains are exceptions to this rule.
</div>
<pre>
pacman -S mingw-w64-ucrt-x86_64-toolchain
</pre>

Install build automation tools (note that only CMake has a special version depending on the toolchain here):
<pre>
pacman -S make difftools mingw-w64-ucrt-x86_64-cmake
</pre>

Install the dependencies for the simulator and the code generation tools:
<div style="margin: 0 0; background: #f7f7e0; padding: 0 10px; border: 1px solid #d0d0c0">
'''Note''': When installing qt5 type enter to install all packages.
</div>
<pre>
pacman -S mingw-w64-ucrt-x86_64-qt5 mingw-w64-ucrt-x86_64-libpng mingw-w64-ucrt-x86_64-zlib mingw-w64-ucrt-x86_64-boost
</pre>

== 3. Build the code generation tools ==

Let us assume you already cloned mxgui's repository somewhere on your filesystem. If you haven't, do it now.

<div style="margin: 0 0; background: #e0f7e0; padding: 0 10px; border: 1px solid #c0d0c0">
'''Tip''': For using git on Windows, we recommend the official distribution (Git for Windows: https://git-scm.com/install/windows) and TortoiseGit for shell integration and GUI support (https://tortoisegit.org).

You can also install git inside MSYS2 by executing <code>pacman -S git</code>. However, this installs a different and separate version of Git, which exists simultaneously and independently from Git for Windows. By default you can't use Git for Windows inside a MSYS2 shell, or MSYS2-installed git in a Windows shell.
</div>

Then, change directory to the mxgui repository's root.

<div style="margin: 0 0; background: #e0f7e0; padding: 0 10px; border: 1px solid #c0d0c0">
'''Tip''': Instead of typing the path manually, you can drag the directory on the terminal window to insert the path automatically.
</div>
<div style="margin: 0 0; background: #f7e0e0; padding: 0 10px; border: 1px solid #d0c0c0">
'''Warning''': MSYS2 natively accepts only Unix-style paths with forward-slashes. Windows style paths with backslashes usually don't work.
</div>

<pre>
cd /c/Users/me/Documents/mxgui
</pre>

Change directory to <code>_tools/code_generators</code>:
<pre>
cd _tools/code_generators
</pre>

Build the code generators with CMake.
<pre>
mkdir build
cd build
cmake ..
make
</pre>
<div style="margin: 0 0; background: #f7f7e0; padding: 0 10px; border: 1px solid #d0d0c0">
'''Note''': If you want to make the compilation faster by using all the CPU cores in your machine, instead of just typing <code>make</code> type <code>make -j4</code> where 4 stands for the number of CPU cores you have.

Of course you can do this any time you use make to compile something, not just for this one case.

If you don't know how many cores your CPU has, check in Task Manager.
</div>

== 4. Build the simulator ==

Now we only need to build the simulator. Change directory to the simulator's root:
<pre>
cd ../../qtsimulator
</pre>

Then build it like we did for the code generators:
<pre>
mkdir build
cd build
cmake ..
make
</pre>

Now you should be able to run the simulator!
<pre>
./qtsimulator.exe
</pre>

<div style="clear: both">
[[File:Mxgui simulator on Windows 11.png|frame|center]]
</div>

<div style="margin: 0 0; background: #f7e0e0; padding: 0 10px; border: 1px solid #d0c0c0">
'''Warning''': If you double-click on the <code>qtsimulator.exe</code> executable in Windows Explorer, it probably won't work because of some missing DLLs. This is normal. The missing DLLs are located in <code>C:\msys64\ucrt64\bin</code>, a directory that the MSYS2 shell configuration adds to the PATH variable automatically, but is not normally included in PATH.

To make the simulator executable work when double-clicked, first check all the required DLLs by executing <code>lld qtsimulator.exe</code> in the MSYS2 shell, and then copy the DLLs located in <code>C:\msys64\ucrt64\bin</code> to the same directory as <code>qtsimulator.exe</code>.

However, unless you want to distribute the compiled simulator, it's much simpler to just always run it from inside an MSYS2 UCRT64 terminal window.
</div>

== References ==

Mxgui qtsimulator on windows

2026-03-26T18:22:02Z

Daniele.cattaneo: Page created

On windows, an easy way to compile the mxgui qtsimulator is to use the MSYS2 toolchain, which provides a Unix-like environment for Windows development.

== 1. Install MSYS2 ==
Download the MSYS 2 toolchain by downloading the prebuilt packages from the official site https://www.msys2.org. Then, follow the instructions on the website to install it.

=== Different toolchains in MSYS2 ===

MSYS2 itself is just a unix-like environment running on Windows, like its predecessor Cygwin. Within this environment, MSYS2 provides multiple toolchains which target different architectures (x86_64 or ARM), use different main compilers (GCC or clang), or a different C runtime library (UCRT or mingw).

The recommended toolchain by the MSYS2 project at the current time is '''UCRT64''', which targets x86_64, uses the GCC compiler and the UCRT runtime. [https://learn.microsoft.com/en-us/cpp/windows/universal-crt-deployment?view=msvc-170 UCRT] is a modern C runtime for Windows, included with the OS since Windows 10, which removes the need to install the C runtime separately when distributing a program (as previously required).

<div style="margin: 0 0; background: #e0f7e0; padding: 0 10px; border: 1px solid #c0d0c0">
'''Trivia''': Before UCRT was introduced, the previous standard C runtime for MSYS2 was mingw. However, mingw was simply a wrapper augmenting an old Microsoft C runtime (''msvcrt.dll'') which for binary compatibility reasons is frozen in time since the release of Windows 95<ref>https://devblogs.microsoft.com/oldnewthing/20140411-00/?p=1273</ref>. As a result, mingw always had serious compatibility problems and bugs.
</div>

MSYS2 adds menu items to the Start menu which launch bash shells with pre-configured paths ('''environments''') for each one of the toolchains.

<div style="clear: both">
[[File:Msys2 toolchains.png|frame|center]]
</div>

All of the following steps are intended to be executed using the shell opened by clicking on '''MSYS2 UCRT64'''.

== 2. Install build tools and prerequisites ==

Open the '''MSYS2 UCRT64''' shell and perform an upgrade:
<pre>
pacman -Syuu
</pre>
Answer Yes to all prompts. If a "base system upgrade" was needed, at this point the shell will close. In this case, just open it up again.

Install the toolchain (including gcc and binutils):
<div style="margin: 0 0; background: #f7f7e0; padding: 0 10px; border: 1px solid #d0d0c0">
'''Note''': The ''mingw-w64-ucrt-x86_64'' prefix in the package name identifies the toolchain and ''usually'' needs to be specified for all packages. Some packages that work the same way for all toolchains are exceptions to this rule.
</div>
<pre>
pacman -S mingw-w64-ucrt-x86_64-toolchain
</pre>

Install build automation tools (note that only CMake has a special version depending on the toolchain here):
<pre>
pacman -S make difftools mingw-w64-ucrt-x86_64-cmake
</pre>

Install the dependencies for the simulator and the code generation tools:
<div style="margin: 0 0; background: #f7f7e0; padding: 0 10px; border: 1px solid #d0d0c0">
'''Note''': When installing qt5 type enter to install all packages.
</div>
<pre>
pacman -S mingw-w64-ucrt-x86_64-qt5 mingw-w64-ucrt-x86_64-libpng mingw-w64-ucrt-x86_64-zlib mingw-w64-ucrt-x86_64-boost
</pre>

== 3. Build the code generation tools ==

Let us assume you already cloned mxgui's repository somewhere on your filesystem. If you haven't, do it now.

<div style="margin: 0 0; background: #e0f7e0; padding: 0 10px; border: 1px solid #c0d0c0">
'''Tip''': For using git on Windows, we recommend the official distribution (Git for Windows: https://git-scm.com/install/windows) and TortoiseGit for shell integration and GUI support (https://tortoisegit.org).

You can also install git inside MSYS2 by executing <code>pacman -S git</code>. However, this installs a different and separate version of Git, which exists simultaneously and independently from Git for Windows. By default you can't use Git for Windows inside a MSYS2 shell, or MSYS2-installed git in a Windows shell.
</div>

Change directory to <code>_tools/code_generators</code>:
<pre>
cd ../../_tools/code_generators
</pre>

Build the code generators with CMake.
<pre>
mkdir build
cd build
cmake ..
make
</pre>
<div style="margin: 0 0; background: #f7f7e0; padding: 0 10px; border: 1px solid #d0d0c0">
'''Note''': If you want to make the compilation faster by using all the CPU cores in your machine, instead of just typing <code>make</code> type <code>make -j4</code> where 4 stands for the number of CPU cores you have.

Of course you can do this any time you use make to compile something, not just for this one case.

If you don't know how many cores your CPU has, check in Task Manager.
</div>

== 4. Build the simulator ==

Now we only need to build the simulator. Change directory to the simulator's root:
<pre>
cd ../../qtsimulator
</pre>

Then build it like we did for the code generators:
<pre>
mkdir build
cd build
cmake ..
make
</pre>

Now you should be able to run the simulator!
<pre>
./qtsimulator.exe
</pre>

<div style="clear: both">
[[File:Mxgui simulator on Windows 11.png|frame|center]]
</div>

<div style="margin: 0 0; background: #f7e0e0; padding: 0 10px; border: 1px solid #d0c0c0">
'''Warning''': If you double-click on the <code>qtsimulator.exe</code> executable in Windows Explorer, it probably won't work because of some missing DLLs. This is normal. The missing DLLs are located in <code>C:\msys64\ucrt64\bin</code>, a directory that the MSYS2 shell configuration adds to the PATH variable automatically, but is not normally included in PATH.

To make the simulator executable work when double-clicked, first check all the required DLLs by executing <code>lld qtsimulator.exe</code> in the MSYS2 shell, and then copy the DLLs located in <code>C:\msys64\ucrt64\bin</code> to the same directory as <code>qtsimulator.exe</code>.

However, unless you want to distribute the compiled simulator, it's much simpler to just always run it from inside an MSYS2 UCRT64 terminal window.
</div>

== References ==

File:Mxgui simulator on Windows 11.png

2026-03-26T18:12:35Z

Daniele.cattaneo:

Screenshot of the mxgui simulator on Windows 11

File:Msys2 toolchains.png

2026-03-26T13:47:57Z

Daniele.cattaneo:

Toolchains available in a default installation of MSYS2

User:Daniele.cattaneo

2026-03-26T11:47:47Z

Daniele.cattaneo:

Library list

2026-03-24T00:14:55Z

Daniele.cattaneo: Add ST HAL guide link

Libraries are additional components not part of the Miosix kernel that can be downloaded to add functionality to the kernel.

* [[mxgui]] is a GUI library for graphic displays
* [[mxusb]] is an USB stack, currently targeting stm32f1 microcontrollers only.

You can also use the [[ST HAL Support in Miosix|STMicroelectronics HAL code]] (with minimal adaptations) for any peripheral that does not have native Miosix drivers. However this is not recommended as in our experience the HAL often contains buggy or suboptimal drivers.

[[Category:Libraries]]

ST Hal Support in Miosix

2026-03-24T00:12:37Z

Daniele.cattaneo: Daniele.cattaneo moved page ST Hal Support in Miosix to ST HAL Support in Miosix: Misspelled title

#REDIRECT [[ST HAL Support in Miosix]]

ST HAL Support in Miosix

2026-03-24T00:12:37Z

Daniele.cattaneo: Daniele.cattaneo moved page ST Hal Support in Miosix to ST HAL Support in Miosix: Misspelled title

If you are developing or have existing code that uses the HAL from ST Microelectronics, you can port it fairly easily into Miosix by following this guide:

'''Note''': The content of this page was tested on Miosix v3.

'''Note''': Miosix uses C++ instead of C

;1. Follow the [[Quick start]] guide to configure the kernel and install all the required tools
;2. Include "miosix.h" in your program's main file (remember that the file main file must be named "main.cpp") and wherever else you need to use Miosix's APIs;
;3. Remove the clock configuration: Miosix already handles the clock configuration and keeping it in the code would result in a lockup of the microcontroller.

:Usually the clock configuration is generated by STM32Cube and it looks like this:

<pre>
static void SystemClock_Config(void)
{
RCC_ClkInitTypeDef RCC_ClkInitStruct;
RCC_OscInitTypeDef RCC_OscInitStruct;

/* Enable Power Control clock */
__HAL_RCC_PWR_CLK_ENABLE();

/* The voltage scaling allows optimizing the power consumption when the device is
clocked below the maximum system frequency, to update the voltage scaling value
regarding system frequency refer to product datasheet. */
__HAL_PWR_VOLTAGESCALING_CONFIG(PWR_REGULATOR_VOLTAGE_SCALE3);

/* Enable MSI Oscillator */
RCC_OscInitStruct.OscillatorType = RCC_OSCILLATORTYPE_MSI;
RCC_OscInitStruct.MSIState = RCC_MSI_ON;
RCC_OscInitStruct.MSIClockRange = RCC_MSIRANGE_5;
RCC_OscInitStruct.MSICalibrationValue=0x00;
RCC_OscInitStruct.PLL.PLLState = RCC_PLL_NONE;
if(HAL_RCC_OscConfig(&RCC_OscInitStruct) != HAL_OK)
{
/* Initialization Error */
Error_Handler();
}
}
</pre>
For some peripherals you might need to adjust peripheral-level clock configuration registers.

:If your code contains interrupts refer to the section below.

:Here an example code of the main.cpp for a blinking led in a Nucleo-L053R8 board:

<pre>
#include "miosix.h"
#include "stm32l053xx.h"
#include "stm32l0xx_hal.h"
#include <interfaces/bsp.h>
using namespace std;
using namespace miosix;

static void MX_GPIO_Init(void);

int main() {
iprintf("Hello world, write your application here\n");
HAL_Init();

MX_GPIO_Init();
for (;;) {
HAL_GPIO_TogglePin(GPIOA, GPIO_PIN_5);
HAL_Delay(500);
}
}
static void MX_GPIO_Init(void) {
__HAL_RCC_GPIOC_CLK_ENABLE();
__HAL_RCC_GPIOA_CLK_ENABLE();

GPIO_InitTypeDef GPIO_InitStruct = {0};

// Configure Led pin
GPIO_InitStruct.Pin = GPIO_PIN_5;
GPIO_InitStruct.Mode = GPIO_MODE_OUTPUT_PP;
GPIO_InitStruct.Pull = GPIO_NOPULL;
GPIO_InitStruct.Speed = GPIO_SPEED_FREQ_LOW;

HAL_GPIO_Init(GPIOA, &GPIO_InitStruct);
}
</pre>

;4. Include in the Makefile all the libraries and all the file .c needed to compile the program
Remember to include the HAL libraries and .c files used

;5. add a CFLAGS and CXXFLAGS that defines the type of board that you are using in the Makefile
:(ex: CFLAGS += -DSTM32L053xx and CXXFLAGS += -DSTM32L053xx for a stm32l053-R8).
:If you want, you can instead uncomment the type of the board in the Miosix folder (ex: for an stm32l053-R8, you need to uncomment "#define STM32L053xx" in "miosix/arch/common/CMSIS/Device/ST/STM32L0xx/Include/stm32l0xx.h")

;5b. You need to do that also for any Shield that you are using.

;6. Create an implementation of the function HAL_Delay() by using the Miosix primitive Thread::Sleep(). You can put the implementation in a separate file (called for example wrapper.cpp) or wherever else you like.

:Here the part that you need to modify in the example of the Makefile for the previous example:

<pre>
#Prevoius code
SRC :=main.cpp \
STM32CubeL0/Drivers/STM32L0xx_HAL_Driver/Src/stm32l0xx_hal.c \
STM32CubeL0/Drivers/BSP/STM32L0xx_Nucleo/stm32l0xx_nucleo.c \
STM32CubeL0/Drivers/STM32L0xx_HAL_Driver/Src/stm32l0xx_hal_gpio.h \
STM32CubeL0/Drivers/STM32L0xx_HAL_Driver/Src/stm32l0xx_hal_cortex.c \
wrapper.cpp

INCLUDE_DIRS := -ISTM32CubeL0/Drivers/STM32L0xx_HAL_Driver/Inc \
-ISTM32CubeL0/Drivers/BSP/STM32L0xx_Nucleo \
-Imiosix/arch/common/CMSIS/Device/ST/STM32L0xx/Include/ \
-ISTM32CubeL0/Projects/NUCLEO-L053R8/Examples/GPIO/GPIO_IOToggle/Inc

#Other code

CFLAGS += -DSTM32L053xx

CXXFLAGS += -DSTM32L053xx

#Other code
</pre>

;7. Compile and flash the program. This is done by using the command "make" and "make program".

----

=== Interrupts ===

ST's HAL expects interrupt handler functions to be defined statically with weak symbols, allowing to define an interrupt handler for a given IRQ number by simply defining a function with the correct name. This does not work in Miosix and thus the code needs to be adapted.

In Miosix interrupt handlers need to be registered at runtime in order to be called. This is done by creating a lock and registering the IRQ like in the following example:

<pre>
{
GlobalIrqLock lock; //disable interrupts on the core that acquired the lock (all in single core)
IRQregisterIrq(lock, SPI2_IRQn, &SPIx_IRQHandler); //setup for SPI2, SPIx_IRQHandler is the handler called when the SPI finished sending a message
}
</pre>

This needs to be done for each interrupt that you have to register.

Keep in mind that the GlobalIrqLock object is a RAII style acquisition primitive. In other words the lock is held as long the "lock" variable exists, thus encapsulating its declaration in a block (curly brackets) will release the lock automatically when the block ends.

ST HAL Support in Miosix

2026-03-24T00:11:40Z

Daniele.cattaneo:

File:Stm3220g serial.jpg

2026-03-14T21:18:41Z

Daniele.cattaneo: Daniele.cattaneo uploaded a new version of File:Stm3220g serial.jpg

Location of serial pins on stm3220g board

Stm32f207ig stm3220g-eval

2026-03-14T21:16:44Z

Daniele.cattaneo:

This board has an STM32F207IG, a Cortex-M3 running at 120MHz with 1MB of FLASH and 128KB of RAM, plus 2MB of external SRAM. In addtion, the board has some nice peripherals including an USB port and a 320x240 LCD display.
Also, there is a microSD socket allowing filesystem support. Due to GPIO conflicts between the USART and SDIO the SD card works in 1-bit mode instead of 4-bit, thus write speed is limited in this board.

To develop for this board you'll need an USB to serial adapter to be able to deploy your code to the board through its serial bootloader as well as to be able to see debug messages as printf is redirected to the serial port on this board. Optionally, you'll need a JTAG in circuit debugger compatible with OpenOCD and Linux, an [https://www.olimex.com/Products/ARM/JTAG/ARM-USB-OCD ARM-USB-OCD] was tested succesfully.

[[File:Stm3220g-eval.jpg|frameless]]

== Configuring the kernel ==

The minimum configuration required is to edit the [[Makefile.inc|miosix/config/Makefile.inc]] file to uncomment the ''OPT_BOARD := stm32f207ig_stm3220g-eval'' line. If you had compiled the kernel before, it is recommended to do a ''make clean'' (or in the Netbeans IDE, to click on the "Clean project" button) to avoid leaving object files around. After, do a ''make'' to compile.

In addition, this board has a couple of board-specific options in the Makefile.inc file. For convenience, the relevant part of that configuration file is reported here so as to be easily located within the file

<source lang="bash">
##---------------------------------------------------------------------------
## stm32f207ig_stm3220g-eval
##
ifeq ($(OPT_BOARD),stm32f207ig_stm3220g-eval)

## Linker script type, there are three options
## 1) Code in FLASH, stack + heap in internal RAM (file *_rom.ld)
## the most common choice, available for all microcontrollers
## 2) Code in FLASH stack in internal RAM heap in external RAM (file
## *_xram.ld) useful for hardware like STM3220G-EVAL when big heap is
## needed. The microcontroller must have an external memory interface.
## 3) Code + stack + heap in external RAM, (file *_all_in_xram.ld)
## useful for debugging code in hardware like STM3220G-EVAL. Code runs
## *very* slow compared to FLASH. Works only with a booloader that
## forwards interrrupts @ 0x64000000 (see miosix/bootloaders for one).
## The microcontroller must have an external memory interface.
## Warning! enable external ram if you use a linker script that requires it
## (see the XRAM flag below)
LINKER_SCRIPT_PATH := arch/cortexM3_stm32f2/stm32f207ig_stm3220g-eval/
#LINKER_SCRIPT := $(LINKER_SCRIPT_PATH)stm32_1m+128k_rom.ld
#LINKER_SCRIPT := $(LINKER_SCRIPT_PATH)stm32_1m+128k_xram.ld
LINKER_SCRIPT := $(LINKER_SCRIPT_PATH)stm32_1m+128k_all_in_xram.ld

## Enable/disable initialization of external RAM at boot. Three options:
## __ENABLE_XRAM : If you want the heap in xram (with an appropriate linker
## script selected above)
## __ENABLE_XRAM and __CODE_IN_XRAM : Debug mode with code + stack + heap
## in xram (with an appropriate linker script selected above)
## none selected : don't use xram (with an appropriate linker script
## selected above)
#XRAM := -D__ENABLE_XRAM
XRAM := -D__ENABLE_XRAM -D__CODE_IN_XRAM

endif
</source>

As can be seen, there are two options for this board: LINKER_SCRIPT and XRAM. The comments explain in detail the meaning of there options, so it isn't necessary to further explain them.

After modifying configuration files it is recommended to do a make clean; make (or in the Netbeans IDE, to click on the "Clean and build project" button) to be sure that changes are applied.

== Loading code ==

As explained before, there are more than one linker script for this board, and the selected linker script affects the way code should be loaded on the board.

===stm32_1m+128k_all_in_xram.ld===
This is the default linker script, it is very useful for debugging code on this board, as it locates everything (code, stack, heap) in the external RAM. It has the disadvantage that the loaded code is lost upon reboot (being in a volatile memory) and that code will run ~10 times slower due to external RAM access timings, but for debugging, these are not issues.

To be able to use this linker script you need to program a bootloader into the microcontroller's FLASH memory that allows code loading to the external RAM as well as forwarding interrupts there.
This bootloader is in the ''miosix/_tools/bootloaders/stm32/uc_loader_stm3220g-eval'' directory, and information on how to install it can be found in the ''miosix/_doc/textdoc/stm32-bootloader.txt'' file. For programming the bootloader the [http://sourceforge.net/projects/stm32flash stm32flash] tool can be used.

===stm32_1m+128k_rom.ld and stm32_1m+128k_xram.ld===

These linker scripts put the code in FLASH, so you need to program the microcontroller's FLASH every time you change your code, but code will run faster and won't be lost at each reboot.

A simple way to load code in FLASH is to use the stm32flash tool. After having installed it on your system, all you need to do is to connect a serial cable between the USART1 connector on the board and your PC. USB to serial adapters work well if you don't have a serial port. Then, flip up the boot0 switch on your board, and hit the Reset key.
On the PC side, you'll need to run the

<source lang="bash">
stm32flash -w main.hex -v /dev/ttyUSB0
</source>

Of course, replace /dev/ttyUSB0 with your serial port device name.
After that, flip down the boot0 switch and hit again Reset. The code you have loaded should start.

== Reading printf output ==

The board support package of this board simply redirects printf to the serial port USART3. The board has an RS232 connector, so you'll simply need to connect it to your computer via a serial cable, or use an USB to serial adapter connected to pins PC10 (USART3 TX) and PC11 (USART3 RX), which are exposed on pins 36 (PC10) and 35 (PC11) of CN4.
The serial port baudrate is set to 115200baud, 8N1.

<div style="clear: both">
[[File:Stm3220g serial.jpg|frame|center|Location of serial pins]]
</div>

On Linux you can use screen. Open a terminal and type ''screen /dev/ttyUSB0 115200'' (Note that to quit from screen you need to type "Ctrl-C, \"). You'll need to change /dev/ttyUSB0 with your serial port device name.

On windows you can use HyperTerminal, you need to configure it to use the required baud rate, no flow control, and select the correct COM port device name.

== In circuit debugging ==

In-circuit debugging requires an USB to JTAG adapter. Ther recomended one is the [https://www.olimex.com/Products/ARM/JTAG/ARM-USB-OCD ARM-USB-OCD]. If you use a different one, you may need to modify the ''miosix/arch/arm7_lpc2000/lpc2138_miosix_board/lpc2138_armusbocd.cfg'' to adapt it to your JTAG tool.

Before you begin you should note that the Miosix kernel will put the CPU to a low power state when no thread is running. This low power state will usually confuse debuggers and make them lose sync with the CPU. To avoid this you need to edit the [[miosix_settings.h|miosix/config/miosix_settings.h]] file and uncomment ''#define JTAG_DISABLE_SLEEP'' line. This will prevent the kernel from putting the CPU in its low power state making debugging possible.
Also, to be able to precisely single-step your code you need to disable compiler optimizations as gdb is incapable of reliably debug an optimized code. The option is in the miosix/config/Makefile.inc file and is the ''OPT_OPTIMIZATION := -O0'' that should be uncommented while the other lines related to the same option should be commented out.

After modifying configuration files it is recommended to do a ''make clean; make'' (or in the Netbeans IDE, to click on the "Clean and build project" button) to be sure that changes are applied.

On the software side, you need to open two shells. In one do a

<source lang="bash">
sudo openocd -f miosix/arch/cortexM3_stm32f2/stm32f207ig_stm3220g-eval/stm3220g_eval.cfg
</source>

This will start the OpenOCD program that will connect to the board and listen for GDB connections.

In the second shell type the following commands

<source lang="bash">
arm-miosix-eabi-gdb main.elf
target remote :3333
monitor soft_reset_halt
load
break main
continue
</source>

The first command will start the gdb debugger. The following commands are typed into the gdb console, and tell it to connect to OpenOCD, reset the board and stop at the beginning of main()
Please not that the load command implies that you are using the stm32_512k+64k_all_in_xram.ld linker script, and will instruct gdb to load your code in RAM. If you are using another linker script that loads code in FLASH you'll need to replace this command with a

<source lang="bash">
monitor flash write_image erase main.bin 0x08000000
</source>

that will program the FLASH memory.

From there on, have a look at [[Quick_start]] for debugger commands.

== (Optional) Configuring the Netbeans IDE ==
To have a fully working code completion that can also resolve the board-specific symbols, right click on the project, go to Set Configuration and select the right board.

[[File:Netbeans-config.png]]

[[Category:Boards]]

Stm32f207ig stm3220g-eval

2026-03-14T21:04:11Z

Daniele.cattaneo: Fix image

This board has an STM32F207IG, a Cortex-M3 running at 120MHz with 1MB of FLASH and 128KB of RAM, plus 2MB of external SRAM. In addtion, the board has some nice peripherals including an USB port and a 320x240 LCD display.
Also, there is a microSD socket allowing filesystem support. Due to GPIO conflicts between the USART and SDIO the SD card works in 1-bit mode instead of 4-bit, thus write speed is limited in this board.

To develop for this board you'll need an USB to serial adapter to be able to deploy your code to the board through its serial bootloader as well as to be able to see debug messages as printf is redirected to the serial port on this board. Optionally, you'll need a JTAG in circuit debugger compatible with OpenOCD and Linux, an [https://www.olimex.com/Products/ARM/JTAG/ARM-USB-OCD ARM-USB-OCD] was tested succesfully.

[[File:Stm3220g-eval.jpg|frameless]]

== Configuring the kernel ==

The minimum configuration required is to edit the [[Makefile.inc|miosix/config/Makefile.inc]] file to uncomment the ''OPT_BOARD := stm32f207ig_stm3220g-eval'' line. If you had compiled the kernel before, it is recommended to do a ''make clean'' (or in the Netbeans IDE, to click on the "Clean project" button) to avoid leaving object files around. After, do a ''make'' to compile.

In addition, this board has a couple of board-specific options in the Makefile.inc file. For convenience, the relevant part of that configuration file is reported here so as to be easily located within the file

<source lang="bash">
##---------------------------------------------------------------------------
## stm32f207ig_stm3220g-eval
##
ifeq ($(OPT_BOARD),stm32f207ig_stm3220g-eval)

## Linker script type, there are three options
## 1) Code in FLASH, stack + heap in internal RAM (file *_rom.ld)
## the most common choice, available for all microcontrollers
## 2) Code in FLASH stack in internal RAM heap in external RAM (file
## *_xram.ld) useful for hardware like STM3220G-EVAL when big heap is
## needed. The microcontroller must have an external memory interface.
## 3) Code + stack + heap in external RAM, (file *_all_in_xram.ld)
## useful for debugging code in hardware like STM3220G-EVAL. Code runs
## *very* slow compared to FLASH. Works only with a booloader that
## forwards interrrupts @ 0x64000000 (see miosix/bootloaders for one).
## The microcontroller must have an external memory interface.
## Warning! enable external ram if you use a linker script that requires it
## (see the XRAM flag below)
LINKER_SCRIPT_PATH := arch/cortexM3_stm32f2/stm32f207ig_stm3220g-eval/
#LINKER_SCRIPT := $(LINKER_SCRIPT_PATH)stm32_1m+128k_rom.ld
#LINKER_SCRIPT := $(LINKER_SCRIPT_PATH)stm32_1m+128k_xram.ld
LINKER_SCRIPT := $(LINKER_SCRIPT_PATH)stm32_1m+128k_all_in_xram.ld

## Enable/disable initialization of external RAM at boot. Three options:
## __ENABLE_XRAM : If you want the heap in xram (with an appropriate linker
## script selected above)
## __ENABLE_XRAM and __CODE_IN_XRAM : Debug mode with code + stack + heap
## in xram (with an appropriate linker script selected above)
## none selected : don't use xram (with an appropriate linker script
## selected above)
#XRAM := -D__ENABLE_XRAM
XRAM := -D__ENABLE_XRAM -D__CODE_IN_XRAM

endif
</source>

As can be seen, there are two options for this board: LINKER_SCRIPT and XRAM. The comments explain in detail the meaning of there options, so it isn't necessary to further explain them.

After modifying configuration files it is recommended to do a make clean; make (or in the Netbeans IDE, to click on the "Clean and build project" button) to be sure that changes are applied.

== Loading code ==

As explained before, there are more than one linker script for this board, and the selected linker script affects the way code should be loaded on the board.

===stm32_1m+128k_all_in_xram.ld===
This is the default linker script, it is very useful for debugging code on this board, as it locates everything (code, stack, heap) in the external RAM. It has the disadvantage that the loaded code is lost upon reboot (being in a volatile memory) and that code will run ~10 times slower due to external RAM access timings, but for debugging, these are not issues.

To be able to use this linker script you need to program a bootloader into the microcontroller's FLASH memory that allows code loading to the external RAM as well as forwarding interrupts there.
This bootloader is in the ''miosix/_tools/bootloaders/stm32/uc_loader_stm3220g-eval'' directory, and information on how to install it can be found in the ''miosix/_doc/textdoc/stm32-bootloader.txt'' file. For programming the bootloader the [http://sourceforge.net/projects/stm32flash stm32flash] tool can be used.

===stm32_1m+128k_rom.ld and stm32_1m+128k_xram.ld===

These linker scripts put the code in FLASH, so you need to program the microcontroller's FLASH every time you change your code, but code will run faster and won't be lost at each reboot.

A simple way to load code in FLASH is to use the stm32flash tool. After having installed it on your system, all you need to do is to connect a serial cable between the USART1 connector on the board and your PC. USB to serial adapters work well if you don't have a serial port. Then, flip up the boot0 switch on your board, and hit the Reset key.
On the PC side, you'll need to run the

<source lang="bash">
stm32flash -w main.hex -v /dev/ttyUSB0
</source>

Of course, replace /dev/ttyUSB0 with your serial port device name.
After that, flip down the boot0 switch and hit again Reset. The code you have loaded should start.

== Reading printf output ==

The board support package of this board simply redirects printf to the serial port USART3. The board has an RS232 connector, so you'll simply need to connect it to your computer via a serial cable, or use an USB to serial adapter connected to pins PC10 (USART3 TX) and PC11 (USART3 RX), which are exposed on pins 36 (PC10) and 35 (PC11) of CN4.
The serial port baudrate is set to 19200baud, 8N1.

[[File:Stm3220g serial.jpg|frame|Location of serial pins]]

On Linux you can use screen. Open a terminal and type ''screen /dev/ttyUSB0 19200'' (Note that to quit from screen you need to type "Ctrl-C, \"). You'll need to change /dev/ttyUSB0 with your serial port device name.

On windows you can use HyperTerminal, you need to configure it to use the required baud rate, no flow control, and select the correct COM port device name.

== In circuit debugging ==

In-circuit debugging requires an USB to JTAG adapter. Ther recomended one is the [https://www.olimex.com/Products/ARM/JTAG/ARM-USB-OCD ARM-USB-OCD]. If you use a different one, you may need to modify the ''miosix/arch/arm7_lpc2000/lpc2138_miosix_board/lpc2138_armusbocd.cfg'' to adapt it to your JTAG tool.

Before you begin you should note that the Miosix kernel will put the CPU to a low power state when no thread is running. This low power state will usually confuse debuggers and make them lose sync with the CPU. To avoid this you need to edit the [[miosix_settings.h|miosix/config/miosix_settings.h]] file and uncomment ''#define JTAG_DISABLE_SLEEP'' line. This will prevent the kernel from putting the CPU in its low power state making debugging possible.
Also, to be able to precisely single-step your code you need to disable compiler optimizations as gdb is incapable of reliably debug an optimized code. The option is in the miosix/config/Makefile.inc file and is the ''OPT_OPTIMIZATION := -O0'' that should be uncommented while the other lines related to the same option should be commented out.

After modifying configuration files it is recommended to do a ''make clean; make'' (or in the Netbeans IDE, to click on the "Clean and build project" button) to be sure that changes are applied.

On the software side, you need to open two shells. In one do a

<source lang="bash">
sudo openocd -f miosix/arch/cortexM3_stm32f2/stm32f207ig_stm3220g-eval/stm3220g_eval.cfg
</source>

This will start the OpenOCD program that will connect to the board and listen for GDB connections.

In the second shell type the following commands

<source lang="bash">
arm-miosix-eabi-gdb main.elf
target remote :3333
monitor soft_reset_halt
load
break main
continue
</source>

The first command will start the gdb debugger. The following commands are typed into the gdb console, and tell it to connect to OpenOCD, reset the board and stop at the beginning of main()
Please not that the load command implies that you are using the stm32_512k+64k_all_in_xram.ld linker script, and will instruct gdb to load your code in RAM. If you are using another linker script that loads code in FLASH you'll need to replace this command with a

<source lang="bash">
monitor flash write_image erase main.bin 0x08000000
</source>

that will program the FLASH memory.

From there on, have a look at [[Quick_start]] for debugger commands.

== (Optional) Configuring the Netbeans IDE ==
To have a fully working code completion that can also resolve the board-specific symbols, right click on the project, go to Set Configuration and select the right board.

[[File:Netbeans-config.png]]

[[Category:Boards]]

File:Stm3220g serial.jpg

2026-03-14T21:03:21Z

Daniele.cattaneo:

Location of serial pins on stm3220g board

Stm32f207ig stm3220g-eval

2026-03-14T20:59:19Z

Daniele.cattaneo: Add serial pin location image

This board has an STM32F207IG, a Cortex-M3 running at 120MHz with 1MB of FLASH and 128KB of RAM, plus 2MB of external SRAM. In addtion, the board has some nice peripherals including an USB port and a 320x240 LCD display.
Also, there is a microSD socket allowing filesystem support. Due to GPIO conflicts between the USART and SDIO the SD card works in 1-bit mode instead of 4-bit, thus write speed is limited in this board.

To develop for this board you'll need an USB to serial adapter to be able to deploy your code to the board through its serial bootloader as well as to be able to see debug messages as printf is redirected to the serial port on this board. Optionally, you'll need a JTAG in circuit debugger compatible with OpenOCD and Linux, an [https://www.olimex.com/Products/ARM/JTAG/ARM-USB-OCD ARM-USB-OCD] was tested succesfully.

[[File:Stm3220g-eval.jpg|frameless]]

== Configuring the kernel ==

The minimum configuration required is to edit the [[Makefile.inc|miosix/config/Makefile.inc]] file to uncomment the ''OPT_BOARD := stm32f207ig_stm3220g-eval'' line. If you had compiled the kernel before, it is recommended to do a ''make clean'' (or in the Netbeans IDE, to click on the "Clean project" button) to avoid leaving object files around. After, do a ''make'' to compile.

In addition, this board has a couple of board-specific options in the Makefile.inc file. For convenience, the relevant part of that configuration file is reported here so as to be easily located within the file

<source lang="bash">
##---------------------------------------------------------------------------
## stm32f207ig_stm3220g-eval
##
ifeq ($(OPT_BOARD),stm32f207ig_stm3220g-eval)

## Linker script type, there are three options
## 1) Code in FLASH, stack + heap in internal RAM (file *_rom.ld)
## the most common choice, available for all microcontrollers
## 2) Code in FLASH stack in internal RAM heap in external RAM (file
## *_xram.ld) useful for hardware like STM3220G-EVAL when big heap is
## needed. The microcontroller must have an external memory interface.
## 3) Code + stack + heap in external RAM, (file *_all_in_xram.ld)
## useful for debugging code in hardware like STM3220G-EVAL. Code runs
## *very* slow compared to FLASH. Works only with a booloader that
## forwards interrrupts @ 0x64000000 (see miosix/bootloaders for one).
## The microcontroller must have an external memory interface.
## Warning! enable external ram if you use a linker script that requires it
## (see the XRAM flag below)
LINKER_SCRIPT_PATH := arch/cortexM3_stm32f2/stm32f207ig_stm3220g-eval/
#LINKER_SCRIPT := $(LINKER_SCRIPT_PATH)stm32_1m+128k_rom.ld
#LINKER_SCRIPT := $(LINKER_SCRIPT_PATH)stm32_1m+128k_xram.ld
LINKER_SCRIPT := $(LINKER_SCRIPT_PATH)stm32_1m+128k_all_in_xram.ld

## Enable/disable initialization of external RAM at boot. Three options:
## __ENABLE_XRAM : If you want the heap in xram (with an appropriate linker
## script selected above)
## __ENABLE_XRAM and __CODE_IN_XRAM : Debug mode with code + stack + heap
## in xram (with an appropriate linker script selected above)
## none selected : don't use xram (with an appropriate linker script
## selected above)
#XRAM := -D__ENABLE_XRAM
XRAM := -D__ENABLE_XRAM -D__CODE_IN_XRAM

endif
</source>

As can be seen, there are two options for this board: LINKER_SCRIPT and XRAM. The comments explain in detail the meaning of there options, so it isn't necessary to further explain them.

After modifying configuration files it is recommended to do a make clean; make (or in the Netbeans IDE, to click on the "Clean and build project" button) to be sure that changes are applied.

== Loading code ==

As explained before, there are more than one linker script for this board, and the selected linker script affects the way code should be loaded on the board.

===stm32_1m+128k_all_in_xram.ld===
This is the default linker script, it is very useful for debugging code on this board, as it locates everything (code, stack, heap) in the external RAM. It has the disadvantage that the loaded code is lost upon reboot (being in a volatile memory) and that code will run ~10 times slower due to external RAM access timings, but for debugging, these are not issues.

To be able to use this linker script you need to program a bootloader into the microcontroller's FLASH memory that allows code loading to the external RAM as well as forwarding interrupts there.
This bootloader is in the ''miosix/_tools/bootloaders/stm32/uc_loader_stm3220g-eval'' directory, and information on how to install it can be found in the ''miosix/_doc/textdoc/stm32-bootloader.txt'' file. For programming the bootloader the [http://sourceforge.net/projects/stm32flash stm32flash] tool can be used.

===stm32_1m+128k_rom.ld and stm32_1m+128k_xram.ld===

These linker scripts put the code in FLASH, so you need to program the microcontroller's FLASH every time you change your code, but code will run faster and won't be lost at each reboot.

A simple way to load code in FLASH is to use the stm32flash tool. After having installed it on your system, all you need to do is to connect a serial cable between the USART1 connector on the board and your PC. USB to serial adapters work well if you don't have a serial port. Then, flip up the boot0 switch on your board, and hit the Reset key.
On the PC side, you'll need to run the

<source lang="bash">
stm32flash -w main.hex -v /dev/ttyUSB0
</source>

Of course, replace /dev/ttyUSB0 with your serial port device name.
After that, flip down the boot0 switch and hit again Reset. The code you have loaded should start.

== Reading printf output ==

The board support package of this board simply redirects printf to the serial port USART3. The board has an RS232 connector, so you'll simply need to connect it to your computer via a serial cable, or use an USB to serial adapter connected to pins PC10 (USART3 TX) and PC11 (USART3 RX), which are exposed on pins 36 (PC10) and 35 (PC11) of CN4.
The serial port baudrate is set to 19200baud, 8N1.

[[File:Stm32f3220g serial.jpg|thumb|Location of the serial pins]]

On Linux you can use screen. Open a terminal and type ''screen /dev/ttyUSB0 19200'' (Note that to quit from screen you need to type "Ctrl-C, \"). You'll need to change /dev/ttyUSB0 with your serial port device name.

On windows you can use HyperTerminal, you need to configure it to use the required baud rate, no flow control, and select the correct COM port device name.

== In circuit debugging ==

In-circuit debugging requires an USB to JTAG adapter. Ther recomended one is the [https://www.olimex.com/Products/ARM/JTAG/ARM-USB-OCD ARM-USB-OCD]. If you use a different one, you may need to modify the ''miosix/arch/arm7_lpc2000/lpc2138_miosix_board/lpc2138_armusbocd.cfg'' to adapt it to your JTAG tool.

Before you begin you should note that the Miosix kernel will put the CPU to a low power state when no thread is running. This low power state will usually confuse debuggers and make them lose sync with the CPU. To avoid this you need to edit the [[miosix_settings.h|miosix/config/miosix_settings.h]] file and uncomment ''#define JTAG_DISABLE_SLEEP'' line. This will prevent the kernel from putting the CPU in its low power state making debugging possible.
Also, to be able to precisely single-step your code you need to disable compiler optimizations as gdb is incapable of reliably debug an optimized code. The option is in the miosix/config/Makefile.inc file and is the ''OPT_OPTIMIZATION := -O0'' that should be uncommented while the other lines related to the same option should be commented out.

After modifying configuration files it is recommended to do a ''make clean; make'' (or in the Netbeans IDE, to click on the "Clean and build project" button) to be sure that changes are applied.

On the software side, you need to open two shells. In one do a

<source lang="bash">
sudo openocd -f miosix/arch/cortexM3_stm32f2/stm32f207ig_stm3220g-eval/stm3220g_eval.cfg
</source>

This will start the OpenOCD program that will connect to the board and listen for GDB connections.

In the second shell type the following commands

<source lang="bash">
arm-miosix-eabi-gdb main.elf
target remote :3333
monitor soft_reset_halt
load
break main
continue
</source>

The first command will start the gdb debugger. The following commands are typed into the gdb console, and tell it to connect to OpenOCD, reset the board and stop at the beginning of main()
Please not that the load command implies that you are using the stm32_512k+64k_all_in_xram.ld linker script, and will instruct gdb to load your code in RAM. If you are using another linker script that loads code in FLASH you'll need to replace this command with a

<source lang="bash">
monitor flash write_image erase main.bin 0x08000000
</source>

that will program the FLASH memory.

From there on, have a look at [[Quick_start]] for debugger commands.

== (Optional) Configuring the Netbeans IDE ==
To have a fully working code completion that can also resolve the board-specific symbols, right click on the project, go to Set Configuration and select the right board.

[[File:Netbeans-config.png]]

[[Category:Boards]]

File:Stm32f3220g serial.jpg

2026-03-14T20:58:16Z

Daniele.cattaneo:

Serial TX/RX pins location on stm3220g board.

Miosix 3

2026-03-12T14:15:19Z

Daniele.cattaneo:

Mxgui OLED example

2025-12-18T00:18:10Z

Daniele.cattaneo: Update instructions to latest Miosix version.

= Before you begin =

This tutorial is mainly focused at showing
* How to add Mxgui to your project
* How to drive a small OLED display that can be easily found on ebay with Mxgui

[[File:Small_oled.jpg]]

This tutorial assumes that you have read the [[Miosix and git workflow]] and that you have already downloaded and configured the kernel.
The code of this example can be found in the mxgui library itself https://github.com/fedetft/mxgui/tree/master/_examples/display_ly091wg14

= Configuration =

In the Miosix top-level directory (or in the directory of your project if you are using an out of git tree project download the mxgui library. If you are under a git repository

<source lang="bash">
git submodule add https://github.com/fedetft/mxgui.git
</source>

or if your project directory is not under git

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

If you are using an out of git tree project setup is is recomended to copy the mxgui/config/mxgui_settings.h file in your project config directory as you'll need to edit it.

<source lang="bash">
cp mxgui/config/mxgui_settings.h config
</source>

Now edit your makefile to add the following:

Add the mxgui directory to SUBDIRS so when you run make, the graphics library will be compiled
<source lang="bash">
SUBDIRS += mxgui
</source>

Add libmxgui.a to LIBS so the the graphics library will be linked
<source lang="bash">
LIBS := mxgui/libmxgui.a
</source>

Add both the mxgui directory and the directory one level upper to INCLUDE_DIRS so includes will work
<source lang="bash">
INCLUDE_DIRS := -Imxgui
</source>

Now, edit mxgui_settings.h as follows, commenting out the following line.
The purpose of this change is to disable the input module of the library, as in this example we don't have a touchscreen driver.
<source lang="C">
#define MXGUI_LEVEL_2
</source>

Replace your main with the example code and edit it as needed to match the pins to the ones of the display
<source lang="bash">
cp mxgui/_examples/display_ly091wg14/main.cpp .
</source>

Build the example with make, and flash it with make program.

Multicore

2025-04-01T16:24:09Z

Daniele.cattaneo: Created page with "Since release 3.0, Miosix supports multicore (SMP) microcontrollers, such as the RP2040. SMP support is required in three key areas: boot, locking, interrupts and scheduler. The kernel is configured with SMP enabled if the board configuration defines the macro WITH_SMP, otherwise only the first core is used. == SMP interfaces == SMP-specific functions that need to be implemented by each architecture port are defined in smp.h. Other interfaces related to SMP support, bu..."

Since release 3.0, Miosix supports multicore (SMP) microcontrollers, such as the RP2040.
SMP support is required in three key areas: boot, locking, interrupts and scheduler.
The kernel is configured with SMP enabled if the board configuration defines the macro WITH_SMP, otherwise only the first core is used.

== SMP interfaces ==

SMP-specific functions that need to be implemented by each architecture port are defined in smp.h.
Other interfaces related to SMP support, but not specific to it, are os_timer.h, interrupts.h, cpu_const.h and atomic_ops.h.

== Boot ==

At boot, if SMP is enabled, Miosix calls a platform-specific function defined in smp.h called IRQinitSMP().
This function is responsible early at boot for doing the following:

* Allocating a system stack (in ARM parlance, the stack for interrupt handlers) for all non-zero cores.
* Starting up all other cores (except core 0 which is already started up) and configuring their system stacks and process stacks (in ARM parlance, the stack for running non-interrupt code).
* Configuring the interrupt vectors for all cores to be the same as core 0 (the interrupt vectors are shared for all cores, but the enabled/disabled state must be per-core).
* Initializing and starting the OS timer for all cores included core 0.
* Jumping to the specified main function in all cores.

At the end of this function, all other cores must be up enough to be able to immediately process a IRQinvokeSchedulerOnCore or an IRQcallOnCore, which will be discussed later.

== Locking ==

When in kernel mode, the hardware implicitly creates one special "thread" that needs to be synchronized against: interrupt handlers.
Interrupt handlers access OS state (specifically, peripheral driver state, or scheduler state for the timer interrupt) but --- barring magic shenanigans that are complicated to implement and add significant overhead --- cannot yield to another thread.
Hence one cannot use conventional synchronization primitives.

In the single core case, the easiest way to ensure mutual exclusion with an interrupt handler is to disable interrupts altogether.
Since preemption is driven by interrupts (even wakeups, at least in ARM architectures, due to the use of PendSV for implementing the Yield primitive) this also has the effect of disabling preemption.
Disabling preemption means we also are in mutual exclusion with other pieces of code that disable/enable interrupts.
There is no need to disable interrupts in interrupt handlers because they already are assumed to run in mutual exclusion between each other.
In reality this is not strictly true on platforms that have nested interrupts but Miosix disables nested interrupts.

In an SMP architectures, being in an interrupt handler and/or disabling interrupts does '''not''' ensure mutual exclusion with other interrupt handlers or with other pieces of code which run with interrupts disabled.
This is because interrupts are per-core, and the interrupt disabling flag is also per-core.
Even with interrupts disabled, or in an interrupt handler, the other cores can run code in parallel, with interrupts disabled or not, or even in an interrupt handler.

The solution to this is to use spinlocks.
A fundamental property of spinlocks, as opposed to other synchronization methods, is that they do not require anything from the operating system, they can always be used even with preemption disabled or in an interrupt handler.
Unfortunately they also burn CPU cycles, but at least on ARM the WFE instruction can be used to put a core to sleep while waiting for a spinlock to be released, and the SEV instruction can wake all cores sleeping on a WFE when a spinlock is released.
These instructions work even with interrupts disabled.

User:Daniele.cattaneo

2025-03-28T14:45:38Z

Daniele.cattaneo:

Hi :)

Github (work): [https://github.com/danielecattaneo]

Github (personal): Secret

[[Miosix in emulation]]

[[arch directory restructuring]]

[[Miosix 3]]

[[Multicore]]

Arch directory restructuring

2024-10-23T00:12:45Z

Daniele.cattaneo: More details that were missing

The ''arch'' directory is a mess with lots of copy-pasted code. Ideally it should be '''consistently and logically organized''': each directory should have a documented purpose in order to leave as little doubt as possible about ''what goes where''. Additionally, each directory's purpose makes sense in the overall structure, without overlaps between the scope of each directory.
At the moment however we observe this is not the case. We believe that in order to make the future growth of Miosix simpler and faster, the right moment to rectify the situation is now.

''Update 31/12/2023'' I discovered a bug in the testing branch of Miosix which was caused by the copy-pasting of gpio_impl.h: version 1.4 (sic, see comments) didn't have the alternateFunction method of Gpio, even though serial_stm32.cpp assumes it always exists. (btw don't we have git? manual versioning in comments is not a robust practice!!!) I bet other similar bugs exist.

== Some definitions ==

Common sense suggests the following taxonomy of parts for MCU-equipped devices targeted by Miosix:
* Board: The device itself being targeted. It's called a board because nobody has observed any MCU wired with point-to-point wiring yet (citation needed). Includes the MCU itself plus any peripheral external to the MCU but '''driven''' by it.
* Chip: The MCU itself. May come in RAM/OTP/ROM/Flash size variations, which are mostly ignored.
* Chip family: A set of MCU types from the same manufacturer with the same microprocessor core but potentially different set of peripherals. While the available set of peripherals may vary, the behaviour and I/O ports of each kind of peripheral are the same across the entire family. Thanks to the brilliant ideas of the various marketing departments of each vendor, the classification here can get very fluid.
* Core: The microprocessor core used by a given chip family.

Let's take as an example the classic stm32f4discovery board that is the most common development device for Miosix:
* The board is the stm32f4discovery itself. It includes the chip, and miscellaneous peripherals such as an accelerometer and a Cirrus Logic audio chip. The STLink programming interface and the power supply are '''not''' considered relevant parts of the board for Miosix, as the MCU is not in control of what they do.
* The chip is an STM32F407VGT6. The VGT6 suffix of the chip name specifies package (100 pin LQFP), Flash size (1MB) and temperature range options (see the datasheet at the "Ordering Information" page).
* The chip family is STM32F4. This can be inferred by the fact that all available chips with this prefix in the part name share the same reference manual. (Notice that this is a slight simplification of reality because there are STM32F4 chips that are not covered by the same reference manual as the STM32F407 but the point we want to get across is that multiple MCUs share roughly the same silicon behaviour and drivers)
* The core is an ARM Cortex M4, as stated in the datasheet. Roughly, ST buys the Verilog for the core from ARM and then takes care of the manufacturing. As far as we know, ARM's licence only allows ST to customize the core in very limited ways, so all Cortex M4 cores should behave basically the same, even from other vendors. Tunables may be things like the number of MPU regions or whether floating point is available or not, which may be important or not.

=== What is an architecture? ===

One definition we did not give is the definition of what an '''architecture''' is. The reason is that there is no accepted definition for this term, especially for forum pundits and bloggers, but also in academia. The RISC school of thought (Patterson/Hennessy and their spawn) historically associated an ''architecture'' with a combination of what are more specifically called the ''instruction set architecture'' (ISA) and the ''microarchitecture'' of a core. The ISA is the overall structure and design of the instructions, as opposed to the ''instruction set'' proper which is the set of instructions accepted by a specific core. The '''microarchitecture''' is the overall internal design of the core itself.

Their thesis was that the microarchitecture design will follow naturally from the definition of the ISA, hence simpler ISAs (RISC) to implement always lead to more efficient and generally better cores. Therefore one can consider the '''architecture''' to be primarily determined by the ISA. However the industry has proven them wrong, and the most glaring example are Intel x86 chips, which have seen an increasing variety of microarchitectures implementing the same ISA (variously extended of course) with wildly varying levels of (non-)efficiency (in all possible ramifications of "efficiency"). Closer to Miosix's targets, the ARM ISA has been extended so much over the years that its core RISC design has now evolved to basically a traditional CISC ISA, but ARM chips still come in every possible size and flavour.

When we talk about x86 "architectures" or ARM "architectures", but do we mean desktop-grade chips or microcontrollers? Even though they have the same "architecture" the cores in these two classes of chips have nothing to do with each other, they don't even share the same instruction decoder probably. Hence our conclusion that the word "architecture" has now lost all useful meaning for our purposes, and is only useful for void parlor chitchat.

And then we come to Miosix which defines "architecture" (arch) as... a board. Which is not what anyone means when they talk about architecture of anything. For Miosix, an "architecture" is more like what in common parlance would be meant as a "platform".

== Current structure ==

Here's a schematic diagram of how the Miosix ''arch'' directory (plus related directories) is configured. In the following ''/'' refers to the ''miosix'' directory at the top level of the repository.

<pre>
arch Architecture-specific files
common Pool of useful files. Very few files here are common to all archs.
CMSIS Collection of ARM & vendor headers following the CMSIS standard
core Board independent drivers required for the OS to function (roughly)
atomic_ops_*.h Core dependent
cache_*.cpp/h Core dependent. This is not required at all for Miosix to work but is nevertheless here
*_os_timer.cpp Chip family dependent
endianness_*.h Core dependent. Should have a generic (slow) implementation but it's missing.
interrupts.h Umbrella header for interrupts_*.h
interrupts_*.h Core dependent. Misleading name, this is for fault handling.
memory_protection.h Umbrella header for mpu_*.h. Required only for process mode. Name is not consistent with other umbrella headers, should have been "mpu.h"
mpu_*.cpp/h Core dependent.
drivers Miscellaneous drivers, which are "common" only very roughly
dcc.cpp/h Core dependent (but common to all ARM cores apparently)
*_adc.cpp/h Chip family dependent
serial.h Umbrella header for *serial*.h
*serial*.cpp/h Chip family dependent
sd_*.cpp/h Chip family dependent
servo_*.cpp/h Board dependent really, should go into utils
*_hardware_rng.cpp/h Chip family dependent
*_rtc.cpp/h Chip family dependent
*_sgm.cpp/h Chip family dependent
*_wd.cpp/h Chip family dependent
*_i2c.cpp/h Chip family dependent
<board group name> Board group specific files.
common Common drivers and configuration for all the boards in the group
arch_settings.h Core dependent. Misleading name, defines requirements for ctxsave
interfaces-impl The actual drivers, most of them required by Miosix to function.
arch_registers_impl.h Chip family dependent. Includes the appropriate register definitions
delays.cpp Chip family dependent as it also depends on ROM/Flash speed. Actually application dependent (!) as cache/prefetch mechanisms can be configured but whatever.
gpio_impl.cpp/h Chip family dependent.
portability_impl.h Core dependent.
portability.cpp Core dependent.
drivers Miscellaneous drivers not required by Miosix to function, with exceptions (atsam4l clock)
*.cpp/h
<board name> Board/chip specific files.
core Board/chip dependent code required for the OS to function.
stage_1_boot.c/cpp/s Chip dependent. Interrupt vector table, reset handler, clock tree setup, bss/data initialization
interfaces_impl Important board/chip specific drivers, most of them required by Miosix to function.
bsp_impl.h Board dependent. Useful board-specific definitions.
bsp.cpp Board dependent. Useful board-specific functions.
hwmapping.h Board dependent. GPIO pin definitions.
deep_sleep.cpp Chip family dependent. Optional implementation of deep sleep primitives.
delays.cpp See above. Sometimes it's here, with no true reason why.
arch_registers_impl.h See above. Sometimes it's here, depends on chip.
... Some boards have extra miscellaneous drivers here
*.h Some boards have chip registers definitions here (LPC2138)
*.cfg Some boards have OpenOCD config files here
*.ld Chip family specific. Linker files for different RAM/Flash configurations
interfaces Headers for hardware interfaces TO miosix (internals) and SOME interfaces OF miosix to the application (APIs). Only commonality is that they are all hardware dependent (while stuff in utils/kernel is ''generally'' hardware independent)
arch_registers.h API. Umbrella for "arch_registers_impl.h", selected through include search path manipulation.
atomic_ops.h API. Umbrella for "atomic_ops_*.h", selected through ifdefs.
bsp.h API + internal prototypes (IRQbspInit, bspInit2). Umbrella for "bsp_impl.h", selected through include search path manipulation.
deep_sleep.h Internal prototypes only. Not an umbrella header.
delays.h API. Not an umbrella header.
endianness.h API. Umbrella for "endianness_*.h", selected through ifdefs.
gpio.h API. Umbrella for "gpio_impl.h", selected through include search path manipulation.
os_timer.h Internal declarations. Not an umbrella header.
portability.h Internal declarations. Primitives for context switching and syscalls. Umbrella for "portability_impl.h", selected through include search path manipulation.
util Additional APIs made available for applications as utilities, built on top of kernel primitives or other drivers
lcd44780.cpp/h Driver for Hitachi-standard HD44780 character displays.
software_i2c/spi.h Bit-banged i2c/spi implementations. Arguably drivers.
utils.cpp/h Memory/CPU usage profiling. Misleading name. Not a driver
... Other files are not related to hardware
config Configuration files, user-modifiable
Makefile.inc List of board + selection of board to build for + selection of compile time options through defines passed as argument to the compiler. The first section of the file arguably is not user-modifiable configuration.
miosix-settings.h Global settings selected through defines in header files
arch Board-dependent settings
<board group>
<board>
board_settings.h Board-dependent settings selected through defines in header files
</pre>

''<board group name>'' is defined as the name of the chip core, followed by an underscore, followed by the name of a chip family. ''<board name>'' is defined by the name of the chip, followed by an underscore, followed by a "common name" of the board. For commercial prototyping boards or specific devices, "common name" is derived from the name given by the manufacturer, or a name which is in common use with some exceptions (i.e. stm32f103 bluepill boards are named "breakout").

Some general patterns can be inferred:
* Apart from minor exceptions, directories named '''core''' contain drivers required for the OS to function.
* Directories named '''interfaces_impl''' generally contain implementations of things defined in /interfaces. Header files in '''interfaces_impl''' are always given the ``_impl`` suffix. C++ files are usually not given the "_impl" suffix but sometimes they have it (gpio_impl.cpp).
* Directories named '''common''' contain code shared by multiple boards. No attempt is made to separate different levels of commonality apart from chip-family specific stuff which is grouped by board group.

=== Include paths ===

The current directory structure allows the Makefile to select the implementation of some file by solely changing the include search paths of the compiler. This mostly applies to files in ''<board group name>/<board name>'' and in ''<board group name>/config''. The Makefile defines several variables that are used to refer to specific paths in the directory tree:

{| class="wikitable"
|-
! Variable !! Value Pattern !! Scope !! Is config !! Defined by !! Description
|-
| LINKER_SCRIPT_PATH || arch/<board group name>/<board name>/ || Board || Yes || Makefile.inc || Directory where the linker scripts are found
|-
| LINKER_SCRIPT || $(LINKER_SCRIPT_PATH)/<script>.ld || Board || Yes || Makefile.inc || Path of the linker script
|-
| ARCH_INC || arch/<board group name>/common || Board group || No || Makefile.inc || Path of the common directory of the board group
|-
| BOARD_INC || arch/<board group name>/<board name> || Board || No || Makefile.inc || Path of the board directory
|-
| BOOT_FILE || $(BOARD_INC)/core/stage_1_boot.o || Board || No || Makefile.inc || Path of the object file for the board bootstrap code
|-
| ARCH_SRC || $(BOARD_INC)/*/*.cpp $(ARCH_INC)/*/*.cpp arch/common/drivers/*.cpp || Board + Board group || No || Sources for the drivers enabled for this board
|-
| KPATH || miosix || Global || Yes || Appl. Makefile || Root directory of the kernel files
|-
| CONFPATH || $(KPATH) || Global || Yes || Appl. Makefile || Root directory for configuration files
|}

For reference, the final include paths, defined by the application makefile, are:
<pre>
$(CONFPATH)
$(CONFPATH)/config/$(BOARD_INC)
$(KPATH)
$(KPATH)/arch/common
$(KPATH)/$(ARCH_INC)
$(KPATH)/$(BOARD_INC)
</pre>

Notice that, despite the name of the defines, there is no distinction between include paths and source paths, as includes are alongside the source. We do not have a problem with this approach, however it results in all includes being publicly available for applications, which is something that is not entirely desirable.

==== Drivers selected by include path ====

Sometimes Miosix's headers include files that depend on the board selected for building. This of course can give problems when reorganizing files around. The affected files are:

* interfaces/arch_registers.h
* interfaces/bsp.h
* interfaces/gpio.h
* interfaces/portability.h

Overall selecting different files through the include paths is desirable, so we want to avoid adding additional architecture-specific ifdefs as much as possible.

=== Issues ===

Experience has shown this organization has the following problems:
* What goes where is not well defined due to the vagueness of directory names
** This leads to files being in the wrong place even though it's not obvious
*** servo_* is the most glaring example
*** The location of delays.cpp and arch_registers_impl.h is also inconsistent
* The two level board group/board classification does not reflect reality, which leads to missing code sharing opportunities:
** GPIO implementations are duplicated multiple times as they are common to multiple chip families and not to a single one.
** Bootstrap code is duplicated multiple times as they are common to boards with the same chip and not common to the board.
** Portability code (i.e. context save/restore primitives mostly) is duplicated multiple times as they are common to a given core and not to a chip family
** Linker scripts are also duplicated multiple times
* Classifications sometimes privilege syntax rather than semantics, in an inconsistent fashion
** Directories named '''interfaces_impl''' contain drivers just like directories named '''drivers''', except that they included from /interfaces.
** What is '''common''' and what is not loosely determined by the amount of code sharing but most stuff not under a '''common''' directory is duplicated at least twice

Of course, the root issue is the fluidity of the distinction between chip and chip family, and how each vendor manages and/or defines each family. For instance, STM32 chips all have similar USART (serial) implementations, but at least two versions can be distinguished through different register definitions and feature sets. Therefore the same overall driver can be shared across almost all STM32 chips, however the driver is littered with ''ifdef''s to single out the specificity of each implementation. There is really no strict distinction to what can be found where, as the vendors can and do mix and match peripherals even amongst themselves. For example, some STM32 chips have Synopsis-designed USB interfaces which can also be found on chips from vendors that are not ST.

These considerations highlight that the solution to handling the issue of organizing platform-specific code in a consistent way to '''minimize code duplication''' is not to '''add''' hierarchy levels, but to remove them. This runs contrary from the naive consideration that "Board includes Chip, which belongs to Chip Family, which contains a Core".

== A proposal ==

Pointing out what's wrong is easy, fixing it up is hard. Of course "what we should do" is a matter of opinion, and a valid answer to that could even be "nothing". Overall, what we ultimately want is for all drivers to be decoupled from boards and board groups, in order to be able to classify each driver depending on its actual logical group it belongs to. We can take this opportunity for a more radical restructuring of Miosix's source tree, or we can opt for more conservative solutions.

=== With classification per device type ===

This proposal is the most radical as it splits the drivers in a completely different way than what is currently done: by device type. For instance all USART drivers go in a "serial" directory, all GPIO drivers go in a GPIO directory, and so on. This approach scales well when there are a lot of drivers around, but completely prevents selection of drivers by using the include paths.

The arch directory has been named "platform" because of our general dislike of the "architecture" word, but that's really just a bonus. Most other operating systems use "arch" as a directory for drivers and target-specific stuff, so keeping the name "arch" is also an option. We also moved the interfaces headers under the "platform" ("arch") directory, since they basically are just umbrella headers for various drivers. This loses the distinction of some of them being more essential than others, additional directories can be added for this purpose.

<pre>
platform
arch_registers.h
atomic_ops.h
bsp.h
deep_sleep.h
delays.h
endianness.h
gpio.h
os_timer.h
portability.h
memory_protection.h
interrupts.h
mpu.h
serial.h
arch_registers
CMSIS
<chip/chip family>
arch_registers_impl.h
....h
core
boot
<chip>
stage_1_boot.c/cpp/s
atomic_ops
atomic_ops_*.h
os_timer
*_os_timer.cpp
endianness
endianness_*.h
faults
interrupts_*.h
mpu
*_mpu.cpp/h
portability
<core>
arch_settings.h
portability_impl.h
portability.cpp
gpio
<chip/chip family>
gpio_impl.cpp/h
delays
<chip/chip family>
delays.cpp
drivers
arm_dcc.cpp/h
deep_sleep
deep_sleep.cpp
cache
cache_*.cpp/h
serial
*_serial.cpp/h
adc
*_adc.cpp/h
sd
*_sd.cpp/h
servo
*_servo.cpp/h
hardware_rng
*_hardware_rng.cpp/h
rtc
*_rtc.cpp/h
sgm
*_sgm.cpp/h
wd
*_wd.cpp/h
i2c
*_i2c.cpp/h
software_i2c.h
spi
software_spi.h
display
lcd44780.cpp/h
...
board
<board>
bsp_impl.h
bsp.cpp
hwmapping.h
*.cfg
linker_scripts
<chip>
*.ld
config
Makefile.inc
miosix_settings.h
<board>
board_settings.h
</pre>

=== Without classification per device type ===

This is just the same proposal as before but which classifies drivers only by "manufacturer" or chip. This allows to use the include trick for selecting headers.

<pre>
platform
arch_registers.h
atomic_ops.h
bsp.h
deep_sleep.h
delays.h
endianness.h
gpio.h
os_timer.h
portability.h
memory_protection.h
interrupts.h
mpu.h
serial.h
arch_registers
CMSIS
<chip/chip family>
arch_registers_impl.h
....h
core
<chip/chip family>
stage_1_boot.c/cpp/s
*_os_timer.cpp
*_mpu.cpp/h
gpio_impl.cpp/h
delays.cpp
<core>
atomic_ops_*.h
endianness_*.h
interrupts_*.h
arch_settings.h
portability_impl.h
portability.cpp
drivers
dcc.cpp/h
*_servo.cpp/h
software_i2c.h
software_spi.h
lcd44780.cpp/h
<core>
cache_*.cpp/h
<chip/chip family>
deep_sleep.cpp
*_serial.cpp/h
*_adc.cpp/h
*_sd.cpp/h
*_hardware_rng.cpp/h
*_rtc.cpp/h
*_sgm.cpp/h
*_wd.cpp/h
*_i2c.cpp/h
...
board
<board>
bsp_impl.h
bsp.cpp
hwmapping.h
*.cfg
linker_scripts
<chip>
*.ld
config
Makefile.inc
miosix_settings.h
<board>
board_settings.h
</pre>

=== With minimal changes to the existing structure ===

<pre>
arch
common
CMSIS
core
boot
<chip>_stage_1_boot.c/cpp/s
<core>_portability
arch_settings.h
portability_impl.h
portability.cpp
<chip family>
delays.cpp
gpio_impl.cpp/h
deep_sleep.cpp
(all other existing files)
drivers
All miscellaneous drivers in board directory are moved here
(all other existing files)
linker_scripts
<chip>
*.ld
<board group name>
common
(should now be empty)
<board name>
interfaces_impl
bsp_impl.h
bsp.cpp
hwmapping.h
*.cfg
interfaces Unmodified
config Unmodified
</pre>

Miosix 3

2024-03-22T17:23:33Z

Daniele.cattaneo:

TODO list for Miosix 3 for development purposes
* CMake in mainline
** Basato sul CMake di Skyward
* Restructuring driver per deduplicare
* Eliminazione codice di startup di ST e delle define stupid CLOCK512MHZ=5120000000
** Driver PLL
* Modifica driver per interrupt registrabili a runtime
* Aggiornamento dei CMSIS
* Split board e chip
* Driver della seriale rifatto e ripulito
* Compressione .data in elf processi
* Compressione kernel in RAM

== Compressione ==

<pre>
[17:09] Federico Terraneo
cazzo sai che in futuro mi è venuta un'idea
[17:10] Federico Terraneo
una volta che iniziamo a giocare con la compressione anche noi
[17:10] Federico Terraneo
potremmo comprimere la copia di .data all'interno dei processi e del kernel
[17:10] Federico Terraneo
easy win, ed è un'altro piccolo paper
[17:10] Federico Terraneo
e non impedisce xip
[17:11] Federico Terraneo
no idea cosa sia
[17:13] Daniele Cattaneo
bella idea! anche se non ci si guadagna poi tantissimo credo
[17:13] Federico Terraneo
abbastanza % da meritare un paper imho
[17:14] Federico Terraneo
e se il codice della decompressione inizi ad averlo in giro per fare altre cose why not?
[17:14] Federico Terraneo
per i processi è easy
[17:14] Federico Terraneo
il loader decomprime
[17:14] Federico Terraneo
per il kernel è più tricky perchè non il codice di decompressione non deve dipendere da .data a sua volta
[17:15] Federico Terraneo
e in ogni caso bisogna patchare ld per comprimere la sezione .data
[17:15] Federico Terraneo
o lo mettiamo nel postlinker
[17:15] Federico Terraneo
possiamo scegliere
[17:15] Federico Terraneo
anche se forse dovremmo patchare ld e basta e togliere il postlinker
[17:17] Federico Terraneo
le dipendenze nel kernel le risolvi facendo un vero e proprio stage 1 loader separato
[17:18] Federico Terraneo
che pensos ervirà anche se vogliamo fare il kernel compresso che si decomprime ed esegue in ram
[17:18] Federico Terraneo
che è un'opzione utile se hai poca flash e tanta ram o se inizia voler scrivere in flash senza stallare tutto l'os
[17:18] Federico Terraneo
durante il ciclo di erase
[17:19] Federico Terraneo
boh, come ti dicevo ho idee per vari modi di piazzare il codice del kernel e dei processi per dare flessibilità
[17:19] Federico Terraneo
c'è anche la compressione degli eseguibili nel romfs
[17:20] Federico Terraneo
tante idee
[17:20] Federico Terraneo
anche se i benchark su linux imostrano che la config attuale è la più veloce
[17:20] Federico Terraneo
forse per iniziare a mettere cose in ram ci vogliono gli f7 con la cache
</pre>

Miosix 3

2024-03-22T17:23:25Z

Daniele.cattaneo:

TODO list for Miosix 3 for development purposes
* CMake in mainline
** Basato sul CMake di Skyward
* Restructuring driver per deduplicare
* Eliminazione codice di startup di ST e delle define stupid CLOCK512MHZ=5120000000
** Driver PLL
* Modifica driver per interrupt registrabili a runtime
* Aggiornamento dei CMSIS
* Split board e chip
* Driver della seriale rifatto e ripulito
* Compressione .data in elf processi
* Compressione kernel in RAM

== Compressione ==

<code>
[17:09] Federico Terraneo
cazzo sai che in futuro mi è venuta un'idea
[17:10] Federico Terraneo
una volta che iniziamo a giocare con la compressione anche noi
[17:10] Federico Terraneo
potremmo comprimere la copia di .data all'interno dei processi e del kernel
[17:10] Federico Terraneo
easy win, ed è un'altro piccolo paper
[17:10] Federico Terraneo
e non impedisce xip
[17:11] Federico Terraneo
no idea cosa sia
[17:13] Daniele Cattaneo
bella idea! anche se non ci si guadagna poi tantissimo credo
[17:13] Federico Terraneo
abbastanza % da meritare un paper imho
[17:14] Federico Terraneo
e se il codice della decompressione inizi ad averlo in giro per fare altre cose why not?
[17:14] Federico Terraneo
per i processi è easy
[17:14] Federico Terraneo
il loader decomprime
[17:14] Federico Terraneo
per il kernel è più tricky perchè non il codice di decompressione non deve dipendere da .data a sua volta
[17:15] Federico Terraneo
e in ogni caso bisogna patchare ld per comprimere la sezione .data
[17:15] Federico Terraneo
o lo mettiamo nel postlinker
[17:15] Federico Terraneo
possiamo scegliere
[17:15] Federico Terraneo
anche se forse dovremmo patchare ld e basta e togliere il postlinker
[17:17] Federico Terraneo
le dipendenze nel kernel le risolvi facendo un vero e proprio stage 1 loader separato
[17:18] Federico Terraneo
che pensos ervirà anche se vogliamo fare il kernel compresso che si decomprime ed esegue in ram
[17:18] Federico Terraneo
che è un'opzione utile se hai poca flash e tanta ram o se inizia voler scrivere in flash senza stallare tutto l'os
[17:18] Federico Terraneo
durante il ciclo di erase
[17:19] Federico Terraneo
boh, come ti dicevo ho idee per vari modi di piazzare il codice del kernel e dei processi per dare flessibilità
[17:19] Federico Terraneo
c'è anche la compressione degli eseguibili nel romfs
[17:20] Federico Terraneo
tante idee
[17:20] Federico Terraneo
anche se i benchark su linux imostrano che la config attuale è la più veloce
[17:20] Federico Terraneo
forse per iniziare a mettere cose in ram ci vogliono gli f7 con la cache
</code>

Miosix 3

2024-03-22T17:23:06Z

Daniele.cattaneo:

TODO list for Miosix 3 for development purposes
* CMake in mainline
** Basato sul CMake di Skyward
* Restructuring driver per deduplicare
* Eliminazione codice di startup di ST e delle define stupid CLOCK512MHZ=5120000000
** Driver PLL
* Modifica driver per interrupt registrabili a runtime
* Aggiornamento dei CMSIS
* Split board e chip
* Driver della seriale rifatto e ripulito
* Compressione .data in elf processi
* Compressione kernel in RAM

## Compressione

[17:09] Federico Terraneo
cazzo sai che in futuro mi è venuta un'idea
[17:10] Federico Terraneo
una volta che iniziamo a giocare con la compressione anche noi
[17:10] Federico Terraneo
potremmo comprimere la copia di .data all'interno dei processi e del kernel
[17:10] Federico Terraneo
easy win, ed è un'altro piccolo paper
[17:10] Federico Terraneo
e non impedisce xip
[17:11] Federico Terraneo
no idea cosa sia
[17:13] Daniele Cattaneo
bella idea! anche se non ci si guadagna poi tantissimo credo
[17:13] Federico Terraneo
abbastanza % da meritare un paper imho
[17:14] Federico Terraneo
e se il codice della decompressione inizi ad averlo in giro per fare altre cose why not?
[17:14] Federico Terraneo
per i processi è easy
[17:14] Federico Terraneo
il loader decomprime
[17:14] Federico Terraneo
per il kernel è più tricky perchè non il codice di decompressione non deve dipendere da .data a sua volta
[17:15] Federico Terraneo
e in ogni caso bisogna patchare ld per comprimere la sezione .data
[17:15] Federico Terraneo
o lo mettiamo nel postlinker
[17:15] Federico Terraneo
possiamo scegliere
[17:15] Federico Terraneo
anche se forse dovremmo patchare ld e basta e togliere il postlinker
[17:17] Federico Terraneo
le dipendenze nel kernel le risolvi facendo un vero e proprio stage 1 loader separato
[17:18] Federico Terraneo
che pensos ervirà anche se vogliamo fare il kernel compresso che si decomprime ed esegue in ram
[17:18] Federico Terraneo
che è un'opzione utile se hai poca flash e tanta ram o se inizia voler scrivere in flash senza stallare tutto l'os
[17:18] Federico Terraneo
durante il ciclo di erase
[17:19] Federico Terraneo
boh, come ti dicevo ho idee per vari modi di piazzare il codice del kernel e dei processi per dare flessibilità
[17:19] Federico Terraneo
c'è anche la compressione degli eseguibili nel romfs
[17:20] Federico Terraneo
tante idee
[17:20] Federico Terraneo
anche se i benchark su linux imostrano che la config attuale è la più veloce
[17:20] Federico Terraneo
forse per iniziare a mettere cose in ram ci vogliono gli f7 con la cache

Miosix 3

2024-03-22T16:29:25Z

Daniele.cattaneo:

Quick start

2024-03-17T17:30:33Z

Daniele.cattaneo: Better instructions for configuring VSCode.

To start using Miosix you need a patched version of the GCC compiler called [[Miosix Toolchain]] and git to download the kernel sources. Optionally you can also use an IDE to simplify code development, and an in-circuit debugger to speed up bug fixing.

= Getting started =

This section will guide you through the installation of the minimum requirements to start using Miosix: installing the compiler, and downloading the kernel.

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

= Miosix and git workflow =

See [[Miosix and git workflow]] to understand how to manage the Miosix git repository.

= In-circuit debugger =

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. Miosix uses GDB and [http://openocd.sourceforge.net openocd] for in-circuit debugging.

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

= IDEs =

At the moment the simplest way to develop Miosix is to use a plain text editor. Alternatively, you can use any IDE that supports Makefiles to take advantage of features such as autocompletion and/or debugger integration (where available).

== Visual Studio Code ==

Visual Studio Code is known to work properly on the Miosix source tree with the standard C/C++ and Makefile extensions. After installing these extensions, you need to configure IntelliSense in the C/C++ extension to use the include paths found from the Makefile by setting the ''Configuration provider'' for the workspace to <code>ms-vscode.makefile-tools</code>.

Integration with GDB/openocd has not been tested but you can run GDB/openocd manually in the integrated terminal.

== Netbeans IDE ==

'''Important:''' These instructions were developed back when NetBeans was still a Sun product, they are probably outdated by now!

For a long time the default IDE to develop for Miosix has been [https://netbeans.org/ Netbeans]. NetBeans does not come with Miosix support out of the box, so you have to configure it first.

* [[Linux Netbeans configuration]]
* [[Windows Netbeans configuration]]
* [[OSX Netbeans configuration]]

== Other IDEs ==

* [[VisualStudio Quick Start|Windows Visual Studio configuration]] using VisualGDB which integrates in-circuit debugging support.
* [[Linux Eclipse configuration|Eclipse]], which has the added feature to allow in-circuit debugging directly from the IDE.
* [[Linux QtCreator configuration]]
* [[Windows QtCreator configuration]]

[[Category:Installation and Configuration]]

Arch directory restructuring

2023-12-31T17:29:36Z

Daniele.cattaneo:

The ''arch'' directory is a mess with lots of copy-pasted code. Ideally it should be '''consistently and logically organized''': each directory should have a documented purpose in order to leave as little doubt as possible about ''what goes where''. Additionally, each directory's purpose makes sense in the overall structure, without overlaps between the scope of each directory.
At the moment however we observe this is not the case. We believe that in order to make the future growth of Miosix simpler and faster, the right moment to rectify the situation is now.

''Update 31/12/2023'' I discovered a bug in the testing branch of Miosix which was caused by the copy-pasting of gpio_impl.h: version 1.4 (sic, see comments) didn't have the alternateFunction method of Gpio, even though serial_stm32.cpp assumes it always exists. (btw don't we have git? manual versioning in comments is not a robust practice!!!) I bet other similar bugs exist.

== Some definitions ==

Common sense suggests the following taxonomy of parts for MCU-equipped devices targeted by Miosix:
* Board: The device itself being targeted. It's called a board because nobody has observed any MCU wired with point-to-point wiring yet. Includes the MCU itself plus any peripheral external to the MCU but '''driven''' by it.
* Chip: The MCU itself. May come in RAM/OTP/ROM/Flash size variations, which are mostly ignored.
* Chip family: A set of MCU types from the same manufacturer with the same microprocessor core but potentially different set of peripherals. While the available set of peripherals may vary, the behaviour and I/O ports of each kind of peripheral are the same across the entire family. Thanks to the brilliant ideas of the various marketing departments of each vendor, the classification here can get very fluid.
* Core: The microprocessor core used by a given chip family.

Let's take as an example the classic stm32f4discovery board that is the most common development device for Miosix:
* The board is the stm32f4discovery itself. It includes the chip, and miscellaneous peripherals such as an accelerometer and a Cirrus Logic audio chip. The STLink programming interface and the power supply are '''not''' considered relevant parts of the board for Miosix, as the MCU is not in control of what they do.
* The chip is an STM32F407VGT6. The VGT6 suffix of the chip name specifies package (100 pin LQFP), Flash size (1MB) and temperature range options (see the datasheet at the "Ordering Information" page).
* The chip family is STM32F4. This can be inferred by the fact that all available chips with this prefix in the part name share the same reference manual.
* The core is an ARM Cortex M4, as stated in the datasheet. Roughly, ST buys the Verilog for the core from ARM and then takes care of the manufacturing. As far as we know, ARM's licence shouldn't allow ST to customize the core in any way, so all Cortex M4 cores should behave the same, even from other vendors.

=== What is an architecture? ===

One definition we did not give is the definition of what an '''architecture''' is. The reason is that there is no accepted definition for this term, especially for forum pundits and bloggers, but also in academia. The RISC school of thought (Patterson/Hennessy and their spawn) historically associated an ''architecture'' with a combination of what are more specifically called the ''instruction set architecture'' (ISA) and the ''microarchitecture'' of a core. The ISA is the overall structure and design of the instructions, as opposed to the ''instruction set'' proper which is the set of instructions accepted by a specific core. The '''microarchitecture''' is the overall internal design of the core itself.

Their thesis was that the microarchitecture design will follow naturally from the definition of the ISA, hence simpler ISAs (RISC) to implement always lead to more efficient and generally better cores. Therefore one can consider the '''architecture''' to be primarily determined by the ISA. However the industry has proven them wrong, and the most glaring example are Intel x86 chips, which have seen an increasing variety of microarchitectures implementing the same ISA (variously extended of course) with wildly varying levels of (non-)efficiency (in all possible ramifications of "efficiency"). Closer to Miosix's targets, the ARM ISA has been extended so much over the years that its core RISC design has now evolved to basically a traditional CISC ISA, but ARM chips still come in every possible size and flavour.

When we talk about x86 "architectures" or ARM "architectures", but do we mean desktop-grade chips or microcontrollers? Even though they have the same "architecture" the cores in these two classes of chips have nothing to do with each other, they don't even share the same instruction decoder probably. Hence our conclusion that the word "architecture" has now lost all useful meaning for our purposes, and is only useful for void parlor chitchat.

And then we come to Miosix which defines "architecture" (arch) as... a board. Which is not what anyone means when they talk about architecture of anything. For Miosix, an "architecture" is more like what in common parlance would be meant as a "platform".

== Current structure ==

Here's a schematic diagram of how the Miosix ''arch'' directory (plus related directories) is configured. In the following ''/'' refers to the ''miosix'' directory at the top level of the repository.

<pre>
arch Architecture-specific files
common Pool of useful files. Very few files here are common to all archs.
CMSIS Collection of ARM & vendor headers following the CMSIS standard
core Board independent drivers required for the OS to function (roughly)
atomic_ops_*.h Core dependent
cache_*.cpp/h Core dependent. This is not required at all for Miosix to work but is nevertheless here
*_os_timer.cpp Chip family dependent
endianness_*.h Core dependent. Should have a generic (slow) implementation but it's missing.
interrupts.h Umbrella header for interrupts_*.h
interrupts_*.h Core dependent. Misleading name, this is for fault handling.
memory_protection.h Umbrella header for mpu_*.h. Required only for process mode. Name is not consistent with other umbrella headers, should have been "mpu.h"
mpu_*.cpp/h Core dependent.
drivers Miscellaneous drivers, which are "common" only very roughly
dcc.cpp/h Core dependent (but common to all ARM cores apparently)
*_adc.cpp/h Chip family dependent
serial.h Umbrella header for *serial*.h
*serial*.cpp/h Chip family dependent
sd_*.cpp/h Chip family dependent
servo_*.cpp/h Board dependent really, should go into utils
*_hardware_rng.cpp/h Chip family dependent
*_rtc.cpp/h Chip family dependent
*_sgm.cpp/h Chip family dependent
*_wd.cpp/h Chip family dependent
*_i2c.cpp/h Chip family dependent
<board group name> Board group specific files.
common Common drivers and configuration for all the boards in the group
arch_settings.h Core dependent. Misleading name, defines requirements for ctxsave
interfaces-impl The actual drivers, most of them required by Miosix to function.
arch_registers_impl.h Chip family dependent. Includes the appropriate register definitions
delays.cpp Chip family dependent as it also depends on ROM/Flash speed. Actually application dependent (!) as cache/prefetch mechanisms can be configured but whatever.
gpio_impl.cpp/h Chip family dependent.
portability_impl.h Core dependent.
portability.cpp Core dependent.
drivers Miscellaneous drivers not required by Miosix to function, with exceptions (atsam4l clock)
*.cpp/h
<board name> Board/chip specific files.
core Board/chip dependent code required for the OS to function.
stage_1_boot.c/cpp/s Chip dependent. Interrupt vector table, reset handler, clock tree setup, bss/data initialization
interfaces_impl Important board/chip specific drivers, most of them required by Miosix to function.
bsp_impl.h Board dependent. Useful board-specific definitions.
bsp.cpp Board dependent. Useful board-specific functions.
hwmapping.h Board dependent. GPIO pin definitions.
deep_sleep.cpp Chip family dependent. Optional implementation of deep sleep primitives.
delays.cpp See above. Sometimes it's here, with no true reason why.
arch_registers_impl.h See above. Sometimes it's here, depends on chip.
... Some boards have extra miscellaneous drivers here
*.h Some boards have chip registers definitions here (LPC2138)
*.cfg Some boards have OpenOCD config files here
*.ld Chip family specific. Linker files for different RAM/Flash configurations
interfaces Headers for hardware interfaces TO miosix (internals) and SOME interfaces OF miosix to the application (APIs). Only commonality is that they are all hardware dependent (while stuff in utils/kernel is ''generally'' hardware independent)
arch_registers.h API. Umbrella for "arch_registers_impl.h", selected through include search path manipulation.
atomic_ops.h API. Umbrella for "atomic_ops_*.h", selected through ifdefs.
bsp.h API + internal prototypes (IRQbspInit, bspInit2). Umbrella for "bsp_impl.h", selected through include search path manipulation.
deep_sleep.h Internal prototypes only. Not an umbrella header.
delays.h API. Not an umbrella header.
endianness.h API. Umbrella for "endianness_*.h", selected through ifdefs.
gpio.h API. Umbrella for "gpio_impl.h", selected through include search path manipulation.
os_timer.h Internal declarations. Not an umbrella header.
portability.h Internal declarations. Primitives for context switching and syscalls. Umbrella for "portability_impl.h", selected through include search path manipulation.
util Additional APIs made available for applications as utilities, built on top of kernel primitives or other drivers
lcd44780.cpp/h Driver for Hitachi-standard HD44780 character displays.
software_i2c/spi.h Bit-banged i2c/spi implementations. Arguably drivers.
utils.cpp/h Memory/CPU usage profiling. Misleading name. Not a driver
... Other files are not related to hardware
config Configuration files, user-modifiable
Makefile.inc List of board + selection of board to build for + selection of compile time options through defines passed as argument to the compiler. The first section of the file arguably is not user-modifiable configuration.
miosix-settings.h Global settings selected through defines in header files
arch Board-dependent settings
<board group>
<board>
board_settings.h Board-dependent settings selected through defines in header files
</pre>

''<board group name>'' is defined as the name of the chip core, followed by an underscore, followed by the name of a chip family. ''<board name>'' is defined by the name of the chip, followed by an underscore, followed by a "common name" of the board. For commercial prototyping boards or specific devices, "common name" is derived from the name given by the manufacturer, or a name which is in common use with some exceptions (i.e. stm32f103 bluepill boards are named "breakout").

Some general patterns can be inferred:
* Apart from minor exceptions, directories named '''core''' contain drivers required for the OS to function.
* Directories named '''interfaces_impl''' generally contain implementations of things defined in /interfaces. Header files in '''interfaces_impl''' are always given the ``_impl`` suffix. C++ files are usually not given the "_impl" suffix but sometimes they have it (gpio_impl.cpp).
* Directories named '''common''' contain code shared by multiple boards. No attempt is made to separate different levels of commonality apart from chip-family specific stuff which is grouped by board group.

=== Include paths ===

The current directory structure allows the Makefile to select the implementation of some file by solely changing the include search paths of the compiler. This mostly applies to files in ''<board group name>/<board name>'' and in ''<board group name>/config''. The Makefile defines several variables that are used to refer to specific paths in the directory tree:

{| class="wikitable"
|-
! Variable !! Value Pattern !! Scope !! Is config !! Defined by !! Description
|-
| LINKER_SCRIPT_PATH || arch/<board group name>/<board name>/ || Board || Yes || Makefile.inc || Directory where the linker scripts are found
|-
| LINKER_SCRIPT || $(LINKER_SCRIPT_PATH)/<script>.ld || Board || Yes || Makefile.inc || Path of the linker script
|-
| ARCH_INC || arch/<board group name>/common || Board group || No || Makefile.inc || Path of the common directory of the board group
|-
| BOARD_INC || arch/<board group name>/<board name> || Board || No || Makefile.inc || Path of the board directory
|-
| BOOT_FILE || $(BOARD_INC)/core/stage_1_boot.o || Board || No || Makefile.inc || Path of the object file for the board bootstrap code
|-
| ARCH_SRC || $(BOARD_INC)/*/*.cpp $(ARCH_INC)/*/*.cpp arch/common/drivers/*.cpp || Board + Board group || No || Sources for the drivers enabled for this board
|-
| KPATH || miosix || Global || Yes || Appl. Makefile || Root directory of the kernel files
|-
| CONFPATH || $(KPATH) || Global || Yes || Appl. Makefile || Root directory for configuration files
|}

For reference, the final include paths, defined by the application makefile, are:
<pre>
$(CONFPATH)
$(CONFPATH)/config/$(BOARD_INC)
$(KPATH)
$(KPATH)/arch/common
$(KPATH)/$(ARCH_INC)
$(KPATH)/$(BOARD_INC)
</pre>

Notice that, despite the name of the defines, there is no distinction between include paths and source paths, as includes are alongside the source. We do not have a problem with this approach, however it results in all includes being publicly available for applications, which is something that is not entirely desirable.

==== Drivers selected by include path ====

Sometimes Miosix's headers include files that depend on the board selected for building. This of course can give problems when reorganizing files around. The affected files are:

* interfaces/arch_registers.h
* interfaces/bsp.h
* interfaces/gpio.h
* interfaces/portability.h

Overall selecting different files through the include paths is desirable, so we want to avoid adding additional architecture-specific ifdefs as much as possible.

=== Issues ===

Experience has shown this organization has the following problems:
* What goes where is not well defined due to the vagueness of directory names
** This leads to files being in the wrong place even though it's not obvious
*** servo_* is the most glaring example
*** The location of delays.cpp and arch_registers_impl.h is also inconsistent
* The two level board group/board classification does not reflect reality, which leads to missing code sharing opportunities:
** GPIO implementations are duplicated multiple times as they are common to multiple chip families and not to a single one.
** Bootstrap code is duplicated multiple times as they are common to boards with the same chip and not common to the board.
** Portability code (i.e. context save/restore primitives mostly) is duplicated multiple times as they are common to a given core and not to a chip family
** Linker scripts are also duplicated multiple times
* Classifications sometimes privilege syntax rather than semantics, in an inconsistent fashion
** Directories named '''interfaces_impl''' contain drivers just like directories named '''drivers''', except that they included from /interfaces.
** What is '''common''' and what is not loosely determined by the amount of code sharing but most stuff not under a '''common''' directory is duplicated at least twice

Of course, the root issue is the fluidity of the distinction between chip and chip family, and how each vendor manages and/or defines each family. For instance, STM32 chips all have similar USART (serial) implementations, but at least two versions can be distinguished through different register definitions and feature sets. Therefore the same overall driver can be shared across almost all STM32 chips, however the driver is littered with ''ifdef''s to single out the specificity of each implementation. There is really no strict distinction to what can be found where, as the vendors can and do mix and match peripherals even amongst themselves. For example, some STM32 chips have Synopsis-designed USB interfaces which can also be found on chips from vendors that are not ST.

These considerations highlight that the solution to handling the issue of organizing platform-specific code in a consistent way to '''minimize code duplication''' is not to '''add''' hierarchy levels, but to remove them. This runs contrary from the naive consideration that "Board includes Chip, which belongs to Chip Family, which contains a Core".

== A proposal ==

Pointing out what's wrong is easy, fixing it up is hard. Of course "what we should do" is a matter of opinion, and a valid answer to that could even be "nothing". Overall, what we ultimately want is for all drivers to be decoupled from boards and board groups, in order to be able to classify each driver depending on its actual logical group it belongs to. We can take this opportunity for a more radical restructuring of Miosix's source tree, or we can opt for more conservative solutions.

=== With classification per device type ===

This proposal is the most radical as it splits the drivers in a completely different way than what is currently done: by device type. For instance all USART drivers go in a "serial" directory, all GPIO drivers go in a GPIO directory, and so on. This approach scales well when there are a lot of drivers around, but completely prevents selection of drivers by using the include paths.

The arch directory has been named "platform" because of our general dislike of the "architecture" word, but that's really just a bonus. Most other operating systems use "arch" as a directory for drivers and target-specific stuff, so keeping the name "arch" is also an option. We also moved the interfaces headers under the "platform" ("arch") directory, since they basically are just umbrella headers for various drivers. This loses the distinction of some of them being more essential than others, additional directories can be added for this purpose.

<pre>
platform
arch_registers.h
atomic_ops.h
bsp.h
deep_sleep.h
delays.h
endianness.h
gpio.h
os_timer.h
portability.h
memory_protection.h
interrupts.h
mpu.h
serial.h
arch_registers
CMSIS
<chip/chip family>
arch_registers_impl.h
....h
core
boot
<chip>
stage_1_boot.c/cpp/s
atomic_ops
atomic_ops_*.h
os_timer
*_os_timer.cpp
endianness
endianness_*.h
faults
interrupts_*.h
mpu
*_mpu.cpp/h
portability
<core>
arch_settings.h
portability_impl.h
portability.cpp
gpio
<chip/chip family>
gpio_impl.cpp/h
delays
<chip/chip family>
delays.cpp
drivers
arm_dcc.cpp/h
deep_sleep
deep_sleep.cpp
cache
cache_*.cpp/h
serial
*_serial.cpp/h
adc
*_adc.cpp/h
sd
*_sd.cpp/h
servo
*_servo.cpp/h
hardware_rng
*_hardware_rng.cpp/h
rtc
*_rtc.cpp/h
sgm
*_sgm.cpp/h
wd
*_wd.cpp/h
i2c
*_i2c.cpp/h
software_i2c.h
spi
software_spi.h
display
lcd44780.cpp/h
...
board
<board>
bsp_impl.h
bsp.cpp
hwmapping.h
*.cfg
linker_scripts
<chip>
*.ld
config
Makefile.inc
miosix_settings.h
<board>
board_settings.h
</pre>

=== Without classification per device type ===

This is just the same proposal as before but which classifies drivers only by "manufacturer" or chip. This allows to use the include trick for selecting headers.

<pre>
platform
arch_registers.h
atomic_ops.h
bsp.h
deep_sleep.h
delays.h
endianness.h
gpio.h
os_timer.h
portability.h
memory_protection.h
interrupts.h
mpu.h
serial.h
arch_registers
CMSIS
<chip/chip family>
arch_registers_impl.h
....h
core
<chip/chip family>
stage_1_boot.c/cpp/s
*_os_timer.cpp
*_mpu.cpp/h
gpio_impl.cpp/h
delays.cpp
<core>
atomic_ops_*.h
endianness_*.h
interrupts_*.h
arch_settings.h
portability_impl.h
portability.cpp
drivers
dcc.cpp/h
*_servo.cpp/h
software_i2c.h
software_spi.h
lcd44780.cpp/h
<core>
cache_*.cpp/h
<chip/chip family>
deep_sleep.cpp
*_serial.cpp/h
*_adc.cpp/h
*_sd.cpp/h
*_hardware_rng.cpp/h
*_rtc.cpp/h
*_sgm.cpp/h
*_wd.cpp/h
*_i2c.cpp/h
...
board
<board>
bsp_impl.h
bsp.cpp
hwmapping.h
*.cfg
linker_scripts
<chip>
*.ld
config
Makefile.inc
miosix_settings.h
<board>
board_settings.h
</pre>

=== With minimal changes to the existing structure ===

<pre>
arch
common
CMSIS
core
boot
<chip>_stage_1_boot.c/cpp/s
<core>_portability
arch_settings.h
portability_impl.h
portability.cpp
<chip family>
delays.cpp
gpio_impl.cpp/h
deep_sleep.cpp
(all other existing files)
drivers
All miscellaneous drivers in board directory are moved here
(all other existing files)
linker_scripts
<chip>
*.ld
<board group name>
common
(should now be empty)
<board name>
interfaces_impl
bsp_impl.h
bsp.cpp
hwmapping.h
*.cfg
interfaces Unmodified
config Unmodified
</pre>

Miosix 3

2023-11-28T16:58:47Z

Daniele.cattaneo:

Miosix 3

2023-11-28T16:58:24Z

Daniele.cattaneo:

TODO list for Miosix 3
* CMake in mainline
** Basato sul CMake di Skyward
* Restructuring driver per deduplicare
* Eliminazione codice di startup di ST e delle define stupid CLOCK512MHZ=5120000000
** Driver PLL
* Modifica driver per interrupt registrabili a runtime
* Aggiornamento dei CMSIS
* Split board e chip
* Driver della seriale rifatto e ripulito

Miosix 3

2023-11-28T16:13:12Z

Daniele.cattaneo: Created page with "* CMake in mainline ** Basato sul CMake di Skyward * Restructuring driver per deduplicare * Eliminazione codice di startup di ST e delle define stupid CLOCK512MHZ=5120000000 ** Driver PLL * Modifica driver per interrupt registrabili a runtime * Aggiornamento dei CMSIS * Split board e chip * Driver della seriale rifatto e ripulito"

* CMake in mainline
** Basato sul CMake di Skyward
* Restructuring driver per deduplicare
* Eliminazione codice di startup di ST e delle define stupid CLOCK512MHZ=5120000000
** Driver PLL
* Modifica driver per interrupt registrabili a runtime
* Aggiornamento dei CMSIS
* Split board e chip
* Driver della seriale rifatto e ripulito

User:Daniele.cattaneo

2023-11-28T13:39:58Z

Daniele.cattaneo:

Hi :)

Github (work): [https://github.com/danielecattaneo]

Github (personal): Secret

[[Miosix in emulation]]

[[arch directory restructuring]]

[[Miosix 3]]

User:Daniele.cattaneo

2023-11-28T13:39:49Z

Daniele.cattaneo:

Hi :)

Github (work): [https://github.com/danielecattaneo]

Github (personal): Secret

[[Miosix in emulation]]

[[arch directory restructuring]]

[[Future]]

Arch directory restructuring

2023-11-17T23:14:43Z

Daniele.cattaneo:

The ''arch'' directory is a mess with lots of copy-pasted code. Ideally it should be '''consistently and logically organized''': each directory should have a documented purpose in order to leave as little doubt as possible about ''what goes where''. Additionally, each directory's purpose makes sense in the overall structure, without overlaps between the scope of each directory.
At the moment however we observe this is not the case. We believe that in order to make the future growth of Miosix simpler and faster, the right moment to rectify the situation is now.

== Some definitions ==

Common sense suggests the following taxonomy of parts for MCU-equipped devices targeted by Miosix:
* Board: The device itself being targeted. It's called a board because nobody has observed any MCU wired with point-to-point wiring yet. Includes the MCU itself plus any peripheral external to the MCU but '''driven''' by it.
* Chip: The MCU itself. May come in RAM/OTP/ROM/Flash size variations, which are mostly ignored.
* Chip family: A set of MCU types from the same manufacturer with the same microprocessor core but potentially different set of peripherals. While the available set of peripherals may vary, the behaviour and I/O ports of each kind of peripheral are the same across the entire family. Thanks to the brilliant ideas of the various marketing departments of each vendor, the classification here can get very fluid.
* Core: The microprocessor core used by a given chip family.

Let's take as an example the classic stm32f4discovery board that is the most common development device for Miosix:
* The board is the stm32f4discovery itself. It includes the chip, and miscellaneous peripherals such as an accelerometer and a Cirrus Logic audio chip. The STLink programming interface and the power supply are '''not''' considered relevant parts of the board for Miosix, as the MCU is not in control of what they do.
* The chip is an STM32F407VGT6. The VGT6 suffix of the chip name specifies package (100 pin LQFP), Flash size (1MB) and temperature range options (see the datasheet at the "Ordering Information" page).
* The chip family is STM32F4. This can be inferred by the fact that all available chips with this prefix in the part name share the same reference manual.
* The core is an ARM Cortex M4, as stated in the datasheet. Roughly, ST buys the Verilog for the core from ARM and then takes care of the manufacturing. As far as we know, ARM's licence shouldn't allow ST to customize the core in any way, so all Cortex M4 cores should behave the same, even from other vendors.

=== What is an architecture? ===

One definition we did not give is the definition of what an '''architecture''' is. The reason is that there is no accepted definition for this term, especially for forum pundits and bloggers, but also in academia. The RISC school of thought (Patterson/Hennessy and their spawn) historically associated an ''architecture'' with a combination of what are more specifically called the ''instruction set architecture'' (ISA) and the ''microarchitecture'' of a core. The ISA is the overall structure and design of the instructions, as opposed to the ''instruction set'' proper which is the set of instructions accepted by a specific core. The '''microarchitecture''' is the overall internal design of the core itself.

Their thesis was that the microarchitecture design will follow naturally from the definition of the ISA, hence simpler ISAs (RISC) to implement always lead to more efficient and generally better cores. Therefore one can consider the '''architecture''' to be primarily determined by the ISA. However the industry has proven them wrong, and the most glaring example are Intel x86 chips, which have seen an increasing variety of microarchitectures implementing the same ISA (variously extended of course) with wildly varying levels of (non-)efficiency (in all possible ramifications of "efficiency"). Closer to Miosix's targets, the ARM ISA has been extended so much over the years that its core RISC design has now evolved to basically a traditional CISC ISA, but ARM chips still come in every possible size and flavour.

When we talk about x86 "architectures" or ARM "architectures", but do we mean desktop-grade chips or microcontrollers? Even though they have the same "architecture" the cores in these two classes of chips have nothing to do with each other, they don't even share the same instruction decoder probably. Hence our conclusion that the word "architecture" has now lost all useful meaning for our purposes, and is only useful for void parlor chitchat.

And then we come to Miosix which defines "architecture" (arch) as... a board. Which is not what anyone means when they talk about architecture of anything. For Miosix, an "architecture" is more like what in common parlance would be meant as a "platform".

== Current structure ==

Here's a schematic diagram of how the Miosix ''arch'' directory (plus related directories) is configured. In the following ''/'' refers to the ''miosix'' directory at the top level of the repository.

<pre>
arch Architecture-specific files
common Pool of useful files. Very few files here are common to all archs.
CMSIS Collection of ARM & vendor headers following the CMSIS standard
core Board independent drivers required for the OS to function (roughly)
atomic_ops_*.h Core dependent
cache_*.cpp/h Core dependent. This is not required at all for Miosix to work but is nevertheless here
*_os_timer.cpp Chip family dependent
endianness_*.h Core dependent. Should have a generic (slow) implementation but it's missing.
interrupts.h Umbrella header for interrupts_*.h
interrupts_*.h Core dependent. Misleading name, this is for fault handling.
memory_protection.h Umbrella header for mpu_*.h. Required only for process mode. Name is not consistent with other umbrella headers, should have been "mpu.h"
mpu_*.cpp/h Core dependent.
drivers Miscellaneous drivers, which are "common" only very roughly
dcc.cpp/h Core dependent (but common to all ARM cores apparently)
*_adc.cpp/h Chip family dependent
serial.h Umbrella header for *serial*.h
*serial*.cpp/h Chip family dependent
sd_*.cpp/h Chip family dependent
servo_*.cpp/h Board dependent really, should go into utils
*_hardware_rng.cpp/h Chip family dependent
*_rtc.cpp/h Chip family dependent
*_sgm.cpp/h Chip family dependent
*_wd.cpp/h Chip family dependent
*_i2c.cpp/h Chip family dependent
<board group name> Board group specific files.
common Common drivers and configuration for all the boards in the group
arch_settings.h Core dependent. Misleading name, defines requirements for ctxsave
interfaces-impl The actual drivers, most of them required by Miosix to function.
arch_registers_impl.h Chip family dependent. Includes the appropriate register definitions
delays.cpp Chip family dependent as it also depends on ROM/Flash speed. Actually application dependent (!) as cache/prefetch mechanisms can be configured but whatever.
gpio_impl.cpp/h Chip family dependent.
portability_impl.h Core dependent.
portability.cpp Core dependent.
drivers Miscellaneous drivers not required by Miosix to function, with exceptions (atsam4l clock)
*.cpp/h
<board name> Board/chip specific files.
core Board/chip dependent code required for the OS to function.
stage_1_boot.c/cpp/s Chip dependent. Interrupt vector table, reset handler, clock tree setup, bss/data initialization
interfaces_impl Important board/chip specific drivers, most of them required by Miosix to function.
bsp_impl.h Board dependent. Useful board-specific definitions.
bsp.cpp Board dependent. Useful board-specific functions.
hwmapping.h Board dependent. GPIO pin definitions.
deep_sleep.cpp Chip family dependent. Optional implementation of deep sleep primitives.
delays.cpp See above. Sometimes it's here, with no true reason why.
arch_registers_impl.h See above. Sometimes it's here, depends on chip.
... Some boards have extra miscellaneous drivers here
*.h Some boards have chip registers definitions here (LPC2138)
*.cfg Some boards have OpenOCD config files here
*.ld Chip family specific. Linker files for different RAM/Flash configurations
interfaces Headers for hardware interfaces TO miosix (internals) and SOME interfaces OF miosix to the application (APIs). Only commonality is that they are all hardware dependent (while stuff in utils/kernel is ''generally'' hardware independent)
arch_registers.h API. Umbrella for "arch_registers_impl.h", selected through include search path manipulation.
atomic_ops.h API. Umbrella for "atomic_ops_*.h", selected through ifdefs.
bsp.h API + internal prototypes (IRQbspInit, bspInit2). Umbrella for "bsp_impl.h", selected through include search path manipulation.
deep_sleep.h Internal prototypes only. Not an umbrella header.
delays.h API. Not an umbrella header.
endianness.h API. Umbrella for "endianness_*.h", selected through ifdefs.
gpio.h API. Umbrella for "gpio_impl.h", selected through include search path manipulation.
os_timer.h Internal declarations. Not an umbrella header.
portability.h Internal declarations. Primitives for context switching and syscalls. Umbrella for "portability_impl.h", selected through include search path manipulation.
util Additional APIs made available for applications as utilities, built on top of kernel primitives or other drivers
lcd44780.cpp/h Driver for Hitachi-standard HD44780 character displays.
software_i2c/spi.h Bit-banged i2c/spi implementations. Arguably drivers.
utils.cpp/h Memory/CPU usage profiling. Misleading name. Not a driver
... Other files are not related to hardware
config Configuration files, user-modifiable
Makefile.inc List of board + selection of board to build for + selection of compile time options through defines passed as argument to the compiler. The first section of the file arguably is not user-modifiable configuration.
miosix-settings.h Global settings selected through defines in header files
arch Board-dependent settings
<board group>
<board>
board_settings.h Board-dependent settings selected through defines in header files
</pre>

''<board group name>'' is defined as the name of the chip core, followed by an underscore, followed by the name of a chip family. ''<board name>'' is defined by the name of the chip, followed by an underscore, followed by a "common name" of the board. For commercial prototyping boards or specific devices, "common name" is derived from the name given by the manufacturer, or a name which is in common use with some exceptions (i.e. stm32f103 bluepill boards are named "breakout").

Some general patterns can be inferred:
* Apart from minor exceptions, directories named '''core''' contain drivers required for the OS to function.
* Directories named '''interfaces_impl''' generally contain implementations of things defined in /interfaces. Header files in '''interfaces_impl''' are always given the ``_impl`` suffix. C++ files are usually not given the "_impl" suffix but sometimes they have it (gpio_impl.cpp).
* Directories named '''common''' contain code shared by multiple boards. No attempt is made to separate different levels of commonality apart from chip-family specific stuff which is grouped by board group.

=== Include paths ===

The current directory structure allows the Makefile to select the implementation of some file by solely changing the include search paths of the compiler. This mostly applies to files in ''<board group name>/<board name>'' and in ''<board group name>/config''. The Makefile defines several variables that are used to refer to specific paths in the directory tree:

{| class="wikitable"
|-
! Variable !! Value Pattern !! Scope !! Is config !! Defined by !! Description
|-
| LINKER_SCRIPT_PATH || arch/<board group name>/<board name>/ || Board || Yes || Makefile.inc || Directory where the linker scripts are found
|-
| LINKER_SCRIPT || $(LINKER_SCRIPT_PATH)/<script>.ld || Board || Yes || Makefile.inc || Path of the linker script
|-
| ARCH_INC || arch/<board group name>/common || Board group || No || Makefile.inc || Path of the common directory of the board group
|-
| BOARD_INC || arch/<board group name>/<board name> || Board || No || Makefile.inc || Path of the board directory
|-
| BOOT_FILE || $(BOARD_INC)/core/stage_1_boot.o || Board || No || Makefile.inc || Path of the object file for the board bootstrap code
|-
| ARCH_SRC || $(BOARD_INC)/*/*.cpp $(ARCH_INC)/*/*.cpp arch/common/drivers/*.cpp || Board + Board group || No || Sources for the drivers enabled for this board
|-
| KPATH || miosix || Global || Yes || Appl. Makefile || Root directory of the kernel files
|-
| CONFPATH || $(KPATH) || Global || Yes || Appl. Makefile || Root directory for configuration files
|}

For reference, the final include paths, defined by the application makefile, are:
<pre>
$(CONFPATH)
$(CONFPATH)/config/$(BOARD_INC)
$(KPATH)
$(KPATH)/arch/common
$(KPATH)/$(ARCH_INC)
$(KPATH)/$(BOARD_INC)
</pre>

Notice that, despite the name of the defines, there is no distinction between include paths and source paths, as includes are alongside the source. We do not have a problem with this approach, however it results in all includes being publicly available for applications, which is something that is not entirely desirable.

==== Drivers selected by include path ====

Sometimes Miosix's headers include files that depend on the board selected for building. This of course can give problems when reorganizing files around. The affected files are:

* interfaces/arch_registers.h
* interfaces/bsp.h
* interfaces/gpio.h
* interfaces/portability.h

Overall selecting different files through the include paths is desirable, so we want to avoid adding additional architecture-specific ifdefs as much as possible.

=== Issues ===

Experience has shown this organization has the following problems:
* What goes where is not well defined due to the vagueness of directory names
** This leads to files being in the wrong place even though it's not obvious
*** servo_* is the most glaring example
*** The location of delays.cpp and arch_registers_impl.h is also inconsistent
* The two level board group/board classification does not reflect reality, which leads to missing code sharing opportunities:
** GPIO implementations are duplicated multiple times as they are common to multiple chip families and not to a single one.
** Bootstrap code is duplicated multiple times as they are common to boards with the same chip and not common to the board.
** Portability code (i.e. context save/restore primitives mostly) is duplicated multiple times as they are common to a given core and not to a chip family
** Linker scripts are also duplicated multiple times
* Classifications sometimes privilege syntax rather than semantics, in an inconsistent fashion
** Directories named '''interfaces_impl''' contain drivers just like directories named '''drivers''', except that they included from /interfaces.
** What is '''common''' and what is not loosely determined by the amount of code sharing but most stuff not under a '''common''' directory is duplicated at least twice

Of course, the root issue is the fluidity of the distinction between chip and chip family, and how each vendor manages and/or defines each family. For instance, STM32 chips all have similar USART (serial) implementations, but at least two versions can be distinguished through different register definitions and feature sets. Therefore the same overall driver can be shared across almost all STM32 chips, however the driver is littered with ''ifdef''s to single out the specificity of each implementation. There is really no strict distinction to what can be found where, as the vendors can and do mix and match peripherals even amongst themselves. For example, some STM32 chips have Synopsis-designed USB interfaces which can also be found on chips from vendors that are not ST.

These considerations highlight that the solution to handling the issue of organizing platform-specific code in a consistent way to '''minimize code duplication''' is not to '''add''' hierarchy levels, but to remove them. This runs contrary from the naive consideration that "Board includes Chip, which belongs to Chip Family, which contains a Core".

== A proposal ==

Pointing out what's wrong is easy, fixing it up is hard. Of course "what we should do" is a matter of opinion, and a valid answer to that could even be "nothing". Overall, what we ultimately want is for all drivers to be decoupled from boards and board groups, in order to be able to classify each driver depending on its actual logical group it belongs to. We can take this opportunity for a more radical restructuring of Miosix's source tree, or we can opt for more conservative solutions.

=== With classification per device type ===

This proposal is the most radical as it splits the drivers in a completely different way than what is currently done: by device type. For instance all USART drivers go in a "serial" directory, all GPIO drivers go in a GPIO directory, and so on. This approach scales well when there are a lot of drivers around, but completely prevents selection of drivers by using the include paths.

The arch directory has been named "platform" because of our general dislike of the "architecture" word, but that's really just a bonus. Most other operating systems use "arch" as a directory for drivers and target-specific stuff, so keeping the name "arch" is also an option. We also moved the interfaces headers under the "platform" ("arch") directory, since they basically are just umbrella headers for various drivers. This loses the distinction of some of them being more essential than others, additional directories can be added for this purpose.

<pre>
platform
arch_registers.h
atomic_ops.h
bsp.h
deep_sleep.h
delays.h
endianness.h
gpio.h
os_timer.h
portability.h
memory_protection.h
interrupts.h
mpu.h
serial.h
arch_registers
CMSIS
<chip/chip family>
arch_registers_impl.h
....h
core
boot
<chip>
stage_1_boot.c/cpp/s
atomic_ops
atomic_ops_*.h
os_timer
*_os_timer.cpp
endianness
endianness_*.h
faults
interrupts_*.h
mpu
*_mpu.cpp/h
portability
<core>
arch_settings.h
portability_impl.h
portability.cpp
gpio
<chip/chip family>
gpio_impl.cpp/h
delays
<chip/chip family>
delays.cpp
drivers
arm_dcc.cpp/h
deep_sleep
deep_sleep.cpp
cache
cache_*.cpp/h
serial
*_serial.cpp/h
adc
*_adc.cpp/h
sd
*_sd.cpp/h
servo
*_servo.cpp/h
hardware_rng
*_hardware_rng.cpp/h
rtc
*_rtc.cpp/h
sgm
*_sgm.cpp/h
wd
*_wd.cpp/h
i2c
*_i2c.cpp/h
software_i2c.h
spi
software_spi.h
display
lcd44780.cpp/h
...
board
<board>
bsp_impl.h
bsp.cpp
hwmapping.h
*.cfg
linker_scripts
<chip>
*.ld
config
Makefile.inc
miosix_settings.h
<board>
board_settings.h
</pre>

=== Without classification per device type ===

This is just the same proposal as before but which classifies drivers only by "manufacturer" or chip. This allows to use the include trick for selecting headers.

<pre>
platform
arch_registers.h
atomic_ops.h
bsp.h
deep_sleep.h
delays.h
endianness.h
gpio.h
os_timer.h
portability.h
memory_protection.h
interrupts.h
mpu.h
serial.h
arch_registers
CMSIS
<chip/chip family>
arch_registers_impl.h
....h
core
<chip/chip family>
stage_1_boot.c/cpp/s
*_os_timer.cpp
*_mpu.cpp/h
gpio_impl.cpp/h
delays.cpp
<core>
atomic_ops_*.h
endianness_*.h
interrupts_*.h
arch_settings.h
portability_impl.h
portability.cpp
drivers
dcc.cpp/h
*_servo.cpp/h
software_i2c.h
software_spi.h
lcd44780.cpp/h
<core>
cache_*.cpp/h
<chip/chip family>
deep_sleep.cpp
*_serial.cpp/h
*_adc.cpp/h
*_sd.cpp/h
*_hardware_rng.cpp/h
*_rtc.cpp/h
*_sgm.cpp/h
*_wd.cpp/h
*_i2c.cpp/h
...
board
<board>
bsp_impl.h
bsp.cpp
hwmapping.h
*.cfg
linker_scripts
<chip>
*.ld
config
Makefile.inc
miosix_settings.h
<board>
board_settings.h
</pre>

=== With minimal changes to the existing structure ===

<pre>
arch
common
CMSIS
core
boot
<chip>_stage_1_boot.c/cpp/s
<core>_portability
arch_settings.h
portability_impl.h
portability.cpp
<chip family>
delays.cpp
gpio_impl.cpp/h
deep_sleep.cpp
(all other existing files)
drivers
All miscellaneous drivers in board directory are moved here
(all other existing files)
linker_scripts
<chip>
*.ld
<board group name>
common
(should now be empty)
<board name>
interfaces_impl
bsp_impl.h
bsp.cpp
hwmapping.h
*.cfg
interfaces Unmodified
config Unmodified
</pre>

Arch directory restructuring

2023-11-16T09:13:19Z

Daniele.cattaneo:

The ''arch'' directory is a mess with lots of copy-pasted code. Ideally it should be '''consistently and logically organized''': each directory should have a documented purpose in order to leave as little doubt as possible about ''what goes where''. Additionally, each directory's purpose makes sense in the overall structure, without overlaps between the scope of each directory.
At the moment however we observe this is not the case. We believe that in order to make the future growth of Miosix simpler and faster, the right moment to rectify the situation is now.

== Some definitions ==

Common sense suggests the following taxonomy of parts for MCU-equipped devices targeted by Miosix:
* Board: The device itself being targeted. It's called a board because nobody has observed any MCU wired with point-to-point wiring yet. Includes the MCU itself plus any peripheral external to the MCU but '''driven''' by it.
* Chip: The MCU itself. May come in RAM/OTP/ROM/Flash size variations, which are mostly ignored.
* Chip family: A set of MCU types from the same manufacturer with the same microprocessor core but potentially different set of peripherals. While the available set of peripherals may vary, the behaviour and I/O ports of each kind of peripheral are the same across the entire family. Thanks to the brilliant ideas of the various marketing departments of each vendor, the classification here can get very fluid.
* Core: The microprocessor core used by a given chip family.

Let's take as an example the classic stm32f4discovery board that is the most common development device for Miosix:
* The board is the stm32f4discovery itself. It includes the chip, and miscellaneous peripherals such as an accelerometer and a Cirrus Logic audio chip. The STLink programming interface and the power supply are '''not''' considered relevant parts of the board for Miosix, as the MCU is not in control of what they do.
* The chip is an STM32F407VGT6. The VGT6 suffix of the chip name specifies package (100 pin LQFP), Flash size (1MB) and temperature range options (see the datasheet at the "Ordering Information" page).
* The chip family is STM32F4. This can be inferred by the fact that all available chips with this prefix in the part name share the same reference manual.
* The core is an ARM Cortex M4, as stated in the datasheet. Roughly, ST buys the Verilog for the core from ARM and then takes care of the manufacturing. As far as we know, ARM's licence shouldn't allow ST to customize the core in any way, so all Cortex M4 cores should behave the same, even from other vendors.

=== What is an architecture? ===

One definition we did not give is the definition of what an '''architecture''' is. The reason is that there is no accepted definition for this term, especially for forum pundits and bloggers, but also in academia. The RISC school of thought (Patterson/Hennessy and their spawn) historically associated an ''architecture'' with a combination of what are more specifically called the ''instruction set architecture'' (ISA) and the ''microarchitecture'' of a core. The ISA is the overall structure and design of the instructions, as opposed to the ''instruction set'' proper which is the set of instructions accepted by a specific core. The '''microarchitecture''' is the overall internal design of the core itself.

Their thesis was that the microarchitecture design will follow naturally from the definition of the ISA, hence simpler ISAs (RISC) to implement always lead to more efficient and generally better cores. Therefore one can consider the '''architecture''' to be primarily determined by the ISA. However the industry has proven them wrong, and the most glaring example are Intel x86 chips, which have seen an increasing variety of microarchitectures implementing the same ISA (variously extended of course) with wildly varying levels of (non-)efficiency (in all possible ramifications of "efficiency"). Closer to Miosix's targets, the ARM ISA has been extended so much over the years that its core RISC design has now evolved to basically a traditional CISC ISA, but ARM chips still come in every possible size and flavour.

When we talk about x86 "architectures" or ARM "architectures", but do we mean desktop-grade chips or microcontrollers? Even though they have the same "architecture" the cores in these two classes of chips have nothing to do with each other, they don't even share the same instruction decoder probably. Hence our conclusion that the word "architecture" has now lost all useful meaning for our purposes, and is only useful for void parlor chitchat.

And then we come to Miosix which defines "architecture" (arch) as... a board. Which is not what anyone means when they talk about architecture of anything. For Miosix, an "architecture" is more like what in common parlance would be meant as a "platform".

== Current structure ==

Here's a schematic diagram of how the Miosix ''arch'' directory (plus related directories) is configured. In the following ''/'' refers to the ''miosix'' directory at the top level of the repository.

<pre>
arch Architecture-specific files
common Pool of useful files. Very few files here are common to all archs.
CMSIS Collection of ARM & vendor headers following the CMSIS standard
core Board independent drivers required for the OS to function (roughly)
atomic_ops_*.h Core dependent
cache_*.cpp/h Core dependent. This is not required at all for Miosix to work but is nevertheless here
*_os_timer.cpp Chip family dependent
endianness_*.h Core dependent. Should have a generic (slow) implementation but it's missing.
interrupts.h Umbrella header for interrupts_*.h
interrupts_*.h Core dependent. Misleading name, this is for fault handling.
memory_protection.h Umbrella header for mpu_*.h. Required only for process mode. Name is not consistent with other umbrella headers, should have been "mpu.h"
mpu_*.cpp/h Core dependent.
drivers Miscellaneous drivers, which are "common" only very roughly
dcc.cpp/h Core dependent (but common to all ARM cores apparently)
*_adc.cpp/h Chip family dependent
serial.h Umbrella header for *serial*.h
*serial*.cpp/h Chip family dependent
sd_*.cpp/h Chip family dependent
servo_*.cpp/h Board dependent really, should go into utils
*_hardware_rng.cpp/h Chip family dependent
*_rtc.cpp/h Chip family dependent
*_sgm.cpp/h Chip family dependent
*_wd.cpp/h Chip family dependent
*_i2c.cpp/h Chip family dependent
<board group name> Board group specific files.
common Common drivers and configuration for all the boards in the group
arch_settings.h Core dependent. Misleading name, defines requirements for ctxsave
interfaces-impl The actual drivers, most of them required by Miosix to function.
arch_registers_impl.h Chip family dependent. Includes the appropriate register definitions
delays.cpp Chip family dependent as it also depends on ROM/Flash speed. Actually application dependent (!) as cache/prefetch mechanisms can be configured but whatever.
gpio_impl.cpp/h Chip family dependent.
portability_impl.h Core dependent.
portability.cpp Core dependent.
drivers Miscellaneous drivers not required by Miosix to function, with exceptions (atsam4l clock)
*.cpp/h
<board name> Board/chip specific files.
core Board/chip dependent code required for the OS to function.
stage_1_boot.c/cpp/s Chip dependent. Interrupt vector table, reset handler, clock tree setup, bss/data initialization
interfaces_impl Important board/chip specific drivers, most of them required by Miosix to function.
bsp_impl.h Board dependent. Useful board-specific definitions.
bsp.cpp Board dependent. Useful board-specific functions.
hwmapping.h Board dependent. GPIO pin definitions.
deep_sleep.cpp Chip family dependent. Optional implementation of deep sleep primitives.
delays.cpp See above. Sometimes it's here, with no true reason why.
arch_registers_impl.h See above. Sometimes it's here, depends on chip.
... Some boards have extra miscellaneous drivers here
*.h Some boards have chip registers definitions here (LPC2138)
*.cfg Some boards have OpenOCD config files here
*.ld Chip family specific. Linker files for different RAM/Flash configurations
interfaces Headers for hardware interfaces TO miosix (internals) and SOME interfaces OF miosix to the application (APIs). Only commonality is that they are all hardware dependent (while stuff in utils/kernel is ''generally'' hardware independent)
arch_registers.h API. Umbrella for "arch_registers_impl.h", selected through include search path manipulation.
atomic_ops.h API. Umbrella for "atomic_ops_*.h", selected through ifdefs.
bsp.h API + internal prototypes (IRQbspInit, bspInit2). Umbrella for "bsp_impl.h", selected through include search path manipulation.
deep_sleep.h Internal prototypes only. Not an umbrella header.
delays.h API. Not an umbrella header.
endianness.h API. Umbrella for "endianness_*.h", selected through ifdefs.
gpio.h API. Umbrella for "gpio_impl.h", selected through include search path manipulation.
os_timer.h Internal declarations. Not an umbrella header.
portability.h Internal declarations. Primitives for context switching and syscalls. Umbrella for "portability_impl.h", selected through include search path manipulation.
util Additional APIs made available for applications as utilities, built on top of kernel primitives or other drivers
lcd44780.cpp/h Driver for Hitachi-standard HD44780 character displays.
software_i2c/spi.h Bit-banged i2c/spi implementations. Arguably drivers.
utils.cpp/h Memory/CPU usage profiling. Misleading name. Not a driver
... Other files are not related to hardware
config Configuration files, user-modifiable
Makefile.inc List of board + selection of board to build for + selection of compile time options through defines passed as argument to the compiler. The first section of the file arguably is not user-modifiable configuration.
miosix-settings.h Global settings selected through defines in header files
arch Board-dependent settings
<board group>
<board>
board_settings.h Board-dependent settings selected through defines in header files
</pre>

''<board group name>'' is defined as the name of the chip core, followed by an underscore, followed by the name of a chip family. ''<board name>'' is defined by the name of the chip, followed by an underscore, followed by a "common name" of the board. For commercial prototyping boards or specific devices, "common name" is derived from the name given by the manufacturer, or a name which is in common use with some exceptions (i.e. stm32f103 bluepill boards are named "breakout").

Some general patterns can be inferred:
* Apart from minor exceptions, directories named '''core''' contain drivers required for the OS to function.
* Directories named '''interfaces_impl''' generally contain implementations of things defined in /interfaces. Header files in '''interfaces_impl''' are always given the ``_impl`` suffix. C++ files are usually not given the "_impl" suffix but sometimes they have it (gpio_impl.cpp).
* Directories named '''common''' contain code shared by multiple boards. No attempt is made to separate different levels of commonality apart from chip-family specific stuff which is grouped by board group.

=== Include paths ===

The current directory structure allows the Makefile to select the implementation of some file by solely changing the include search paths of the compiler. This mostly applies to files in ''<board group name>/<board name>'' and in ''<board group name>/config''. The Makefile defines several variables that are used to refer to specific paths in the directory tree:

{| class="wikitable"
|-
! Variable !! Value Pattern !! Scope !! Is config !! Defined by !! Description
|-
| LINKER_SCRIPT_PATH || arch/<board group name>/<board name>/ || Board || Yes || Makefile.inc || Directory where the linker scripts are found
|-
| LINKER_SCRIPT || $(LINKER_SCRIPT_PATH)/<script>.ld || Board || Yes || Makefile.inc || Path of the linker script
|-
| ARCH_INC || arch/<board group name>/common || Board group || No || Makefile.inc || Path of the common directory of the board group
|-
| BOARD_INC || arch/<board group name>/<board name> || Board || No || Makefile.inc || Path of the board directory
|-
| BOOT_FILE || $(BOARD_INC)/core/stage_1_boot.o || Board || No || Makefile.inc || Path of the object file for the board bootstrap code
|-
| ARCH_SRC || $(BOARD_INC)/*/*.cpp $(ARCH_INC)/*/*.cpp arch/common/drivers/*.cpp || Board + Board group || No || Sources for the drivers enabled for this board
|-
| KPATH || miosix || Global || Yes || Appl. Makefile || Root directory of the kernel files
|-
| CONFPATH || $(KPATH) || Global || Yes || Appl. Makefile || Root directory for configuration files
|}

For reference, the final include paths, defined by the application makefile, are:
<pre>
$(CONFPATH)
$(CONFPATH)/config/$(BOARD_INC)
$(KPATH)
$(KPATH)/arch/common
$(KPATH)/$(ARCH_INC)
$(KPATH)/$(BOARD_INC)
</pre>

Notice that, despite the name of the defines, there is no distinction between include paths and source paths, as includes are alongside the source. We do not have a problem with this approach, however it results in all includes being publicly available for applications, which is something that is not entirely desirable.

=== Issues ===

Experience has shown this organization has the following problems:
* What goes where is not well defined due to the vagueness of directory names
** This leads to files being in the wrong place even though it's not obvious
*** servo_* is the most glaring example
*** The location of delays.cpp and arch_registers_impl.h is also inconsistent
* The two level board group/board classification does not reflect reality, which leads to missing code sharing opportunities:
** GPIO implementations are duplicated multiple times as they are common to multiple chip families and not to a single one.
** Bootstrap code is duplicated multiple times as they are common to boards with the same chip and not common to the board.
** Portability code (i.e. context save/restore primitives mostly) is duplicated multiple times as they are common to a given core and not to a chip family
* Classifications sometimes privilege syntax rather than semantics, in an inconsistent fashion
** Directories named '''interfaces_impl''' contain drivers just like directories named '''drivers''', except that they included from /interfaces.
** What is '''common''' and what is not loosely determined by the amount of code sharing but most stuff not under a '''common''' directory is duplicated at least twice

Of course, the root issue is the fluidity of the distinction between chip and chip family, and how each vendor manages and/or defines each family. For instance, STM32 chips all have similar USART (serial) implementations, but at least two versions can be distinguished through different register definitions and feature sets. Therefore the same overall driver can be shared across almost all STM32 chips, however the driver is littered with ''ifdef''s to single out the specificity of each implementation. There is really no strict distinction to what can be found where, as the vendors can and do mix and match peripherals even amongst themselves. For example, some STM32 chips have Synopsis-designed USB interfaces which can also be found on chips from vendors that are not ST.

These considerations highlight that the solution to handling the issue of organizing platform-specific code in a consistent way to '''minimize code duplication''' is not to '''add''' hierarchy levels, but to remove them. This runs contrary from the naive consideration that "Board includes Chip, which belongs to Chip Family, which contains a Core".

== A proposal ==

Pointing out what's wrong is easy, fixing it up is hard. Of course "what we should do" is a matter of opinion, and a valid answer to that could even be "nothing". If I were to do something, I would do the following:

=== With classification per device type ===

<pre>
platform
arch_registers.h
atomic_ops.h
bsp.h
deep_sleep.h
delays.h
endianness.h
gpio.h
os_timer.h
portability.h
memory_protection.h
interrupts.h
mpu.h
serial.h
arch_registers
CMSIS
<chip/chip family>
arch_registers_impl.h
....h
core
boot
<chip>
stage_1_boot.c/cpp/s
atomic_ops
atomic_ops_*.h
os_timer
*_os_timer.cpp
endianness
endianness_*.h
faults
interrupts_*.h
mpu
*_mpu.cpp/h
portability
<core>
arch_settings.h
portability_impl.h
portability.cpp
gpio
<chip/chip family>
gpio_impl.cpp/h
delays
<chip/chip family>
delays.cpp
drivers
arm_dcc.cpp/h
deep_sleep
deep_sleep.cpp
cache
cache_*.cpp/h
serial
*_serial.cpp/h
adc
*_adc.cpp/h
sd
*_sd.cpp/h
servo
*_servo.cpp/h
hardware_rng
*_hardware_rng.cpp/h
rtc
*_rtc.cpp/h
sgm
*_sgm.cpp/h
wd
*_wd.cpp/h
i2c
*_i2c.cpp/h
software_i2c.h
spi
software_spi.h
display
lcd44780.cpp/h
...
board
<board>
bsp_impl.h
bsp.cpp
hwmapping.h
*.cfg
linker_scripts
<chip>
*.ld
config
Makefile.inc
miosix_settings.h
<board>
board_settings.h
</pre>

=== Without classification per device type ===

<pre>
platform
arch_registers.h
atomic_ops.h
bsp.h
deep_sleep.h
delays.h
endianness.h
gpio.h
os_timer.h
portability.h
memory_protection.h
interrupts.h
mpu.h
serial.h
arch_registers
CMSIS
<chip/chip family>
arch_registers_impl.h
....h
core
<chip/chip family>
stage_1_boot.c/cpp/s
*_os_timer.cpp
*_mpu.cpp/h
gpio_impl.cpp/h
delays.cpp
<core>
atomic_ops_*.h
endianness_*.h
interrupts_*.h
arch_settings.h
portability_impl.h
portability.cpp
drivers
dcc.cpp/h
*_servo.cpp/h
software_i2c.h
software_spi.h
lcd44780.cpp/h
<core>
cache_*.cpp/h
<chip/chip family>
deep_sleep.cpp
*_serial.cpp/h
*_adc.cpp/h
*_sd.cpp/h
*_hardware_rng.cpp/h
*_rtc.cpp/h
*_sgm.cpp/h
*_wd.cpp/h
*_i2c.cpp/h
...
board
<board>
bsp_impl.h
bsp.cpp
hwmapping.h
*.cfg
linker_scripts
<chip>
*.ld
config
Makefile.inc
miosix_settings.h
<board>
board_settings.h
</pre>

=== With minimal changes to the existing structure ===

<pre>
arch
common
CMSIS
core
boot
<chip>_stage_1_boot.c/cpp/s
<core>_portability
arch_settings.h
portability_impl.h
portability.cpp
<chip family>
delays.cpp
gpio_impl.cpp/h
deep_sleep.cpp
(all other existing files)
drivers
All miscellaneous drivers in board directory are moved here
(all other existing files)
linker_scripts
<chip>
*.ld
<board group name>
common
(should now be empty)
<board name>
interfaces_impl
bsp_impl.h
bsp.cpp
hwmapping.h
*.cfg
interfaces Unmodified
config Unmodified
</pre>

Arch directory restructuring

2023-11-13T15:44:25Z

Daniele.cattaneo: Start of proposal

The ''arch'' directory is a mess with lots of copy-pasted code. Ideally it should be '''consistently and logically organized''': each directory should have a documented purpose in order to leave as little doubt as possible about ''what goes where''. Additionally, each directory's purpose makes sense in the overall structure, without overlaps between the scope of each directory.
At the moment however we observe this is not the case. We believe that in order to make the future growth of Miosix simpler and faster, the right moment to rectify the situation is now.

== Some definitions ==

Common sense suggests the following taxonomy of parts for MCU-equipped devices targeted by Miosix:
* Board: The device itself being targeted. It's called a board because nobody has observed any MCU wired with point-to-point wiring yet. Includes the MCU itself plus any peripheral external to the MCU but '''driven''' by it.
* Chip: The MCU itself. May come in RAM/OTP/ROM/Flash size variations, which are mostly ignored.
* Chip family: A set of MCU types from the same manufacturer with the same microprocessor core but potentially different set of peripherals. While the available set of peripherals may vary, the behaviour and I/O ports of each kind of peripheral are the same across the entire family. Thanks to the brilliant ideas of the various marketing departments of each vendor, the classification here can get very fluid.
* Core: The microprocessor core used by a given chip family.

Let's take as an example the classic stm32f4discovery board that is the most common development device for Miosix:
* The board is the stm32f4discovery itself. It includes the chip, and miscellaneous peripherals such as an accelerometer and a Cirrus Logic audio chip. The STLink programming interface and the power supply are '''not''' considered relevant parts of the board for Miosix, as the MCU is not in control of what they do.
* The chip is an STM32F407VGT6. The VGT6 suffix of the chip name specifies package (100 pin LQFP), Flash size (1MB) and temperature range options (see the datasheet at the "Ordering Information" page).
* The chip family is STM32F4. This can be inferred by the fact that all available chips with this prefix in the part name share the same reference manual.
* The core is an ARM Cortex M4, as stated in the datasheet. Roughly, ST buys the Verilog for the core from ARM and then takes care of the manufacturing. As far as we know, ARM's licence shouldn't allow ST to customize the core in any way, so all Cortex M4 cores should behave the same, even from other vendors.

=== What is an architecture? ===

One definition we did not give is the definition of what an '''architecture''' is. The reason is that there is no accepted definition for this term, especially for forum pundits and bloggers, but also in academia. The RISC school of thought (Patterson/Hennessy and their spawn) historically associated an ''architecture'' with a combination of what are more specifically called the ''instruction set architecture'' (ISA) and the ''microarchitecture'' of a core. The ISA is the overall structure and design of the instructions, as opposed to the ''instruction set'' proper which is the set of instructions accepted by a specific core. The '''microarchitecture''' is the overall internal design of the core itself.

Their thesis was that the microarchitecture design will follow naturally from the definition of the ISA, hence simpler ISAs (RISC) to implement always lead to more efficient and generally better cores. Therefore one can consider the '''architecture''' to be primarily determined by the ISA. However the industry has proven them wrong, and the most glaring example are Intel x86 chips, which have seen an increasing variety of microarchitectures implementing the same ISA (variously extended of course) with wildly varying levels of (non-)efficiency (in all possible ramifications of "efficiency"). Closer to Miosix's targets, the ARM ISA has been extended so much over the years that its core RISC design has now evolved to basically a traditional CISC ISA, but ARM chips still come in every possible size and flavour.

When we talk about x86 "architectures" or ARM "architectures", but do we mean desktop-grade chips or microcontrollers? Even though they have the same "architecture" the cores in these two classes of chips have nothing to do with each other, they don't even share the same instruction decoder probably. Hence our conclusion that the word "architecture" has now lost all useful meaning for our purposes, and is only useful for void parlor chitchat.

And then we come to Miosix which defines "architecture" (arch) as... a board. Which is not what anyone means when they talk about architecture of anything. For Miosix, an "architecture" is more like what in common parlance would be meant as a "platform".

== Current structure ==

Here's a schematic diagram of how the Miosix ''arch'' directory (plus related directories) is configured. In the following ''/'' refers to the ''miosix'' directory at the top level of the repository.

<pre>
arch Architecture-specific files
common Pool of useful files. Very few files here are common to all archs.
CMSIS Collection of ARM & vendor headers following the CMSIS standard
core Board independent drivers required for the OS to function (roughly)
atomic_ops_*.h Core dependent
cache_*.cpp/h Core dependent. This is not required at all for Miosix to work but is nevertheless here
*_os_timer.cpp Chip family dependent
endianness_*.h Core dependent. Should have a generic (slow) implementation but it's missing.
interrupts.h Umbrella header for interrupts_*.h
interrupts_*.h Core dependent. Misleading name, this is for fault handling.
memory_protection.h Umbrella header for mpu_*.h. Required only for process mode. Name is not consistent with other umbrella headers, should have been "mpu.h"
mpu_*.cpp/h Core dependent.
drivers Miscellaneous drivers, which are "common" only very roughly
dcc.cpp/h Core dependent (but common to all ARM cores apparently)
*_adc.cpp/h Chip family dependent
serial.h Umbrella header for *serial*.h
*serial*.cpp/h Chip family dependent
sd_*.cpp/h Chip family dependent
servo_*.cpp/h Board dependent really, should go into utils
*_hardware_rng.cpp/h Chip family dependent
*_rtc.cpp/h Chip family dependent
*_sgm.cpp/h Chip family dependent
*_wd.cpp/h Chip family dependent
*_i2c.cpp/h Chip family dependent
<board group name> Board group specific files.
common Common drivers and configuration for all the boards in the group
arch_settings.h Core dependent. Misleading name, defines requirements for ctxsave
interfaces-impl The actual drivers, most of them required by Miosix to function.
arch_registers_impl.h Chip family dependent. Includes the appropriate register definitions
delays.cpp Chip family dependent as it also depends on ROM/Flash speed. Actually application dependent (!) as cache/prefetch mechanisms can be configured but whatever.
gpio_impl.cpp/h Chip family dependent.
portability_impl.h Core dependent.
portability.cpp Core dependent.
drivers Miscellaneous drivers not required by Miosix to function, with exceptions (atsam4l clock)
*.cpp/h
<board name> Board/chip specific files.
core Board/chip dependent code required for the OS to function.
stage_1_boot.c/cpp/s Chip dependent. Interrupt vector table, reset handler, clock tree setup, bss/data initialization
interfaces_impl Important board/chip specific drivers, most of them required by Miosix to function.
bsp_impl.h Board dependent. Useful board-specific definitions.
bsp.cpp Board dependent. Useful board-specific functions.
hwmapping.h Board dependent. GPIO pin definitions.
deep_sleep.cpp Chip family dependent. Optional implementation of deep sleep primitives.
delays.cpp See above. Sometimes it's here, with no true reason why.
arch_registers_impl.h See above. Sometimes it's here, depends on chip.
... Some boards have extra miscellaneous drivers here
*.h Some boards have chip registers definitions here (LPC2138)
*.cfg Some boards have OpenOCD config files here
*.ld Chip family specific. Linker files for different RAM/Flash configurations
interfaces Headers for hardware interfaces TO miosix (internals) and SOME interfaces OF miosix to the application (APIs). Only commonality is that they are all hardware dependent (while stuff in utils/kernel is ''generally'' hardware independent)
arch_registers.h API. Umbrella for "arch_registers_impl.h", selected through include search path manipulation.
atomic_ops.h API. Umbrella for "atomic_ops_*.h", selected through ifdefs.
bsp.h API + internal prototypes (IRQbspInit, bspInit2). Umbrella for "bsp_impl.h", selected through include search path manipulation.
deep_sleep.h Internal prototypes only. Not an umbrella header.
delays.h API. Not an umbrella header.
endianness.h API. Umbrella for "endianness_*.h", selected through ifdefs.
gpio.h API. Umbrella for "gpio_impl.h", selected through include search path manipulation.
os_timer.h Internal declarations. Not an umbrella header.
portability.h Internal declarations. Primitives for context switching and syscalls. Umbrella for "portability_impl.h", selected through include search path manipulation.
util Additional APIs made available for applications as utilities, built on top of kernel primitives or other drivers
lcd44780.cpp/h Driver for Hitachi-standard HD44780 character displays.
software_i2c/spi.h Bit-banged i2c/spi implementations. Arguably drivers.
utils.cpp/h Memory/CPU usage profiling. Misleading name. Not a driver
... Other files are not related to hardware
</pre>

''<board group name>'' is defined as the name of the chip core, followed by an underscore, followed by the name of a chip family. ''<board name>'' is defined by the name of the chip, followed by an underscore, followed by a "common name" of the board. For commercial prototyping boards or specific devices, "common name" is derived from the name given by the manufacturer, or a name which is in common use with some exceptions (i.e. stm32f103 bluepill boards are named "breakout").

Some general patterns can be inferred:
* Apart from minor exceptions, directories named '''core''' contain drivers required for the OS to function.
* Directories named '''interfaces_impl''' generally contain implementations of things defined in /interfaces. Header files in '''interfaces_impl''' are always given the ``_impl`` suffix. C++ files are usually not given the "_impl" suffix but sometimes they have it (gpio_impl.cpp).
* Directories named '''common''' contain code shared by multiple boards. No attempt is made to separate different levels of commonality apart from chip-family specific stuff which is grouped by board group.

=== Issues ===

Experience has shown this organization has the following problems:
* What goes where is not well defined due to the vagueness of directory names
** This leads to files being in the wrong place even though it's not obvious
*** servo_* is the most glaring example
*** The location of delays.cpp and arch_registers_impl.h is also inconsistent
* The two level board group/board classification does not reflect reality, which leads to missing code sharing opportunities:
** GPIO implementations are duplicated multiple times as they are common to multiple chip families and not to a single one.
** Bootstrap code is duplicated multiple times as they are common to boards with the same chip and not common to the board.
** Portability code (i.e. context save/restore primitives mostly) is duplicated multiple times as they are common to a given core and not to a chip family
* Classifications sometimes privilege syntax rather than semantics, in an inconsistent fashion
** Directories named '''interfaces_impl''' contain drivers just like directories named '''drivers''', except that they included from /interfaces.
** What is '''common''' and what is not loosely determined by the amount of code sharing but most stuff not under a '''common''' directory is duplicated at least twice

Of course, the root issue is the fluidity of the distinction between chip and chip family, and how each vendor manages and/or defines each family. For instance, STM32 chips all have similar USART (serial) implementations, but at least two versions can be distinguished through different register definitions and feature sets. Therefore the same overall driver can be shared across almost all STM32 chips, however the driver is littered with ''ifdef''s to single out the specificity of each implementation. There is really no strict distinction to what can be found where, as the vendors can and do mix and match peripherals even amongst themselves. For example, some STM32 chips have Synopsis-designed USB interfaces which can also be found on chips from vendors that are not ST.

These considerations highlight that the solution to handling the issue of organizing platform-specific code in a consistent way to '''minimize code duplication''' is not to '''add''' hierarchy levels, but to remove them. This runs contrary from the naive consideration that "Board includes Chip, which belongs to Chip Family, which contains a Core".

== A proposal ==

Pointing out what's wrong is easy, fixing it up is hard. Of course "what we should do" is a matter of opinion, and a valid answer to that could even be "nothing". If I were to do something, I would do the following:

=== With classification per device type ===

<pre>
platform
arch_registers.h
atomic_ops.h
bsp.h
deep_sleep.h
delays.h
endianness.h
gpio.h
os_timer.h
portability.h
memory_protection.h
interrupts.h
mpu.h
serial.h
arch_registers
CMSIS
<chip/chip family>
arch_registers_impl.h
....h
core
boot
<chip>
stage_1_boot.c/cpp/s
atomic_ops
atomic_ops_*.h
os_timer
*_os_timer.cpp
endianness
endianness_*.h
faults
interrupts_*.h
mpu
*_mpu.cpp/h
portability
<core>
arch_settings.h
portability_impl.h
portability.cpp
gpio
<chip/chip family>
gpio_impl.cpp/h
delays
<chip/chip family>
delays.cpp
drivers
arm_dcc.cpp/h
deep_sleep
deep_sleep.cpp
cache
cache_*.cpp/h
serial
*_serial.cpp/h
adc
*_adc.cpp/h
sd
*_sd.cpp/h
servo
*_servo.cpp/h
hardware_rng
*_hardware_rng.cpp/h
rtc
*_rtc.cpp/h
sgm
*_sgm.cpp/h
wd
*_wd.cpp/h
i2c
*_i2c.cpp/h
software_i2c.h
spi
software_spi.h
display
lcd44780.cpp/h
...
board
<board>
bsp_impl.h
bsp.cpp
hwmapping.h
*.cfg
linker_scripts
<chip>
*.ld
</pre>

=== Without classification per device type ===

<pre>
platform
arch_registers.h
atomic_ops.h
bsp.h
deep_sleep.h
delays.h
endianness.h
gpio.h
os_timer.h
portability.h
memory_protection.h
interrupts.h
mpu.h
serial.h
arch_registers
CMSIS
<chip/chip family>
arch_registers_impl.h
....h
core
<chip/chip family>
stage_1_boot.c/cpp/s
*_os_timer.cpp
*_mpu.cpp/h
gpio_impl.cpp/h
delays.cpp
<core>
atomic_ops_*.h
endianness_*.h
interrupts_*.h
arch_settings.h
portability_impl.h
portability.cpp
drivers
dcc.cpp/h
*_servo.cpp/h
software_i2c.h
software_spi.h
lcd44780.cpp/h
<core>
cache_*.cpp/h
<chip/chip family>
deep_sleep.cpp
*_serial.cpp/h
*_adc.cpp/h
*_sd.cpp/h
*_hardware_rng.cpp/h
*_rtc.cpp/h
*_sgm.cpp/h
*_wd.cpp/h
*_i2c.cpp/h
...
board
<board>
bsp_impl.h
bsp.cpp
hwmapping.h
*.cfg
linker_scripts
<chip>
*.ld
</pre>

Arch directory restructuring

2023-11-13T14:47:44Z

Daniele.cattaneo: More

Arch directory restructuring

2023-11-13T13:24:04Z

Daniele.cattaneo:

The ''arch'' directory is a mess with lots of copy-pasted code. Let's fix that!

== Some definitions ==

Common sense suggests the following taxonomy of parts for MCU-equipped devices targeted by Miosix:
* Board: The device itself being targeted. It's called a board because nobody has observed any MCU wired with point-to-point wiring yet. Includes the MCU itself plus any peripheral external to the MCU but '''driven''' by it.
* Chip: The MCU itself. May come in RAM/OTP/ROM/Flash size variations, which are mostly ignored.
* Chip family: A set of MCU types from the same manufacturer with the same microprocessor core but potentially different set of peripherals. While the available set of peripherals may vary, the behaviour and I/O ports of each kind of peripheral are the same across the entire family. Thanks to the brilliant ideas of the various marketing departments of each vendor, the classification here can get very fluid.
* Core: The microprocessor core used by a given chip family.

Let's take as an example the classic stm32f4discovery board that is the most common development device for Miosix:
* The board is the stm32f4discovery itself. It includes the chip, and miscellaneous peripherals such as an accelerometer and a Cirrus Logic audio chip. The STLink programming interface and the power supply are '''not''' considered relevant parts of the board for Miosix, as the MCU is not in control of what they do.
* The chip is an STM32F407VGT6. The VGT6 suffix of the chip name specifies package (100 pin LQFP), Flash size (1MB) and temperature range options (see the datasheet at the "Ordering Information" page).
* The chip family is STM32F4. This can be inferred by the fact that all available chips with this prefix in the part name share the same reference manual.
* The core is an ARM Cortex M4, as stated in the datasheet. Roughly, ST buys the Verilog for the core from ARM and then takes care of the manufacturing. As far as we know, ARM's licence shouldn't allow ST to customize the core in any way, so all Cortex M4 cores should behave the same, even from other vendors.

One definition we did not give is the definition of what an '''architecture''' is. The reason is that there is no accepted definition for this term, especially for forum pundits and bloggers, but also in academia. The RISC school of thought (Patterson/Hennessy and their spawn) historically associated an ''architecture'' with a combination of what are more specifically called the ''instruction set architecture'' (ISA) and the ''microarchitecture'' of a core. Their thesis was that the microarchitecture design will follow naturally from the definition of the ISA, hence simpler ISAs (RISC) to implement always lead to more efficient and generally better cores. However the industry has proven them wrong, and the most glaring example are Intel x86 chips, which have seen an increasing variety of microarchitectures implementing the same ISA (variously extended of course) with wildly varying levels of (non-)efficiency (in all possible ramifications of "efficiency"). Closer to Miosix's targets, the ARM ISA has been extended so much over the years that its core RISC design has now evolved to basically a traditional CISC ISA, but ARM chips still come in every possible size and flavour. Usually we talk about x86 "architectures" or ARM "architectures", but do we mean desktop-grade chips or microcontrollers? Even though they have the same "architecture" the cores in these two classes of chips have nothing to do with each other, they don't even share the same instruction decoder probably. Hence our conclusion that the word "architecture" has now lost all useful meaning for our purposes, and is only useful for void parlor chitchat.

And then we come to Miosix which defines "architecture" (arch) as... a board. Which is not what anyone means when they talk about architecture of anything. For Miosix, an "architecture" is more like what in common parlance would be meant as a "platform".

== Current structure ==

<pre>
arch
common Pool of useful files. Very few files here are common to all archs.
CMSIS Collection of ARM & vendor headers following the CMSIS standard
core Board independent drivers required for the OS to function (roughly)
atomic_ops_*.h Core dependent
cache_*.cpp/h Core dependent. This is not required at all for Miosix to work but is nevertheless here
*_os_timer.cpp Chip family dependent
endianness_*.h Core dependent. Should have a generic (slow) implementation but it's missing.
interrupts.h Umbrella header for interrupts_*.h
interrupts_*.h Core dependent. Misleading name, this is for fault handling.
memory_protection.h Umbrella header for mpu_*.h. Required only for process mode. Name is not consistent with other umbrella headers, should have been "mpu.h"
mpu_*.cpp/h Core dependent.
drivers Miscellaneous drivers, which are "common" only very roughly
dcc.cpp/h Core dependent (but common to all ARM cores apparently)
*_adc.cpp/h Chip family dependent
serial.h Umbrella header for *serial*.h
*serial*.cpp/h Chip family dependent
sd_*.cpp/h Chip family dependent
servo_*.cpp/h Board dependent really, should go into utils
*_hardware_rng.cpp/h Chip family dependent
*_rtc.cpp/h Chip family dependent
*_sgm.cpp/h Chip family dependent
*_wd.cpp/h Chip family dependent
*_i2c.cpp/h Chip family dependent
<board group name> Board specific files.Board names are decided based on chip family but also include the core in their name
common Common drivers and configuration for all the boards in the group
arch_settings.h Core dependent. Misleading name, defines requirements for ctxsave
interfaces-impl The actual drivers
arch_registers_impl.h Chip family dependent. Includes the appropriate register definitions
delays.cpp Chip family dependent as it also depends on ROM/Flash speed. Actually application dependent (!) as cache/prefetch mechanisms can be configured but whatever.
gpio_impl.cpp/h Chip family dependent.
portability_impl.h Core dependent.
portability.cpp Core dependent.
<board name> Board/chip specific files.
core Board/chip dependent code required for the OS to function.
stage_1_boot.c/cpp/s Chip dependent. Interrupt vector table, reset handler, clock tree setup, bss/data initialization
interfaces_impl Board/chip specific drivers.
bsp_impl.h Board dependent. Useful board-specific definitions.
bsp.cpp Board dependent. Useful board-specific functions.
hwmapping.h Board dependent. GPIO pin definitions.
delays.cpp See above. Sometimes it's here, with no true reason why.
arch_registers_impl.h See above. Sometimes it's here, depends on chip.
... Some boards have extra miscellaneous drivers here
interfaces
</pre>

''<board group name>'' is defined as the name of the chip core, followed by an underscore, followed by the name of a chip family. ''<board name>'' is defined by the name of the chip, followed by an underscore, followed by a "common name" of the board. For commercial prototyping boards or specific devices, "common name" is derived from the name given by the manufacturer, or a name which is in common use with some exceptions (i.e. stm32f103 bluepill boards are named "breakout").

Some general patterns can be inferred:
* Apart from minor exceptions, directories named '''core''' contain drivers required for the OS to function.
* Directories named '''interfaces_impl''' generally contain implementations of things defined in /interfaces. Header files in '''interfaces_impl''' are always given the ``_impl`` suffix. C++ files are usually not given the "_impl" suffix but sometimes they have it (gpio_impl.cpp).
* Directories named '''common''' contain code shared by multiple boards. No attempt is made to separate different levels of commonality apart from chip-family specific stuff which is grouped by board group.

=== Issues ===

Experience has shown this organization has the following problems:
* What goes where is not well defined due to the vagueness of directory names, which leads to files being in the wrong place even though it's not obvious
** servo_* is the most glaring example
** The location of delays.cpp and arch_registers_impl.h is also inconsistent
* The two level board group/board classification does not reflect reality, which leads to missing code sharing opportunities:
** GPIO implementations are duplicated multiple times as they are common to multiple chip families and not to a single one.
** Bootstrap code is duplicated multiple times as they are common to boards with the same chip and not common to the board.
** Portability code (i.e. context save/restore primitives mostly) is duplicated multiple times as they are common to a given core and not to a chip family

Arch directory restructuring

2023-11-13T13:17:39Z

Daniele.cattaneo: Fix lists once again

The ''arch'' directory is a mess with lots of copy-pasted code. Let's fix that!

== Some definitions ==

Common sense suggests the following taxonomy of parts for MCU-equipped devices targeted by Miosix:
* Board: The device itself being targeted. It's called a board because nobody has observed any MCU wired with point-to-point wiring yet. Includes the MCU itself plus any peripheral external to the MCU but '''driven''' by it.
* Chip: The MCU itself. May come in RAM/OTP/ROM/Flash size variations, which are mostly ignored.
* Chip family: A set of MCU types from the same manufacturer with the same microprocessor core but potentially different set of peripherals. While the available set of peripherals may vary, the behaviour and I/O ports of each kind of peripheral are the same across the entire family. Thanks to the brilliant ideas of the various marketing departments of each vendor, the classification here can get very fluid.
* Core: The microprocessor core used by a given chip family.

Let's take as an example the classic stm32f4discovery board that is the most common development device for Miosix:
* The board is the stm32f4discovery itself. It includes the chip, and miscellaneous peripherals such as an accelerometer and a Cirrus Logic audio chip. The STLink programming interface and the power supply are '''not''' considered relevant parts of the board for Miosix, as the MCU is not in control of what they do.
* The chip is an STM32F407VGT6. The VGT6 suffix of the chip name specifies package (100 pin LQFP), Flash size (1MB) and temperature range options (see the datasheet at the "Ordering Information" page).
* The chip family is STM32F4. This can be inferred by the fact that all available chips with this prefix in the part name share the same reference manual.
* The core is an ARM Cortex M4, as stated in the datasheet. Roughly, ST buys the Verilog for the core from ARM and then takes care of the manufacturing. As far as we know, ARM's licence shouldn't allow ST to customize the core in any way, so all Cortex M4 cores should behave the same, even from other vendors.

One definition we did not give is the definition of what an '''architecture''' is. The reason is that there is no accepted definition for this term, especially for forum pundits and bloggers, but also in academia. The RISC school of thought (Patterson/Hennessy and their spawn) historically associated an ''architecture'' with a combination of what are more specifically called the ''instruction set architecture'' (ISA) and the ''microarchitecture'' of a core. Their thesis was that the microarchitecture design will follow naturally from the definition of the ISA, hence simpler ISAs (RISC) to implement always lead to more efficient and generally better cores. However the industry has proven them wrong, and the most glaring example are Intel x86 chips, which have seen an increasing variety of microarchitectures implementing the same ISA (variously extended of course) with wildly varying levels of (non-)efficiency (in all possible ramifications of "efficiency"). Closer to Miosix's targets, the ARM ISA has been extended so much over the years that its core RISC design has now evolved to basically a traditional CISC ISA, but ARM chips still come in every possible size and flavour. Usually we talk about x86 "architectures" or ARM "architectures", but do we mean desktop-grade chips or microcontrollers? Even though they have the same "architecture" the cores in these two classes of chips have nothing to do with each other, they don't even share the same instruction decoder probably. Hence our conclusion that the word "architecture" has now lost all useful meaning for our purposes, and is only useful for void parlor chitchat.

And then we come to Miosix which defines "architecture" (arch) as... a board. Which is not what anyone means when they talk about architecture of anything. For Miosix, an "architecture" is more like what in common parlance would be meant as a "platform".

== Current structure ==

<pre>
arch
common Pool of useful files. Very few files here are common to all archs.
CMSIS Collection of ARM & vendor headers following the CMSIS standard
core Board independent drivers required for the OS to function (roughly)
atomic_ops_*.h Core dependent
cache_*.cpp/h Core dependent. This is not required for Miosix but is nevertheless here
*_os_timer.cpp Chip family dependent
endianness_*.h Core dependent. Should have a generic (slow) implementation.
interrupts.h Umbrella header for interrupts_*.h
interrupts_*.h Core dependent. Misleading name, this is for fault handling.
memory_protection.h Umbrella header for mpu_*.h. Required only for process mode.
mpu_*.cpp/h Core dependent.
drivers Miscellaneous drivers, which are "common" only very roughly
dcc.cpp/h Core dependent (but common to all ARM cores apparently)
*_adc.cpp/h Chip family dependent
serial.h Umbrella header for *serial*.h
*serial*.cpp/h Chip family dependent
sd_*.cpp/h Chip family dependent
servo_*.cpp/h Board dependent really, should go into utils
*_hardware_rng.cpp/h Chip family dependent
*_rtc.cpp/h Chip family dependent
*_sgm.cpp/h Chip family dependent
*_wd.cpp/h Chip family dependent
*_i2c.cpp/h Chip family dependent
<board group name> Board specific files.Board names are decided based on chip family but also include the core in their name
common Common drivers and configuration for all the boards in the group
arch_settings.h Core dependent. Misleading name, defines requirements for ctxsave
interfaces-impl The actual drivers
arch_registers_impl.h Chip family dependent. Includes the appropriate register definitions
delays.cpp Chip family dependent as it also depends on ROM/Flash speed. Actually application dependent (!) as cache/prefetch mechanisms can be configured but whatever.
gpio_impl.cpp/h Chip family dependent.
portability_impl.h Core dependent.
portability.cpp Core dependent.
<board name> Board/chip specific files.
core Board/chip dependent code required for the OS to function.
stage_1_boot.c/cpp/s Chip dependent. Interrupt vector table, reset handler, clock tree setup, bss/data initialization
interfaces_impl Board/chip specific drivers.
bsp_impl.h Board dependent. Useful board-specific definitions.
bsp.cpp Board dependent. Useful board-specific functions.
hwmapping.h Board dependent. GPIO pin definitions.
delays.cpp See above. Sometimes it's here, with no true reason why.
arch_registers_impl.h See above. Sometimes it's here, depends on chip.
... Some boards have extra miscellaneous drivers here
interfaces
</pre>

''<board group name>'' is defined as the name of the chip core, followed by an underscore, followed by the name of a chip family. ''<board name>'' is defined by the name of the chip, followed by an underscore, followed by a "common name" of the board. For commercial prototyping boards or specific devices, "common name" is derived from the name given by the manufacturer, or a name which is in common use with some exceptions (i.e. stm32f103 bluepill boards are named "breakout").

Some general patterns can be inferred:
* Apart from minor exceptions, directories named '''core''' contain drivers required for the OS to function.
* Directories named '''interfaces_impl''' generally contain implementations of things defined in /interfaces. Header files in '''interfaces_impl''' are always given the ``_impl`` suffix. C++ files are usually not given the "_impl" suffix but sometimes they have it (gpio_impl.cpp).
* Directories named '''common''' contain code shared by multiple boards. No attempt is made to separate different levels of commonality apart from chip-family specific stuff which is grouped by board group.

=== Issues ===

Experience has shown this organization has the following problems:
* What goes where is not well defined due to the vagueness of directory names, which leads to files being in the wrong place even though it's not obvious
** servo_* is the most glaring example
** The location of delays.cpp and arch_registers_impl.h is also inconsistent
* The two level board group/board classification does not reflect reality, which leads to missing code sharing opportunities:
** GPIO implementations are duplicated multiple times as they are common to multiple chip families and not to a single one.
** Bootstrap code is duplicated multiple times as they are common to boards with the same chip and not common to the board.
** Portability code (i.e. context save/restore primitives mostly) is duplicated multiple times as they are common to a given core and not to a chip family

Arch directory restructuring

2023-11-13T13:16:47Z

Daniele.cattaneo: Fix lists

The ''arch'' directory is a mess with lots of copy-pasted code. Let's fix that!

== Some definitions ==

Common sense suggests the following taxonomy of parts for MCU-equipped devices targeted by Miosix:
* Board: The device itself being targeted. It's called a board because nobody has observed any MCU wired with point-to-point wiring yet. Includes the MCU itself plus any peripheral external to the MCU but '''driven''' by it.
* Chip: The MCU itself. May come in RAM/OTP/ROM/Flash size variations, which are mostly ignored.
* Chip family: A set of MCU types from the same manufacturer with the same microprocessor core but potentially different set of peripherals. While the available set of peripherals may vary, the behaviour and I/O ports of each kind of peripheral are the same across the entire family. Thanks to the brilliant ideas of the various marketing departments of each vendor, the classification here can get very fluid.
* Core: The microprocessor core used by a given chip family.

Let's take as an example the classic stm32f4discovery board that is the most common development device for Miosix:
* The board is the stm32f4discovery itself. It includes the chip, and miscellaneous peripherals such as an accelerometer and a Cirrus Logic audio chip. The STLink programming interface and the power supply are '''not''' considered relevant parts of the board for Miosix, as the MCU is not in control of what they do.
* The chip is an STM32F407VGT6. The VGT6 suffix of the chip name specifies package (100 pin LQFP), Flash size (1MB) and temperature range options (see the datasheet at the "Ordering Information" page).
* The chip family is STM32F4. This can be inferred by the fact that all available chips with this prefix in the part name share the same reference manual.
* The core is an ARM Cortex M4, as stated in the datasheet. Roughly, ST buys the Verilog for the core from ARM and then takes care of the manufacturing. As far as we know, ARM's licence shouldn't allow ST to customize the core in any way, so all Cortex M4 cores should behave the same, even from other vendors.

One definition we did not give is the definition of what an '''architecture''' is. The reason is that there is no accepted definition for this term, especially for forum pundits and bloggers, but also in academia. The RISC school of thought (Patterson/Hennessy and their spawn) historically associated an ''architecture'' with a combination of what are more specifically called the ''instruction set architecture'' (ISA) and the ''microarchitecture'' of a core. Their thesis was that the microarchitecture design will follow naturally from the definition of the ISA, hence simpler ISAs (RISC) to implement always lead to more efficient and generally better cores. However the industry has proven them wrong, and the most glaring example are Intel x86 chips, which have seen an increasing variety of microarchitectures implementing the same ISA (variously extended of course) with wildly varying levels of (non-)efficiency (in all possible ramifications of "efficiency"). Closer to Miosix's targets, the ARM ISA has been extended so much over the years that its core RISC design has now evolved to basically a traditional CISC ISA, but ARM chips still come in every possible size and flavour. Usually we talk about x86 "architectures" or ARM "architectures", but do we mean desktop-grade chips or microcontrollers? Even though they have the same "architecture" the cores in these two classes of chips have nothing to do with each other, they don't even share the same instruction decoder probably. Hence our conclusion that the word "architecture" has now lost all useful meaning for our purposes, and is only useful for void parlor chitchat.

And then we come to Miosix which defines "architecture" (arch) as... a board. Which is not what anyone means when they talk about architecture of anything. For Miosix, an "architecture" is more like what in common parlance would be meant as a "platform".

== Current structure ==

<pre>
arch
common Pool of useful files. Very few files here are common to all archs.
CMSIS Collection of ARM & vendor headers following the CMSIS standard
core Board independent drivers required for the OS to function (roughly)
atomic_ops_*.h Core dependent
cache_*.cpp/h Core dependent. This is not required for Miosix but is nevertheless here
*_os_timer.cpp Chip family dependent
endianness_*.h Core dependent. Should have a generic (slow) implementation.
interrupts.h Umbrella header for interrupts_*.h
interrupts_*.h Core dependent. Misleading name, this is for fault handling.
memory_protection.h Umbrella header for mpu_*.h. Required only for process mode.
mpu_*.cpp/h Core dependent.
drivers Miscellaneous drivers, which are "common" only very roughly
dcc.cpp/h Core dependent (but common to all ARM cores apparently)
*_adc.cpp/h Chip family dependent
serial.h Umbrella header for *serial*.h
*serial*.cpp/h Chip family dependent
sd_*.cpp/h Chip family dependent
servo_*.cpp/h Board dependent really, should go into utils
*_hardware_rng.cpp/h Chip family dependent
*_rtc.cpp/h Chip family dependent
*_sgm.cpp/h Chip family dependent
*_wd.cpp/h Chip family dependent
*_i2c.cpp/h Chip family dependent
<board group name> Board specific files.Board names are decided based on chip family but also include the core in their name
common Common drivers and configuration for all the boards in the group
arch_settings.h Core dependent. Misleading name, defines requirements for ctxsave
interfaces-impl The actual drivers
arch_registers_impl.h Chip family dependent. Includes the appropriate register definitions
delays.cpp Chip family dependent as it also depends on ROM/Flash speed. Actually application dependent (!) as cache/prefetch mechanisms can be configured but whatever.
gpio_impl.cpp/h Chip family dependent.
portability_impl.h Core dependent.
portability.cpp Core dependent.
<board name> Board/chip specific files.
core Board/chip dependent code required for the OS to function.
stage_1_boot.c/cpp/s Chip dependent. Interrupt vector table, reset handler, clock tree setup, bss/data initialization
interfaces_impl Board/chip specific drivers.
bsp_impl.h Board dependent. Useful board-specific definitions.
bsp.cpp Board dependent. Useful board-specific functions.
hwmapping.h Board dependent. GPIO pin definitions.
delays.cpp See above. Sometimes it's here, with no true reason why.
arch_registers_impl.h See above. Sometimes it's here, depends on chip.
... Some boards have extra miscellaneous drivers here
interfaces
</pre>

''<board group name>'' is defined as the name of the chip core, followed by an underscore, followed by the name of a chip family. ''<board name>'' is defined by the name of the chip, followed by an underscore, followed by a "common name" of the board. For commercial prototyping boards or specific devices, "common name" is derived from the name given by the manufacturer, or a name which is in common use with some exceptions (i.e. stm32f103 bluepill boards are named "breakout").

Some general patterns can be inferred:
* Apart from minor exceptions, directories named '''core''' contain drivers required for the OS to function.
* Directories named '''interfaces_impl''' generally contain implementations of things defined in /interfaces. Header files in '''interfaces_impl''' are always given the ``_impl`` suffix. C++ files are usually not given the "_impl" suffix but sometimes they have it (gpio_impl.cpp).
* Directories named '''common''' contain code shared by multiple boards. No attempt is made to separate different levels of commonality apart from chip-family specific stuff which is grouped by board group.

=== Issues ===

Experience has shown this organization has the following problems:
* What goes where is not well defined due to the vagueness of directory names, which leads to files being in the wrong place even though it's not obvious
* servo_* is the most glaring example
* The location of delays.cpp and arch_registers_impl.h is also inconsistent
* The two level board group/board classification does not reflect reality, which leads to missing code sharing opportunities:
* GPIO implementations are duplicated multiple times as they are common to multiple chip families and not to a single one.
* Bootstrap code is duplicated multiple times as they are common to boards with the same chip and not common to the board.
* Portability code (i.e. context save/restore primitives mostly) is duplicated multiple times as they are common to a given core and not to a chip family

Arch directory restructuring

2023-11-13T13:16:08Z

Daniele.cattaneo: Start writing

The ''arch'' directory is a mess with lots of copy-pasted code. Let's fix that!

== Some definitions ==

Common sense suggests the following taxonomy of parts for MCU-equipped devices targeted by Miosix:
* Board: The device itself being targeted. It's called a board because nobody has observed any MCU wired with point-to-point wiring yet. Includes the MCU itself plus any peripheral external to the MCU but '''driven''' by it.
* Chip: The MCU itself. May come in RAM/OTP/ROM/Flash size variations, which are mostly ignored.
* Chip family: A set of MCU types from the same manufacturer with the same microprocessor core but potentially different set of peripherals. While the available set of peripherals may vary, the behaviour and I/O ports of each kind of peripheral are the same across the entire family. Thanks to the brilliant ideas of the various marketing departments of each vendor, the classification here can get very fluid.
* Core: The microprocessor core used by a given chip family.

Let's take as an example the classic stm32f4discovery board that is the most common development device for Miosix:
* The board is the stm32f4discovery itself. It includes the chip, and miscellaneous peripherals such as an accelerometer and a Cirrus Logic audio chip. The STLink programming interface and the power supply are '''not''' considered relevant parts of the board for Miosix, as the MCU is not in control of what they do.
* The chip is an STM32F407VGT6. The VGT6 suffix of the chip name specifies package (100 pin LQFP), Flash size (1MB) and temperature range options (see the datasheet at the "Ordering Information" page).
* The chip family is STM32F4. This can be inferred by the fact that all available chips with this prefix in the part name share the same reference manual.
* The core is an ARM Cortex M4, as stated in the datasheet. Roughly, ST buys the Verilog for the core from ARM and then takes care of the manufacturing. As far as we know, ARM's licence shouldn't allow ST to customize the core in any way, so all Cortex M4 cores should behave the same, even from other vendors.

One definition we did not give is the definition of what an '''architecture''' is. The reason is that there is no accepted definition for this term, especially for forum pundits and bloggers, but also in academia. The RISC school of thought (Patterson/Hennessy and their spawn) historically associated an ''architecture'' with a combination of what are more specifically called the ''instruction set architecture'' (ISA) and the ''microarchitecture'' of a core. Their thesis was that the microarchitecture design will follow naturally from the definition of the ISA, hence simpler ISAs (RISC) to implement always lead to more efficient and generally better cores. However the industry has proven them wrong, and the most glaring example are Intel x86 chips, which have seen an increasing variety of microarchitectures implementing the same ISA (variously extended of course) with wildly varying levels of (non-)efficiency (in all possible ramifications of "efficiency"). Closer to Miosix's targets, the ARM ISA has been extended so much over the years that its core RISC design has now evolved to basically a traditional CISC ISA, but ARM chips still come in every possible size and flavour. Usually we talk about x86 "architectures" or ARM "architectures", but do we mean desktop-grade chips or microcontrollers? Even though they have the same "architecture" the cores in these two classes of chips have nothing to do with each other, they don't even share the same instruction decoder probably. Hence our conclusion that the word "architecture" has now lost all useful meaning for our purposes, and is only useful for void parlor chitchat.

And then we come to Miosix which defines "architecture" (arch) as... a board. Which is not what anyone means when they talk about architecture of anything. For Miosix, an "architecture" is more like what in common parlance would be meant as a "platform".

== Current structure ==

<pre>
arch
common Pool of useful files. Very few files here are common to all archs.
CMSIS Collection of ARM & vendor headers following the CMSIS standard
core Board independent drivers required for the OS to function (roughly)
atomic_ops_*.h Core dependent
cache_*.cpp/h Core dependent. This is not required for Miosix but is nevertheless here
*_os_timer.cpp Chip family dependent
endianness_*.h Core dependent. Should have a generic (slow) implementation.
interrupts.h Umbrella header for interrupts_*.h
interrupts_*.h Core dependent. Misleading name, this is for fault handling.
memory_protection.h Umbrella header for mpu_*.h. Required only for process mode.
mpu_*.cpp/h Core dependent.
drivers Miscellaneous drivers, which are "common" only very roughly
dcc.cpp/h Core dependent (but common to all ARM cores apparently)
*_adc.cpp/h Chip family dependent
serial.h Umbrella header for *serial*.h
*serial*.cpp/h Chip family dependent
sd_*.cpp/h Chip family dependent
servo_*.cpp/h Board dependent really, should go into utils
*_hardware_rng.cpp/h Chip family dependent
*_rtc.cpp/h Chip family dependent
*_sgm.cpp/h Chip family dependent
*_wd.cpp/h Chip family dependent
*_i2c.cpp/h Chip family dependent
<board group name> Board specific files.Board names are decided based on chip family but also include the core in their name
common Common drivers and configuration for all the boards in the group
arch_settings.h Core dependent. Misleading name, defines requirements for ctxsave
interfaces-impl The actual drivers
arch_registers_impl.h Chip family dependent. Includes the appropriate register definitions
delays.cpp Chip family dependent as it also depends on ROM/Flash speed. Actually application dependent (!) as cache/prefetch mechanisms can be configured but whatever.
gpio_impl.cpp/h Chip family dependent.
portability_impl.h Core dependent.
portability.cpp Core dependent.
<board name> Board/chip specific files.
core Board/chip dependent code required for the OS to function.
stage_1_boot.c/cpp/s Chip dependent. Interrupt vector table, reset handler, clock tree setup, bss/data initialization
interfaces_impl Board/chip specific drivers.
bsp_impl.h Board dependent. Useful board-specific definitions.
bsp.cpp Board dependent. Useful board-specific functions.
hwmapping.h Board dependent. GPIO pin definitions.
delays.cpp See above. Sometimes it's here, with no true reason why.
arch_registers_impl.h See above. Sometimes it's here, depends on chip.
... Some boards have extra miscellaneous drivers here
interfaces
</pre>

''<board group name>'' is defined as the name of the chip core, followed by an underscore, followed by the name of a chip family. ''<board name>'' is defined by the name of the chip, followed by an underscore, followed by a "common name" of the board. For commercial prototyping boards or specific devices, "common name" is derived from the name given by the manufacturer, or a name which is in common use with some exceptions (i.e. stm32f103 bluepill boards are named "breakout").

Some general patterns can be inferred:
* Apart from minor exceptions, directories named '''core''' contain drivers required for the OS to function.
* Directories named '''interfaces_impl''' generally contain implementations of things defined in /interfaces. Header files in '''interfaces_impl''' are always given the ``_impl`` suffix. C++ files are usually not given the "_impl" suffix but sometimes they have it (gpio_impl.cpp).
* Directories named '''common''' contain code shared by multiple boards. No attempt is made to separate different levels of commonality apart from chip-family specific stuff which is grouped by board group.

=== Issues ===

Experience has shown this organization has the following problems:
* What goes where is not well defined due to the vagueness of directory names, which leads to files being in the wrong place even though it's not obvious
* servo_* is the most glaring example
* The location of delays.cpp and arch_registers_impl.h is also inconsistent
* The two level board group/board classification does not reflect reality, which leads to missing code sharing opportunities:
* GPIO implementations are duplicated multiple times as they are common to multiple chip families and not to a single one.
* Bootstrap code is duplicated multiple times as they are common to boards with the same chip and not common to the board.
* Portability code (i.e. context save/restore primitives mostly) is duplicated multiple times as they are common to a given core and not to a chip family

User:Daniele.cattaneo

2023-11-13T11:29:53Z

Daniele.cattaneo:

Hi :)

Github (work): [https://github.com/danielecattaneo]

Github (personal): Secret

[[Miosix in emulation]]

[[arch directory restructuring]]

Linux Debugger configuration

2023-07-03T20:37:35Z

Daniele.cattaneo: Bold markup rather than italic.

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

== Setting up OpenOCD ==

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

=== Run OpenOCD ===
The OpenOCD configuration is included in the official Miosix distribution under the path 'miosix/arch'. You must choose the proper config file for the device in use. For example for the stm32f429zi_stm32f4discovery board:
<source lang="bash">
openocd -f miosix/arch/cortexM4_stm32f4/stm32f429zi_stm32f4discovery/stm32f4discovery.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]]. If you haven't already installed it's time to do it. The debugger must be launched on the ELF binary file.
<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 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>

=== 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]]

Linux Debugger configuration

2023-07-03T20:37:08Z

Daniele.cattaneo: Add troubleshooting info for the case in which breakpoints don't work.

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

== Setting up OpenOCD ==

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

=== Run OpenOCD ===
The OpenOCD configuration is included in the official Miosix distribution under the path 'miosix/arch'. You must choose the proper config file for the device in use. For example for the stm32f429zi_stm32f4discovery board:
<source lang="bash">
openocd -f miosix/arch/cortexM4_stm32f4/stm32f429zi_stm32f4discovery/stm32f4discovery.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]]. If you haven't already installed it's time to do it. The debugger must be launched on the ELF binary file.
<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 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>

=== 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]]

MacOS Quick Start

2023-06-11T20:17:19Z

Daniele.cattaneo: MacOS is now called macOS.

{{DISPLAYTITLE:macOS Quick Start}}
This page explains how to install the precompiled Miosix Toolchain, which since January 2023 is also available for macOS. The building instructions previously found on this page have been updated and moved to [[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. 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 is recommended first.

== 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>

QSTLink2 is not supported on macOS.

==== 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. 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. If you are using an Apple Silicon (ARM) Mac, the installer will automatically propose to install Rosetta for you in case it is not already installed.

== 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).