Collaboration diagram for Utilities:

Classes
struct	argument_type< T >

struct	argument_type< T(U)>

Macros
#define	DECL(t) argument_type<void(t)>::type
	Wrap a type declaration so it can be passed with commas in it. More...

#define	IMPORT_FSTR_DATA(name, file)
	Link the contents of a file. More...

#define	STR(x) XSTR(x)

#define	XSTR(x) #x

#define	IMPORT_FSTR_DATA_SECTION(name)

#define	DECLARE_FSTR_IMPORT(ObjectType, name) extern const ObjectType name __asm__(STR(name));
	Declare a reference to an `IMPORT_FSTR_DATA` block. More...

Detailed Description

Macro Definition Documentation

◆ DECL

#define DECL ( t ) argument_type<void(t)>::type

Wrap a type declaration so it can be passed with commas in it.

Example:

template <typename ElementType, size_t Columns>
struct MultiRow
{
    ElementType values[Columns];
}

These fail:

    DECLARE_FSTR_ARRAY(myArray, MultiRow<double, 3>);
    DECLARE_FSTR_ARRAY(myArray, (MultiRow<double, 3>));

Use DECL like this:

    DECLARE_FSTR_ARRAY(myArray, DECL((MultiRow<double, 3>)) );

Although for this example we should probably do this:

    using MultiRow_double_3 = MultiRow<double, 3>;
    DECLARE_FSTR_ARRAY(myArray, MultiRow_double_3);

◆ DECLARE_FSTR_IMPORT

#define DECLARE_FSTR_IMPORT	(	ObjectType,
		name
	)	extern const ObjectType name __asm__(STR(name));

Declare a reference to an IMPORT_FSTR_DATA block.

When referencing inline assembler labels using extern "C" tells the compiler not to mangle the name. However, doing that inside an anonymous namespace leads to undefined behaviour and breaks with GCC 15. Using an explicit asm(label) directive makes this unambiguous. See https://gcc.gnu.org/onlinedocs/gcc/Asm-Labels.html

◆ IMPORT_FSTR_DATA

#define IMPORT_FSTR_DATA	(	name,
		file
	)

Value:

    __asm__(IMPORT_FSTR_DATA_SECTION(name)                     \
            ".align 4\n"                                       \
            STR(name) ":\n"                                    \
            ".long " STR(name) "_end - " STR(name) " - 4\n"    \
            ".incbin \"" file "\"\n"                           \
            STR(name) "_end:\n");

Link the contents of a file.

This provides a more efficient way to read constant (read-only) file data. The file content is bound into firmware image at link time.

We need inline assembler's .incbin instruction to actually import the data. We use a macro STR() so that if required the name can be resolved from a #defined value.

Use PROJECT_DIR to locate files in your project's source tree:

IMPORT_FSTR_DATA(myFlashData, PROJECT_DIR "/files/my_flash_file.txt");

Use COMPONENT_PATH within a component.

No C/C++ symbol is declared, this is type-dependent and must be done separately:

DECLARE_FSTR_IMPORT(FSTR::String, myFlashData);

If the symbol is not referenced the content will be discarded by the linker.

◆ IMPORT_FSTR_DATA_SECTION

#define IMPORT_FSTR_DATA_SECTION ( name )

Value:

".section " ICACHE_RODATA_SECTION "." STR(name) "\n" \

".type " STR(name) ", @object\n"

◆ STR

#define STR ( x ) XSTR(x)

◆ XSTR

#define XSTR ( x ) #x

Classes

Macros