Struct imxrt_rt::RuntimeBuilder

pub struct RuntimeBuilder { /* private fields */ }

Builder for the i.MX RT runtime.

RuntimeBuilder let you assign sections to memory regions. It also lets you partition FlexRAM DTCM/ITCM/OCRAM. Call build() to commit the runtime configuration.

Behaviors

The implementation tries to place the stack in the lowest-possible memory addresses. This means the stack will grow down into reserved memory below DTCM and OCRAM for most chip families. The outlier is the 1170, where the stack will grow into OCRAM backdoor for the CM4 coprocessor. Be careful here…

Similarly, the implementation tries to place the heap in the highest-possible memory addresses. This means the heap will grow up into reserved memory above DTCM and OCRAM for most chip families.

The vector table requires a 1024-byte alignment. The vector table’s placement is prioritized above all other sections, except the stack. If placing the stack and vector table in the same section (which is the default behavior), consider keeping the stack size as a multiple of 1 KiB to minimize internal fragmentation.

Default values

The example below demonstrates the default RuntimeBuilder memory placements, stack sizes, and heap sizes.

use imxrt_rt::{Family, RuntimeBuilder, Memory};

const FLASH_SIZE: usize = 16 * 1024;
let family = Family::Imxrt1060;

let mut b = RuntimeBuilder::from_flexspi(family, FLASH_SIZE);
// FlexRAM banks represent default fuse values.
b.flexram_banks(family.default_flexram_banks());
b.text(Memory::Itcm);    // Copied from flash.
b.rodata(Memory::Ocram); // Copied from flash.
b.data(Memory::Ocram);   // Copied from flash.
b.vectors(Memory::Dtcm); // Copied from flash.
b.bss(Memory::Ocram);
b.uninit(Memory::Ocram);
b.stack(Memory::Dtcm);
b.stack_size(8 * 1024);  // 8 KiB stack.
b.heap(Memory::Dtcm);    // Heap in DTCM...
b.heap_size(0);          // ...but no space given to the heap.

assert_eq!(b, RuntimeBuilder::from_flexspi(family, FLASH_SIZE));

Implementations

impl RuntimeBuilder

pub fn from_flexspi(family: Family, flash_size: usize) -> Self

Creates a runtime that can execute and load contents from FlexSPI flash.

flash_size is the size of your flash component, in bytes.

pub fn flexram_banks(&mut self, flexram_banks: FlexRamBanks) -> &mut Self

Set the FlexRAM bank allocation.

Use this to customize the sizes of DTCM, ITCM, and OCRAM. See the FlexRamBanks documentation for requirements on the bank allocations.

pub fn text(&mut self, memory: Memory) -> &mut Self

Set the memory placement for code.

pub fn rodata(&mut self, memory: Memory) -> &mut Self

Set the memory placement for read-only data.

pub fn data(&mut self, memory: Memory) -> &mut Self

Set the memory placement for mutable data.

pub fn vectors(&mut self, memory: Memory) -> &mut Self

Set the memory placement for the vector table.

pub fn bss(&mut self, memory: Memory) -> &mut Self

Set the memory placement for zero-initialized data.

pub fn uninit(&mut self, memory: Memory) -> &mut Self

Set the memory placement for uninitialized data.

pub fn stack(&mut self, memory: Memory) -> &mut Self

Set the memory placement for stack memory.

pub fn stack_size(&mut self, bytes: usize) -> &mut Self

Set the size, in bytes, of the stack.

pub fn heap(&mut self, memory: Memory) -> &mut Self

Set the memory placement for the heap.

Note that the default heap has no size. Use heap_size to allocate space for a heap.

pub fn heap_size(&mut self, bytes: usize) -> &mut Self

Set the size, in bytes, of the heap.

pub fn flexspi(&mut self, peripheral: FlexSpi) -> &mut Self

Set the FlexSPI peripheral that interfaces flash.

See the FlexSpi to understand the default values. If this builder is not configuring a flash-loaded runtime, this call is silently ignored.

pub fn linker_script_name(&mut self, name: &str) -> &mut Self

Set the name of the linker script file.

You can use this to customize the linker script name for your users. See the crate-level documentation for more information.

pub fn build(&self) -> Result<(), Box<dyn Error>>

Commit the runtime configuration.

build() ensures that the generated linker script is available to the linker.

Errors

The implementation ensures that your chip can support the FlexRAM bank allocation. An invalid allocation is signaled by an error.

Returns an error if any of the following sections are placed in flash:

• data
• vectors
• bss
• uninit
• stack
• heap

The implementation may rely on the linker to signal other errors. For example, suppose a runtime configuration with no ITCM banks. If a section is placed in ITCM, that error could be signaled here, or through the linker. No matter the error path, the implementation ensures that there will be an error.

Trait Implementations

impl Clone for RuntimeBuilder

fn clone(&self) -> RuntimeBuilder

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for RuntimeBuilder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl PartialEq<RuntimeBuilder> for RuntimeBuilder

fn eq(&self, other: &RuntimeBuilder) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for RuntimeBuilder

impl StructuralEq for RuntimeBuilder

impl StructuralPartialEq for RuntimeBuilder