Program space

Support for data stored in flash memory. More...

Collaboration diagram for Program space:

Macros
#define	IS_ALIGNED(_x)   (((uint32_t)(_x)&3) == 0)
	determines if the given value is aligned to a word (4-byte) boundary More...
#define	ALIGNUP4(n)   (((n) + 3) & ~3)
	Align a size up to the nearest word boundary. More...
#define	ALIGNDOWN4(n)   ((n) & ~3)
	Align a size down to the nearest word boundary. More...
#define	printf_P_heap(f_P, ...)
#define	printf_P_stack(f_P, ...)
#define	printf_P(fmt, ...)   m_printf(fmt, ##__VA_ARGS__)
#define	PSTR_COUNTED(str)
	Define and use a counted flash string inline. More...
#define	_F(str)   (str)
#define	DEFINE_PSTR(name, str)   const char name[] PROGMEM_PSTR = str;
	define a PSTR More...
#define	DEFINE_PSTR_LOCAL(name, str)   static DEFINE_PSTR(name, str)
	define a PSTR for local (static) use More...
#define	DECLARE_PSTR(name)   extern const char name[];
	Declare a global reference to a PSTR instance. More...
#define	LOAD_PSTR(name, flash_str)
	Create a local (stack) buffer called name and load it with flash data. More...
#define	_FLOAD(pstr)
#define	PSTR_ARRAY(name, str)
	Define a flash string and load it into a named array buffer on the stack. More...

Functions
void *	memcpy_aligned (void *dst, const void *src, unsigned len)
	copy memory aligned to word boundaries More...
int	memcmp_aligned (const void *ptr1, const void *ptr2, unsigned len)
	compare memory aligned to word boundaries More...
#define	FLASH_MEMORY_START_ADDR   0x40200000
#define	isFlashPtr(ptr)   ((uint32_t)ptr >= FLASH_MEMORY_START_ADDR)
	Simple check to determine if a pointer refers to flash memory. More...
#define	PROGMEM   STORE_ATTR ICACHE_RODATA_ATTR
	Place entity into flash memory. More...
#define	PROGMEM_PSTR
	Place NUL-terminated string data into flash memory. More...
#define	PSTR(str)
	Define and use a NUL-terminated 'C' flash string inline. More...
#define	PGM_P   const char*
	Identifies a char pointer as living in flash memory Use to clarify code. More...
#define	PRIPSTR   "%s"
	Remove ? More...

Detailed Description

Support for data stored in flash memory.

Macro Definition Documentation

_F

#define _F

(

str

)

(str)

_FLOAD

#define _FLOAD

(

pstr

)

Value:

    (__extension__({                                                                                                   \
        LOAD_PSTR(_buf, pstr);                                                                                         \
        _buf;                                                                                                          \
    }))

ALIGNDOWN4

#define ALIGNDOWN4

(

n

)

((n) & ~3)

Align a size down to the nearest word boundary.

ALIGNUP4

#define ALIGNUP4

(

n

)

(((n) + 3) & ~3)

Align a size up to the nearest word boundary.

DECLARE_PSTR

#define DECLARE_PSTR

(

name

)

extern const char name[];

Declare a global reference to a PSTR instance.

Parameters

name

DEFINE_PSTR

#define DEFINE_PSTR	(		name,
			str
	)		const char name[] PROGMEM_PSTR = str;

define a PSTR

Parameters

name	name of string
str	the string data

DEFINE_PSTR_LOCAL

#define DEFINE_PSTR_LOCAL	(		name,
			str
	)		static DEFINE_PSTR(name, str)

define a PSTR for local (static) use

Parameters

name	name of string
str	the string data

FLASH_MEMORY_START_ADDR

#define FLASH_MEMORY_START_ADDR   0x40200000

IS_ALIGNED

#define IS_ALIGNED

(

_x

)

(((uint32_t)(_x)&3) == 0)

determines if the given value is aligned to a word (4-byte) boundary

isFlashPtr

#define isFlashPtr

(

ptr

)

((uint32_t)ptr >= FLASH_MEMORY_START_ADDR)

Simple check to determine if a pointer refers to flash memory.

LOAD_PSTR

#define LOAD_PSTR	(		name,
			flash_str
	)

Value:

    char name[ALIGNUP4(sizeof(flash_str))] __attribute__((aligned(4)));                                                \
    memcpy_aligned(name, flash_str, sizeof(flash_str));

Create a local (stack) buffer called name and load it with flash data.

Parameters

name
flash_str	Content stored in flash. The compiler knows its size (length + nul), which is rounded up to multiple of 4 bytes for fast copy.

If defining a string within a function or other local context, must declare static.

Example:

    void testfunc() {
        static DEFINE_PSTR(test, "This is a test string\n");
        m_printf(LOAD_PSTR(test));
    }

PGM_P

#define PGM_P   const char*

Identifies a char pointer as living in flash memory Use to clarify code.

printf_P

#define printf_P	(		fmt,
			...
	)		m_printf(fmt, ##__VA_ARGS__)

printf_P_heap

#define printf_P_heap	(		f_P,
			...
	)

Value:

    (__extension__({                                                                                                   \
        char* __localF = (char*)malloc(strlen_P(f_P) + 1);                                                             \
        strcpy_P(__localF, f_P);                                                                                       \
        int __result = os_printf_plus(__localF, ##__VA_ARGS__);                                                        \
        free(__localF);                                                                                                \
        __result;                                                                                                      \
    }))

printf_P_stack

#define printf_P_stack	(		f_P,
			...
	)

Value:

    (__extension__({                                                                                                   \
        char __localF[256];                                                                                            \
        strncpy_P(__localF, f_P, sizeof(__localF));                                                                    \
        __localF[sizeof(__localF) - 1] = '\0';                                                                         \
        m_printf(__localF, ##__VA_ARGS__);                                                                             \
    }))

PRIPSTR

#define PRIPSTR   "%s"

Remove ?

PROGMEM

#define PROGMEM   STORE_ATTR ICACHE_RODATA_ATTR

Place entity into flash memory.

Attach to const variable declaration to have it stored in flash memory

Such variables should not be accessed like regular pointers as aligned instructions are required. Use the provided library functions, such as memcpy_P, instead.

PROGMEM_PSTR

#define PROGMEM_PSTR

Value:

    STORE_ATTR                                                                                                         \
    __attribute__((section("\".irom0.pstr." __FILE__                                                                   \
                           "." MACROQUOTE(__LINE__) "." MACROQUOTE(__COUNTER__) "\", \"aSM\", @progbits, 1 #")))

Place NUL-terminated string data into flash memory.

Duplicate string data will be merged according to the rules laid out in https://sourceware.org/binutils/docs/as/Section.html

PSTR

#define PSTR

(

str

)

Value:

    (__extension__({                                                                                                   \
        static const char __pstr__[] PROGMEM_PSTR = str;                                                               \
        &__pstr__[0];                                                                                                  \
    }))

Define and use a NUL-terminated 'C' flash string inline.

Parameters

str

Return values

char[]

In flash memory, access using flash functions

Note

Uses string section merging so must not contain embedded NULs

PSTR_ARRAY

#define PSTR_ARRAY	(		name,
			str
	)

Value:

    DEFINE_PSTR_LOCAL(__pstr__##name, str);                                                                            \
    LOAD_PSTR(name, __pstr__##name)

Define a flash string and load it into a named array buffer on the stack.

Note

Must not contain embedded NUL characters

For example, this:

    PSTR_ARRAY(myText, "some text");

is roughly equivalent to this:

    char myText[ALIGNED_SIZE] = "some text";

where ALIGNED_SIZE is the length of the text (including NUL terminator) rounded up to the next word boundary. To get the length of the text, excluding NUL terminator, use:

    sizeof(PSTR_myText) - 1

PSTR_COUNTED

#define PSTR_COUNTED

(

str

)

Value:

    (__extension__({                                                                                                   \
        static const char __pstr__[] PROGMEM = str;                                                                    \
        &__pstr__[0];                                                                                                  \
    }))

Define and use a counted flash string inline.

Parameters

str

Return values

char[]

In flash memory, access using flash functions

Note

Strings are treated as binary data so may contain embedded NULs, but duplicate strings are not merged.

Function Documentation

memcmp_aligned()

int memcmp_aligned	(	const void *	ptr1,
		const void *	ptr2,
		unsigned	len
	)

compare memory aligned to word boundaries

Parameters

ptr1
ptr2
len

Return values

int	0 if all bytes match

ptr1 and ptr2 must all be aligned to word (4-byte) boundaries. len is rounded up to the nearest word boundary

memcpy_aligned()

void* memcpy_aligned	(	void *	dst,
		const void *	src,
		unsigned	len
	)

copy memory aligned to word boundaries

Parameters

dst
src
len	Size of the source data

dst and src must be aligned to word (4-byte) boundaries len will be rounded up to the nearest word boundary, so the dst buffer MUST be large enough for this.