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"

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!");

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);

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"));

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]	dest	buffer to copy into
[in]	src	flash data to copy
[in]	n	number 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.