# Memory Layout and Configuration Guide

This document explains the memory layout, configuration entry points, and tuning methods for the K230/K230D RT-Smart platform, based on the SDK source Kconfig files, linker scripts, and board-level implementations.

## Overall Memory Model

In the current SDK, DDR is divided into two main regions:

1. **RT-Smart system region** — kernel + user-space page pool + dynamic heap
1. **MMZ region** — large media-related memory blocks

The core configuration options are found under **Board Configuration → Memory Layout**:

- `CONFIG_MEM_RTSMART_BASE` — RT-Smart start base address (default `0x0`)
- `CONFIG_RTSMART_OPENSIB_MEMORY_SIZE` — OpenSBI reserved region size (default `0x20000`)
- `CONFIG_MEM_RTSMART_SIZE` — RT-Smart total memory size
- `CONFIG_MEM_RTSMART_HEAP_SIZE` — RT-Smart heap size
- `CONFIG_MEM_MMZ_BASE` — MMZ base address
- `CONFIG_MEM_MMZ_SIZE` — MMZ size
- `CONFIG_MEM_TOTAL_SIZE` — Total DDR size (used in static mode)

Source references:

- `boards/Kconfig`
- `boards/Kconfig.memory_static`
- `boards/Kconfig.memory_auto`
- `src/rtsmart/rtsmart/kernel/bsp/maix3/board/board.c`
- `src/rtsmart/rtsmart/kernel/bsp/maix3/board/board.h`
- `src/rtsmart/rtsmart/kernel/bsp/maix3/link.lds.in`

## Two Configuration Modes

### Static Configuration Mode

When `CONFIG_AUTO_DETECT_DDR_SIZE=n`, a fixed set of values from `Kconfig.memory_static` is used:

- `MEM_TOTAL_SIZE`
- `MEM_RTSMART_SIZE`
- `MEM_RTSMART_HEAP_SIZE`
- `MEM_MMZ_BASE`
- `MEM_MMZ_SIZE`

These values are compiled directly into the linker script and runtime initialization.

**Best suited for:**

- Boards with fixed DDR (e.g. SiP with fixed capacity)
- Cases where precise control over each region size is required

### Automatic DDR Detection Mode

When `CONFIG_AUTO_DETECT_DDR_SIZE=y`, tier-based values from `Kconfig.memory_auto` are used:

- 512 MB tier: `*_512`
- 1024 MB tier: `*_1024`
- 2048 MB tier: `*_2048`

Runtime flow (see `board.c`):

1. Obtain DDR capacity via `k230_atag_get_ddr_size()`
1. If that fails, fall back to `0x20000000` (512 MB)
1. Select the matching tier's RT-Smart size, heap size, MMZ base address, and MMZ size

> In auto mode, `board.h` redirects `CONFIG_MEM_*` macros to `get_*()` function return values, enabling dynamic selection based on the actual DDR size.

## Key Address Formulas

The following formulas are derived from `board.c` and `link.lds.in`:

1. **System start address**

$$
RTT\_SYS\_BASE = MEM\_RTSMART\_BASE + RTSMART\_OPENSIB\_MEMORY\_SIZE
$$

1. **Total usable system region** (aligned to KB, with 1 KB reserved)

$$
RTT\_SYS\_SIZE = \left(\left\lfloor\frac{MEM\_RTSMART\_SIZE - RTSMART\_OPENSIB\_MEMORY\_SIZE}{1024}\right\rfloor - 1\right) \times 1024
$$

1. **RAM_END** (4 KB reserved at the end)

$$
RAM\_END = RTT\_SYS\_BASE + RTT\_SYS\_SIZE - 4096
$$

1. **Heap region**

- `RT_HW_HEAP_BEGIN = &__bss_end`
- `RT_HW_HEAP_END = RT_HW_HEAP_BEGIN + CONFIG_MEM_RTSMART_HEAP_SIZE`

1. **MMZ region**

- `MEM_MMZ_BASE = CONFIG_MEM_MMZ_BASE`
- `MEM_MMZ_SIZE = CONFIG_MEM_MMZ_SIZE - 4096` (see `board.h`)

## Default Tiers (Auto Mode)

From `boards/Kconfig.memory_auto`:

**512 MB tier**

- `MEM_RTSMART_SIZE_512 = 0x10000000` (256 MB)
- `MEM_RTSMART_HEAP_SIZE_512 = 0x02000000` (32 MB)
- `MEM_MMZ_BASE_512 = 0x10000000`
- `MEM_MMZ_SIZE_512 = 0x10000000` (256 MB)

**1024 MB tier**

- `MEM_RTSMART_SIZE_1024 = 0x20000000` (512 MB)
- `MEM_RTSMART_HEAP_SIZE_1024 = 0x04000000` (64 MB)
- `MEM_MMZ_BASE_1024 = 0x20000000`
- `MEM_MMZ_SIZE_1024 = 0x20000000` (512 MB)

**2048 MB tier**

- `MEM_RTSMART_SIZE_2048 = 0x20000000` (512 MB)
- `MEM_RTSMART_HEAP_SIZE_2048 = 0x04000000` (64 MB)
- `MEM_MMZ_BASE_2048 = 0x20000000`
- `MEM_MMZ_SIZE_2048 = 0x60000000` (1536 MB)

## Configuration Entry Point

Run the following in the SDK root directory:

```bash
make menuconfig
```

Navigate to:

```text
Board Configuration
  -> Memory Layout
```

From there you can:

1. Enable/disable `Auto Detect DRAM Size`
1. Configure per-tier parameters (512/1024/2048) in auto mode
1. Configure `MEM_TOTAL_SIZE`, `MEM_RTSMART_SIZE`, `MEM_RTSMART_HEAP_SIZE`, `MEM_MMZ_BASE`, `MEM_MMZ_SIZE` in static mode

## Configuration Guidelines and Constraints

Follow these rules:

1. **Total size constraint**
   - `MEM_RTSMART_SIZE + MEM_MMZ_SIZE` must not exceed `MEM_TOTAL_SIZE`

1. **Contiguous layout (recommended)**
   - Set `MEM_MMZ_BASE = MEM_RTSMART_SIZE` (assuming the default `MEM_RTSMART_BASE=0`)

1. **Heap size constraint**
   - `MEM_RTSMART_HEAP_SIZE` must be smaller than the actual usable system region (after subtracting the kernel image, BSS, and page management overhead)

1. **Media-heavy workloads**
   - Increase `MEM_MMZ_SIZE`
   - Ensure the RT-Smart heap still meets application requirements

1. **Application-heavy workloads**
   - Increase `MEM_RTSMART_HEAP_SIZE`
   - Avoid shrinking MMZ to the point where media module allocations fail

## Validation After Changes

1. Rebuild the image:

```bash
time make log
```

1. Check `.config` to verify the target values (e.g. `CONFIG_MEM_RTSMART_SIZE`, `CONFIG_MEM_MMZ_SIZE`) are applied correctly.

1. Run typical workloads on the board (media, AI, network) and observe whether any out-of-memory or allocation failure errors appear.

## K230D Example (Static Configuration)

From `configs/k230d_rtos_evb_defconfig`:

- `CONFIG_MEM_RTSMART_SIZE=0x4400000`
- `CONFIG_MEM_RTSMART_HEAP_SIZE=0x1000000`
- `CONFIG_MEM_MMZ_BASE=0x4400000`
- `CONFIG_MEM_MMZ_SIZE=0x3C00000`

This is a typical contiguous "system region + MMZ region" split.

## FAQ

### In auto DDR detection mode, why does the actual behavior differ from expectations?

Check:

1. Is `CONFIG_AUTO_DETECT_DDR_SIZE=y`?
1. Does the corresponding tier option exist (512/1024/2048)?
1. Can the board correctly retrieve the ATAG DDR size? (If not, it falls back to the 512 MB tier.)

### Memory configuration changed, compiles fine, but crashes at runtime?

Check:

1. Is `MEM_RTSMART_HEAP_SIZE` too large, encroaching on the page pool space?
1. Do `MEM_MMZ_BASE`/`MEM_MMZ_SIZE` overflow or overlap with the system region?
1. Does the board's actual DDR capacity match the configuration?