Loading...
Searching...
No Matches
Utility functions, macros, and types for

read-only memory More...

Detailed Description

read-only memory

This modules adds utility functions, macros, and functions for read-only memory. The goal is to hide the differences between modified architectures that map flash into the data address space (e.g. ARM) and those which doesn't (e.g. most AVR, Xtensa).

Usage

#include "flash_utils.h"
Utility functions, macros, and types for read-only memory.

No module needs to be selected, this is a header-only implementation that is always available.

Porting Code to Use <tt>flash_utils</tt>

This is mainly targeting applications developers to ease developing apps that work well on both legacy modified Harvard architectures (e.g. ATmega) and modern modified Harvard architectures (e.g. ARM, ATtiny, ...) as well as von-Neumann machines.

The intention is to limit in-tree use to a very small number of modules that yield the most "bang for the buck" and not leak the use of flash_utils through the API. Specifically, reverting to not using flash_utils should not be noticed by any user (unless looking at memory consumption).

Files

file  flash_utils.h
 Utility functions, macros, and types for read-only memory.
 

Macros

#define FLASH_ATTR   <IMPLEMTATION_DEFINED>
 C type qualifier required to place a variable in flash.
 
#define PRIsflash   <IMPLEMTATION_DEFINED>
 Format specifier for printing FLASH CONST char *
 
#define TO_FLASH(str_literal)   <IMPLEMTATION_DEFINED>
 Macro to allocate a string literal on flash and return a FLASH_ATTR const char * pointer to it Usage:
 
#define FLASH_PUTS(x)   flash_puts(TO_FLASH(x))
 A convenience wrapper for flash_puts(TO_FLASH("str literal"))
 

Functions

int flash_strcmp (const char *ram, FLASH_ATTR const char *flash)
 Like strcmp(), but the second string resides in flash.
 
int flash_strncmp (const char *ram, FLASH_ATTR const char *flash, size_t n)
 Like strncmp(), but the first string resides in flash.
 
size_t flash_strlen (FLASH_ATTR const char *flash)
 Like strlen(), but the string resides in flash.
 
char * flash_strcpy (char *ram, FLASH_ATTR const char *flash)
 Like strcpy(), but the source flash resides in flash.
 
char * flash_strncpy (char *ram, FLASH_ATTR const char *flash, size_t n)
 Like strncpy(), but the source flash resides in flash.
 
int flash_printf (FLASH_ATTR const char *flash,...)
 Like printf(), but the format string resides in flash.
 
int flash_vprintf (FLASH_ATTR const char *flash, va_list args)
 Like vprintf(), but the format string resides in flash.
 
int flash_fprintf (FILE *stream, FLASH_ATTR const char *flash,...)
 Like fprintf(), but the format string resides in flash.
 
int flash_vfprintf (FILE *stream, FLASH_ATTR const char *flash, va_list args)
 Like vfprintf(), but the format string resides in flash.
 
int flash_snprintf (char *buf, size_t buf_len, FLASH_ATTR const char *flash,...)
 Like snprintf(), but the format string resides in flash.
 
int flash_vsnprintf (char *buf, size_t buf_len, FLASH_ATTR const char *flash, va_list args)
 Like vsnprintf(), but the format string resides in flash.
 
void flash_puts (FLASH_ATTR const char *flash)
 Like puts(), but the string resides in flash.
 
void * flash_memcpy (void *dest, FLASH_ATTR const void *src, size_t n)
 Like memcpy(), but src resides in flash.
 
static void flash_print_str (FLASH_ATTR const char *flash)
 Like flash_puts but without line break.
 

Macro Definition Documentation

◆ FLASH_ATTR

#define FLASH_ATTR   <IMPLEMTATION_DEFINED>

C type qualifier required to place a variable in flash.

Definition at line 68 of file flash_utils.h.

◆ FLASH_PUTS

#define FLASH_PUTS (   x)    flash_puts(TO_FLASH(x))

A convenience wrapper for flash_puts(TO_FLASH("str literal"))

Usage:

FLASH_PUTS("Hello world!");
#define FLASH_PUTS(x)
A convenience wrapper for flash_puts(TO_FLASH("str literal"))

Definition at line 240 of file flash_utils.h.

◆ PRIsflash

#define PRIsflash   <IMPLEMTATION_DEFINED>

Format specifier for printing FLASH CONST char *

Usage:

FLASH_ATTR const char fmt[] = "I am printing \"%" PRIsflash "\" from flash\n";
FLASH_ATTR const char msg[] = "message from flash";
flash_printf(fmt, msg);
#define PRIsflash
Format specifier for printing FLASH CONST char *
Definition flash_utils.h:80
#define FLASH_ATTR
C type qualifier required to place a variable in flash.
Definition flash_utils.h:68
int flash_printf(FLASH_ATTR const char *flash,...)
Like printf(), but the format string resides in flash.

Definition at line 80 of file flash_utils.h.

◆ TO_FLASH

#define TO_FLASH (   str_literal)    <IMPLEMTATION_DEFINED>

Macro to allocate a string literal on flash and return a FLASH_ATTR const char * pointer to it Usage:

flash_puts(TO_FLASH("Hello world"));
#define TO_FLASH(str_literal)
Macro to allocate a string literal on flash and return a FLASH_ATTR const char * pointer to it Usage:
Definition flash_utils.h:91
void flash_puts(FLASH_ATTR const char *flash)
Like puts(), but the string resides in flash.

Definition at line 91 of file flash_utils.h.

Function Documentation

◆ flash_fprintf()

int flash_fprintf ( FILE *  stream,
FLASH_ATTR const char *  flash,
  ... 
)

Like fprintf(), but the format string resides in flash.

This will be a zero-overhead wrapper on top of fprintf() for von-Neumann architectures or Harvard architectures that also map their flash into the data address space.

◆ flash_memcpy()

void * flash_memcpy ( void *  dest,
FLASH_ATTR const void *  src,
size_t  n 
)

Like memcpy(), but src resides in flash.

Parameters
[out]destbuffer to copy into
[in]srcflash data to copy
[in]nnumber of bytes to copy

◆ flash_print_str()

static void flash_print_str ( FLASH_ATTR const char *  flash)
inlinestatic

Like flash_puts but without line break.

Definition at line 245 of file flash_utils.h.

◆ flash_printf()

int flash_printf ( FLASH_ATTR const char *  flash,
  ... 
)

Like printf(), but the format string resides in flash.

This will be a zero-overhead wrapper on top of printf() for von-Neumann architectures or Harvard architectures that also map their flash into the data address space.

◆ flash_puts()

void flash_puts ( FLASH_ATTR const char *  flash)

Like puts(), but the string resides in flash.

This will be a zero-overhead wrapper on top of puts() for von-Neumann architectures or Harvard architectures that also map their flash into the data address space.

◆ flash_snprintf()

int flash_snprintf ( char *  buf,
size_t  buf_len,
FLASH_ATTR const char *  flash,
  ... 
)

Like snprintf(), but the format string resides in flash.

This will be a zero-overhead wrapper on top of snprintf() for von-Neumann architectures or Harvard architectures that also map their flash into the data address space.

◆ flash_strcmp()

int flash_strcmp ( const char *  ram,
FLASH_ATTR const char *  flash 
)

Like strcmp(), but the second string resides in flash.

This will be a zero-overhead wrapper on top of strcmp() for von-Neumann architectures or Harvard architectures that also map their flash into the data address space.

◆ flash_strcpy()

char * flash_strcpy ( char *  ram,
FLASH_ATTR const char *  flash 
)

Like strcpy(), but the source flash resides in flash.

This will be a zero-overhead wrapper on top of strcpy() for von-Neumann architectures or Harvard architectures that also map their flash into the data address space.

◆ flash_strlen()

size_t flash_strlen ( FLASH_ATTR const char *  flash)

Like strlen(), but the string resides in flash.

This will be a zero-overhead wrapper on top of strlen() for von-Neumann architectures or Harvard architectures that also map their flash into the data address space.

◆ flash_strncmp()

int flash_strncmp ( const char *  ram,
FLASH_ATTR const char *  flash,
size_t  n 
)

Like strncmp(), but the first string resides in flash.

This will be a zero-overhead wrapper on top of strncmp() for von-Neumann architectures or Harvard architectures that also map their flash into the data address space.

◆ flash_strncpy()

char * flash_strncpy ( char *  ram,
FLASH_ATTR const char *  flash,
size_t  n 
)

Like strncpy(), but the source flash resides in flash.

This will be a zero-overhead wrapper on top of strncpy() for von-Neumann architectures or Harvard architectures that also map their flash into the data address space.

◆ flash_vfprintf()

int flash_vfprintf ( FILE *  stream,
FLASH_ATTR const char *  flash,
va_list  args 
)

Like vfprintf(), but the format string resides in flash.

This will be a zero-overhead wrapper on top of vfprintf() for von-Neumann architectures or Harvard architectures that also map their flash into the data address space.

◆ flash_vprintf()

int flash_vprintf ( FLASH_ATTR const char *  flash,
va_list  args 
)

Like vprintf(), but the format string resides in flash.

This will be a zero-overhead wrapper on top of vprintf() for von-Neumann architectures or Harvard architectures that also map their flash into the data address space.

◆ flash_vsnprintf()

int flash_vsnprintf ( char *  buf,
size_t  buf_len,
FLASH_ATTR const char *  flash,
va_list  args 
)

Like vsnprintf(), but the format string resides in flash.

This will be a zero-overhead wrapper on top of vsnprintf() for von-Neumann architectures or Harvard architectures that also map their flash into the data address space.