external_memory_mgt.py

Go to the documentation of this file.

 
 
import os
import json
import sys
from typing import Dict
from common.utils import get_model_name_and_its_input_shape
 
 
def update_activation_c_code(c_project_path: str,
                              path_network_c_info: str,
                              available_AXIRAM: int,
                              cfg=None,
                              custom_objects: Dict = None) -> None:
    """
    @brief Patches generated C firmware files to configure activation buffer placement.
 
    @details
    This function performs **surgical modification of generated C source files**
    to ensure that neural network activation buffers, camera capture buffers, and
    rescaled image buffers are placed in the correct memory sections (AXIRAM or SDRAM)
    at link time.
 
    The function modifies three C files:
 
    **1. `main.h` — Camera resolution configuration**
    Patches `#define CAMERA_RESOLUTION`, `#define CAM_RES_WIDTH`, and
    `#define CAM_RES_HEIGHT` based on the model's input shape and the
    preprocessing aspect ratio mode from the Hydra configuration.
 
    Resolution selection logic:
    | Mode | Network ≤ QVGA (320×240) | Network ≤ VGA (640×480) |
    |------|--------------------------|-------------------------|
    | crop | CAMERA_R320x240, QVGA_HEIGHT | CAMERA_R640x480, VGA_HEIGHT |
    | padding | CAMERA_R320x240, QVGA_WIDTH | CAMERA_R640x480, VGA_WIDTH |
    | fit | CAMERA_R320x240, QVGA_WxH | CAMERA_R640x480, VGA_WxH |
 
    **2. `main.c` — Activation buffer declarations**
    Replaces the generated code block between
    `/*** @GENERATED CODE START - DO NOT TOUCH@ ***/` markers with
    explicit buffer declarations using GCC section attributes:
 
    @code{.c}
    // Example output for a model with 2 activation pools:
    __attribute__((section(".NN_Activation_Buffer_AXIRAM")))
    __attribute__ ((aligned (32)))
    static uint8_t NN_Activation_Buffer_AXIRAM[AI_ACTIVATION_1_SIZE_BYTES + 32 - (AI_ACTIVATION_1_SIZE_BYTES%32)];
 
    __attribute__((section(".NN_Activation_Buffer_npuRAM4")))
    __attribute__ ((aligned (32)))
    static uint8_t NN_Activation_Buffer_npuRAM4[AI_ACTIVATION_2_SIZE_BYTES + 32 - (AI_ACTIVATION_2_SIZE_BYTES%32)];
 
    ai_handle NN_Activation_Buffer[AI_ACTIVATION_BUFFERS_COUNT] = {
        NN_Activation_Buffer_AXIRAM, NN_Activation_Buffer_npuRAM4,
    };
    @endcode
 
    Buffer assignment strategy:
    - Buffers are sorted smallest-to-largest
    - Each buffer is assigned to AXIRAM if space remains, SDRAM otherwise
    - The 32-byte alignment padding ensures efficient cache line usage
 
    The CapturedImage_Buffer and RescaledImage_Buffer are also assigned
    to AXIRAM or SDRAM based on remaining available space after activations.
 
    **3. `ai_interface.h` — Input buffer index**
    Patches the `AI_NETWORK_INPUTS_IN_ACTIVATIONS_INDEX` and
    `AI_NETWORK_INPUTS_IN_ACTIVATIONS_SIZE` macros, which tell the firmware
    which activation buffer pool contains the model's input tensor.
 
    @param c_project_path       Root path of the STM32CubeIDE C project.
                                Expected structure:
                                @code
                                c_project_path/
                                └── Application/STM32H747I-DISCO/
                                    ├── Inc/CM7/main.h
                                    ├── Inc/CM7/ai_interface.h
                                    └── Src/CM7/main.c
                                @endcode
    @param path_network_c_info  Path to `network_c_info.json` generated by
                                ST Edge AI Core. Contains the list of memory pools
                                with their names, rights (ACC_READ/ACC_WRITE),
                                and used_size_bytes.
    @param available_AXIRAM     Available AXIRAM in bytes after subtracting
                                the ST AI runtime library footprint.
    @param cfg                  Hydra DictConfig containing:
                                - cfg.preprocessing.resizing.aspect_ratio
                                - cfg.general.model_path
    @param custom_objects       Custom Keras objects dictionary for model loading
                                (passed to get_model_name_and_its_input_shape).
 
    @return None — all modifications are performed in place on the C source files.
 
    @note Files are modified using a **write-then-rename** pattern for atomicity:
          a `_modify.c` / `_modify.h` temporary file is written, then
          `os.replace()` atomically replaces the original.
 
    @warning This function directly modifies generated firmware source files.
             Any manual edits inside the `@GENERATED CODE START/STOP` blocks
             will be overwritten on the next deployment run.
 
    @note This function is designed for **STM32H747I-DISCO** targets.
          For STM32N6570-DK (used in this project), the Neural-ART toolchain
          handles memory placement differently — this function is not called
          during STM32N6 deployment.
    """
 
    # --- Resolve target file paths within the C project ---
    path_main_h = os.path.join(
        c_project_path, "Application/STM32H747I-DISCO/Inc/CM7/main.h")
    path_main_c = os.path.join(
        c_project_path, "Application/STM32H747I-DISCO/Src/CM7/main.c")
    path_ai_interface_h = os.path.join(
        c_project_path, "Application/STM32H747I-DISCO/Inc/CM7/ai_interface.h")
 
    # --- Determine model input dimensions from the model file ---
    
    aspect_ratio = cfg.preprocessing.resizing.aspect_ratio
    _, input_shape = get_model_name_and_its_input_shape(
        model_path=cfg.general.model_path, custom_objects=custom_objects)
    network_height = input_shape[0]
    network_width = input_shape[1]
    network_channel = input_shape[2]  # 1=grayscale, 3=RGB
 
    # --- Compute resize buffer size (bytes) ---
    
    if network_channel == 1:
        resize_buffer_size = network_height * network_width           # Grayscale
    if network_channel == 3:
        resize_buffer_size = network_height * network_width * 2       # RGB565
 
    # --- Camera resolution constants (pixels) ---
    QVGA_width = 320
    QVGA_height = 240
    VGA_width = 640
    VGA_height = 480
 
    # --- Select camera resolution based on model input size and aspect ratio mode ---
    
    if aspect_ratio == "crop":
        if network_width <= QVGA_height and network_height <= QVGA_height:
            cam_res = "CAMERA_R320x240"
            cam_res_width = cam_buffer_width = "QVGA_RES_HEIGHT"
            cam_res_height = cam_buffer_height = "QVGA_RES_HEIGHT"
        elif network_width <= VGA_height and network_height <= VGA_height:
            cam_res = "CAMERA_R640x480"
            cam_res_width = cam_buffer_width = "VGA_RES_HEIGHT"
            cam_res_height = cam_buffer_height = "VGA_RES_HEIGHT"
    elif aspect_ratio == "padding":
        if network_width <= QVGA_width and network_height <= QVGA_width:
            cam_res = "CAMERA_R320x240"
            cam_res_width = cam_buffer_width = "QVGA_RES_WIDTH"
            cam_res_height = cam_buffer_height = "QVGA_RES_HEIGHT"
        elif network_width <= VGA_width and network_height <= VGA_width:
            cam_res = "CAMERA_R640x480"
            cam_res_width = cam_buffer_width = "VGA_RES_WIDTH"
            cam_res_height = cam_buffer_height = "VGA_RES_HEIGHT"
    else:
        # Default: fit mode — camera captures at closest standard resolution
        if network_width <= QVGA_width and network_height <= QVGA_height:
            cam_res = "CAMERA_R320x240"
            cam_res_width = cam_buffer_width = "QVGA_RES_WIDTH"
            cam_res_height = cam_buffer_height = "QVGA_RES_HEIGHT"
        elif network_width <= VGA_width and network_height <= VGA_height:
            cam_res = "CAMERA_R640x480"
            cam_res_width = cam_buffer_width = "VGA_RES_WIDTH"
            cam_res_height = cam_buffer_height = "VGA_RES_HEIGHT"
 
    if 'cam_res' not in locals():
        raise ValueError("Needed camera resolution ({}x{}) exceeds VGA format.".format(
            network_width, network_height))
 
    # =========================================================================
    # Patch 1: main.h — Update camera resolution macros
    # =========================================================================
    with open(os.path.join(path_main_h), 'r') as f1, \
         open(os.path.join(os.path.dirname(path_main_h), 'main_modify.h'), 'w') as f2:
        for lineNumber, line in enumerate(f1):
            if "#define CAMERA_RESOLUTION" in line:
                line = "#define CAMERA_RESOLUTION (" + cam_res + ")\n"
            elif "#define CAM_RES_WIDTH" in line:
                line = "#define CAM_RES_WIDTH (" + cam_res_width + ")\n"
            elif "#define CAM_RES_HEIGHT" in line:
                line = "#define CAM_RES_HEIGHT (" + cam_res_height + ")\n"
            f2.write(line)
    os.replace(
        os.path.join(os.path.dirname(path_main_h), 'main_modify.h'),
        path_main_h
    )
 
    # --- Resolve symbolic camera buffer dimensions to actual pixel values ---
    def resolve_cam_dim(sym):
        if sym == "QVGA_RES_WIDTH":  return QVGA_width
        if sym == "QVGA_RES_HEIGHT": return QVGA_height
        if sym == "VGA_RES_WIDTH":   return VGA_width
        return VGA_height
 
    cam_buffer_width = resolve_cam_dim(cam_buffer_width)
    cam_buffer_height = resolve_cam_dim(cam_buffer_height)
 
    
    if network_channel == 1:
        cam_buffer_size = cam_buffer_height * cam_buffer_width
    if network_channel == 3:
        cam_buffer_size = cam_buffer_height * cam_buffer_width * 2
 
    # =========================================================================
    # Patch 2: main.c — Declare activation buffers with explicit section attrs
    # =========================================================================
    
    with open(os.path.join(path_network_c_info), 'r') as f:
        graph = json.load(f)
 
    
    activations = [e for e in graph["memory_pools"]
                   if e["rights"] == "ACC_WRITE" and e["used_size_bytes"] != 0]
 
    
    activations = sorted(activations, key=lambda x: x['used_size_bytes'])
 
    writeLine = True
    with open(os.path.join(path_main_c), 'r') as f1, \
         open(os.path.join(os.path.dirname(path_main_c), 'main_modify.c'), 'w') as f2:
        for lineNumber, line in enumerate(f1):
            if line == " /*** @GENERATED CODE START - DO NOT TOUCH@ ***/\n":
                pool_list_str = []
                for i, pool in enumerate(activations):
                    
                    name_pool = (
                        "NN_Activation_Buffer_" + pool["name"]
                        if pool["name"] != "heap_overlay_pool"
                        else "NN_Activation_Buffer_AXIRAM"
                    )
                    
                    line += (
                        f'__attribute__((section(".{name_pool}")))\n'
                        f'__attribute__ ((aligned (32)))\n'
                        f'static uint8_t {name_pool}'
                        f'[AI_ACTIVATION_{i+1}_SIZE_BYTES + 32 - '
                        f'(AI_ACTIVATION_{i+1}_SIZE_BYTES%32)];\n'
                    )
                    pool_list_str.append(name_pool)
                    
                    if name_pool == "NN_Activation_Buffer_AXIRAM":
                        available_AXIRAM -= pool['used_size_bytes']
 
                
                line += "ai_handle NN_Activation_Buffer[AI_ACTIVATION_BUFFERS_COUNT] = { "
                for pool in pool_list_str:
                    line += pool + ", "
                line += "};\n\n"
                f2.write(line)
                writeLine = False
 
            if line == " /*** @GENERATED CODE STOP - DO NOT TOUCH@ ***/\n":
                writeLine = True
            if writeLine:
                f2.write(line)
    os.replace(
        os.path.join(os.path.dirname(path_main_c), 'main_modify.c'),
        path_main_c
    )
 
    # --- Second pass: place CapturedImage and RescaledImage buffers ---
    
    writeLine = True
    with open(os.path.join(path_main_c), 'r') as f1, \
         open(os.path.join(os.path.dirname(path_main_c), 'main_modify.c'), 'w') as f2:
        for lineNumber, line in enumerate(f1):
            if '__attribute__((section(".CapturedImage_Buffer' in line:
                if cam_buffer_size < available_AXIRAM:
                    available_AXIRAM -= cam_buffer_size
                    line = '__attribute__((section(".CapturedImage_Buffer_AXIRAM")))\n'
                else:
                    line = '__attribute__((section(".CapturedImage_Buffer_SDRAM")))\n'
            if '__attribute__((section(".RescaledImage_Buffer' in line:
                if resize_buffer_size < available_AXIRAM:
                    available_AXIRAM -= resize_buffer_size
                    line = '__attribute__((section(".RescaledImage_Buffer_AXIRAM")))\n'
                else:
                    line = '__attribute__((section(".RescaledImage_Buffer_SDRAM")))\n'
            f2.write(line)
    os.replace(
        os.path.join(os.path.dirname(path_main_c), 'main_modify.c'),
        path_main_c
    )
 
    # =========================================================================
    # Patch 3: ai_interface.h — Set input buffer index and size macros
    # =========================================================================
    
    input_buffer_activation_buffer_index = 0
    writeLine = True
    with open(os.path.join(path_ai_interface_h), 'r') as f1, \
         open(os.path.join(os.path.dirname(path_ai_interface_h),
                           'interface_modify.h'), 'w') as f2:
        for lineNumber, line in enumerate(f1):
            if line == " /*** @GENERATED CODE START - DO NOT TOUCH@ ***/\n":
                
                line += (
                    f"#define AI_NETWORK_INPUTS_IN_ACTIVATIONS_INDEX "
                    f"{input_buffer_activation_buffer_index}"
                    f"\n#define AI_NETWORK_INPUTS_IN_ACTIVATIONS_SIZE "
                    f"AI_ACTIVATION_{input_buffer_activation_buffer_index+1}_SIZE_BYTES\n\n"
                )
                f2.write(line)
                writeLine = False
            if line == " /*** @GENERATED CODE STOP - DO NOT TOUCH@ ***/\n":
                writeLine = True
            if writeLine:
                f2.write(line)
    os.replace(
        os.path.join(os.path.dirname(path_ai_interface_h), 'interface_modify.h'),
        path_ai_interface_h
    )