add_embedded_resource

Adds an embedded resource to one or more targets.

Syntax

add_embedded_resource(
    NAME <internal name>
    SOURCE <path>
    TARGETS <target list>

    SECTION <section name>
    GENERATED_HEADER <header file name>

    [FORCE_LINK]
)

Overview

The add_embedded_resource statement adds an arbitrary binary file into the project and exposes it to the source code as a variable. It can be used to include pictures, configuration files, or any other chunks of data.

Embedded resources are normally placed into the main FLASH memory togethewith the code.

Parameters

NAME: Specifies an internal name of the resource. It affects the internal symbol name and the variable name in the EmbeddedResources namespace.

SOURCE: Specifies the path to the resource file. Can be absolute or relative to the current source directory.

TARGETS: Specifies the list of targets, separated by spaces, where the resource will be added.

SECTION: Optional. Specifies the section where the resource will be placed. Defaults to .rodata that will be placed into the default FLASH memory together with constants defined in the code. You can place embedded resources into different memories by changing their section names and editing the linker script to place the resource section elsewhere.

GENERATED_HEADER: Optional. Specifies the name of the generated header file that will contain the declaration of the resource as a variable. Defaults to EmbeddedResources.h.

FORCE_LINK: If specified, the resource will be physically present in memory even if it's not referenced by the code. Otherwise, unused resources will be automatically discarded by the linker.

Remarks

VisualGDB will automatically generate this statement when you use the Add->Add Embedded Resource(s) command in Solution Explorer.

If you would like to embed an output of another target into one or more targets, use the embed_target_output statement instead.

Examples

The following example includes the logo.png file as an embedded resource and loads it from the C and C++ code:

CMakeLists.txt:

add_bsp_based_executable(NAME ResourceDemo
                         SOURCES ResourceDemo.cpp PlainCDemo.c)
add_embedded_resource(NAME logo
                      SOURCE logo.png
                      TARGETS ResourceDemo)

ResourceDemo.cpp:

#include <EmbeddedResources.h>
using namespace EmbeddedResources;

void DisplayLogo()
{
    const void *start = logo.data();
    size_t size = logo.size();
    DisplayPNG(start, size);
}

ResourceDemo.c:

#include <EmbeddedResources.h>

void DisplayLogo()
{
    const void *start = logo_start;
    size_t size = ((char *)logo_end) - ((char *)logo_start);
    DisplayPNG(start, size);
}

In the following example, the resource is placed into an external memory called FLASH2:

CMakeLists.txt:

add_embedded_resource(NAME logo
                      SOURCE logo.png
                      SECTION .logo
                      TARGETS ResourceDemo)

ResourceDemo.ld:

MEMORY
{
    FLASH (RX)   : ORIGIN = 0x08000000, LENGTH = 1M
    FLASH2 (RX)  : ORIGIN = 0x10000000, LENGTH = 1M
}

SECTIONS
{
    <...>

    .logo :
    {
        *(.logo*)
    } > FLASH2
}

Download

Tutorials

Documentation