Skip to content

README.md

Latest commit

 

History

History
416 lines (385 loc) · 12 KB

README.md

File metadata and controls

416 lines (385 loc) · 12 KB

STM32G0xx Runtimes

This repository generates GNAT runtimes that support all MCUs in the STM32G0 family.

The following runtime profiles are supported:

  • light
  • light-tasking
  • embedded

Usage

Using the light-tasking-stm32g0xx runtime as an example, first edit your alire.toml file and add the following elements:

  • Add light_tasking_stm32g0xx in the dependency list: 
    [[depends-on]]
light_tasking_stm32g0xx = "*"
  • if applicable, apply any runtime configuration variables (see "Runtime Configuration" below).

Then edit your project file to add the following elements:

  • "with" the run-time project file: 
    with "runtime_build.gpr";
  • if you are using the light-tasking or embedded runtime profile, then you also need to "with" ravenscar_build.gpr: 
    with "ravenscar_build.gpr";
  • specify the Target and Runtime attributes: 
    for Target use runtime_build'Target;
for Runtime ("Ada") use runtime_build'Runtime ("Ada");
  • specify the Linker switches: 
    package Linker is
  for Switches ("Ada") use Runtime_Build.Linker_Switches;
end Linker;

Runtime Configuration

Crate Configuration

The runtime is configurable through crate configuration variables in your project's alire.toml.

MCU Configuration

The following variables configure the specific STM32G0 MCU that is being targeted:

Variable Values Default Description
MCU_Sub_Family "G030", "G031", "G041", "G050", "G051", "G061", "G070", "G071", "G081", "G0B0", "G0B1", "G0C1" "G0B1" Specifies the sub-family part of the STM32G0 part number. For example, choose "G0B1" for the STM32G0B1RE.
MCU_Flash_Memory_Size "4", "6", "8", "B", "C", "E" "B" Specifies the "flash memory size" part of the STM32G0 part number. For example, this is the "E" in "STM32G0B1RE".

By default, the runtime is configured for the STM32G0B1RE. If you are using a different MCU, then you will need to configure the runtime by adding the following to your alire.toml. For example, to configure the runtime for the STM32G031J4:

[configuration.values]
light_tasking_stm32g0xx.MCU_Sub_Family        = "G031"
light_tasking_stm32g0xx.MCU_Flash_Memory_Size = "4"

The following variables tell the runtime whether you will enable RAM parity checking in the option bytes:

Variable Values Default Description
RAM_Parity_Check "Enabled", "Disabled" "Disabled" Tells the runtime whether you will enable RAM parity checking in the option bytes. Note that the runtime does not write this value to the option bytes. It is the user's responsibility to ensure that the option byte is programmed correctly. This configuration variable is only used to inform the runtime of the value it should assume.

This is used by the runtime to adjust the linker scripts to account for whether SRAM parity checking is enabled. When it is enabled, the amount of usable RAM is slightly lower. For example, on a STM32G0 with 144 KB of SRAM, the runtime will configure the linker script for 128 KB when the SRAM parity check is enabled.

Clock Configuration

By default, the runtime configures the clocks to provide a 64 MHz system clock from the high-speed internal (HSI) oscillator. The following crate configuration variables can be used to configure a different clock tree:

Variable Values Default Description
LSI_Enabled true, false true When true, the runtime will enable the 32 kHz low-speed internal (LSI) oscillator at startup.
LSE_Enabled true, false true When true, the runtime will enable the 32.768 kHz low-speed external (LSE) oscillator at startup.
HSE_Bypass true, false false When true, the runtime will use enable the HSE bypass feature to allow an external clock source to be used (setting HSEBYP in the clock configuration registers). When false, the HSE will be configured for an external crystal/ceramic resonator.
LSE_Bypass true, false false When true, the runtime will use enable the LSE bypass feature to allow an external clock source to be used (setting LSEBYP in the clock configuration registers). When false, the LSE will be configured for an external crystal/ceramic resonator.
HSE_Clock_Frequency 4000000 .. 48000000 8000000 Specifies the frequency of the HSE clock in Hertz. The default is 8 MHz.
PLL_Src "HSE", "HSI16" "HSI16" Specifies the clock source to use for the input into the PLL.
  • "HSE" selects the high-speed external (HSE) clock as the PLL clock source.
  • "HSI16" selects high-speed internal (HSI) clock as the PLL clock source.
PLL_M_Div 1 .. 8 2 Specifies the 'M' divider value in the PLL configuration
PLL_N_Div 1 .. 8 2 Specifies the 'N' multiplier value in the PLL configuration.
PLL_R_Div 1 .. 8 2 Specifies the 'R' divider value in the PLL configuration
PLL_Q_Div 1 .. 8 2 Specifies the 'Q' divider value in the PLL configuration
PLL_P_Div 1 .. 8 2 Specifies the 'P' divider value in the PLL configuration
PLL_Q_Enable true, false, true Selects whether the PLL's 'Q' output clock is enabled.
PLL_P_Enable true, false, true Selects whether the PLL's 'P' output clock is enabled.
SYSCLK_Src "LSE", "LSI", "HSE", "PLLRCLK", "HSISYS" "PLLRCLK" Specifies the clock source to use for the system clock (SYSCLK).
  • "LSE" selects the 32.768 low-speed external (LSE) clock.
  • "LSI" selects the 32 kHz low-speed internal (LSI) clock.
  • "HSE" selects the high-speed external (HSE) clock.
  • "PLLRCLK" selects the PLL's 'R' clock.
  • "HSISYS" selects the high-speed internal (HSI) clock, divided by HSI_Div.
AHB_Pre "DIV1", "DIV2", "DIV4", "DIV8", "DIV16", "DIV64", "DIV128", "DIV256", "DIV512" "DIV1" Specifies the divider to use for the AHB prescaler.
APB_Pre "DIV1", "DIV2", "DIV4", "DIV8", "DIV16" "DIV1" Specifies the divider to use for the APB prescaler.

Here's an example of configuring the runtime in alire.toml for a 64 MHz system clock from a 24 MHz HSE oscillator:

[configuration.values]
# Configure a 24 MHz HSE crystal oscillator
light_tasking_stm32g0xx.HSE_Clock_Frequency = 24000000
light_tasking_stm32g0xx.HSE_Bypass = false

# Select PLLRCLK as the SYSCLK source
light_tasking_stm32g0xx.SYSCLK_Src = "PLLRCLK"

# Configure the PLL VCO to run at 128 MHz from the 24 MHz HSE (fVCO = fHSE * (N/M))
light_tasking_stm32g0xx.PLL_Src = "HSE"
light_tasking_stm32g0xx.PLL_N_Mul = 10
light_tasking_stm32g0xx.PLL_M_Div = 2

# Configure the PLLRCLK to run at 64 MHz from the 128 MHz VCO.
light_tasking_stm32g0xx.PLL_R_Div = 2

# Configure the AHB an APB to also run at 64 MHz
light_tasking_stm32g0xx.AHB_Pre = "DIV1"
light_tasking_stm32g0xx.APB_Pre = "DIV1"

Stack Sizes

The following variables configure the interrupt stack sizes:

Variable Values Default Description
Interrupt_Stack_Size Any positive integer 1024 Specifies the size of the primary stack used for interrupt handlers.
Interrupt_Secondary_Stack_Size Any positive integer 128 Specifies the size of the secondary stack used for interrupt handlers.

GPR Scenario Variables

The runtime project files expose *_BUILD and *_LIBRARY_TYPE GPR scenario variables to configure the build mode (e.g. debug/production) and library type. These variables are prefixed with the name of the runtime in upper case. For example, for the light-tasking-stm32g0xx runtime the variables are LIGHT_TASKING_STM32G0XX_BUILD and LIGHT_TASKING_STM32G0XX_LIBRARY_TYPE respectively.

The *_BUILD variable can be set to the following values:

  • Production (default) builds the runtime with optimization enabled and with all run-time checks suppressed.
  • Debug disables optimization and adds debug symbols.
  • Assert enables assertions.
  • Gnatcov disables optimization and enables flags to help coverage.

The *_LIBRARY_TYPE variable can be set to either static (default) or dynamic, though only static libraries are supported on this target.

You can usually leave these set to their defaults, but if you want to set them explicitly then you can set them either by passing them on the command line when building your project with Alire:

alr build -- -XLIGHT_TASKING_STM32G0XX_BUILD=Debug

or by setting them in your project's alire.toml:

[gpr-set-externals]
LIGHT_TASKING_STM32G0XX_BUILD = "Debug"