Memory mapped persistence storage (like NVRAM or EEPROM) API on Soletta. More...

Data Structures
struct	sol_memmap_entry
	A memory map entry. More...

struct	sol_memmap_map
	Memory map basic struct. More...

Macros
#define	CREATE_BLOB(_val)
	Macro to create a struct sol_blob with value passed as argument. More...

#define	CREATE_BUFFER(_val)
	Macro to create a struct sol_buffer with value passed as argument and flags SOL_BUFFER_FLAGS_MEMORY_NOT_OWNED and SOL_BUFFER_FLAGS_NO_NUL_BYTE. More...

#define	SOL_MEMMAP_BOOL_ENTRY(_name, _offset, _bit_offset) SOL_MEMMAP_ENTRY_BIT_SIZE(_name, _offset, 1, _bit_offset, 1)
	Macro to declare a sol_memmap_entry variable for boolean. More...

#define	SOL_MEMMAP_ENTRY(_name, _offset, _size) SOL_MEMMAP_ENTRY_BIT_SIZE(_name, _offset, _size, 0, 0)
	Macro to declare a sol_memmap_entry variable without bit_offset and bit_size. More...

#define	SOL_MEMMAP_ENTRY_BIT_SIZE(_name, _offset, _size, _bit_offset, _bit_size) static struct sol_memmap_entry _name = { .offset = (_offset), .size = (_size), .bit_size = (_bit_size), .bit_offset = (_bit_offset) }
	Macro to declare a sol_memmap_entry variable setting fields with values passed by argument. More...

#define	SOL_MEMMAP_VERSION_ENTRY "_version"
	Name of property which contains stored map version. More...

Typedefs
typedef struct sol_memmap_entry	sol_memmap_entry
	A memory map entry. More...

typedef struct sol_memmap_map	sol_memmap_map
	Memory map basic struct. More...

Functions
int	sol_memmap_add_map (const struct sol_memmap_map *map)
	Add a map to internal list of available maps. More...

uint32_t	sol_memmap_get_timeout (const struct sol_memmap_map *map)
	Get map timeout. More...

static int	sol_memmap_read_bool (const char name, bool value)
	Reads a boolean contents. More...

static int	sol_memmap_read_double (const char name, double value)
	Reads a double contents. More...

static int	sol_memmap_read_drange (const char name, struct sol_drange value)
	Reads a drange contents. More...

static int	sol_memmap_read_int32 (const char name, int32_t value)
	Reads an int32_t contents. More...

static int	sol_memmap_read_irange (const char name, struct sol_irange value)
	Reads an irange content. More...

int	sol_memmap_read_raw (const char name, struct sol_buffer buffer)
	Read storage contents to buffer. More...

static int	sol_memmap_read_string (const char name, char *value)
	Reads a string contents. More...

static int	sol_memmap_read_uint8 (const char name, uint8_t value)
	Read an uint8_t contents. More...

int	sol_memmap_remove_map (const struct sol_memmap_map *map)
	Removes a previously added map from internal list of available maps. More...

int	sol_memmap_set_timeout (struct sol_memmap_map *map, uint32_t timeout)
	Defines map timeout to actually perform write. More...

static int	sol_memmap_write_bool (const char name, bool value, void(cb)(void data, const char name, struct sol_blob blob, int status), const void data)
	Writes a bool contents to storage. More...

static int	sol_memmap_write_double (const char name, double value, void(cb)(void data, const char name, struct sol_blob blob, int status), const void data)
	Writes a double contents to storage. More...

static int	sol_memmap_write_drange (const char name, struct sol_drange value, void(cb)(void data, const char name, struct sol_blob blob, int status), const void *data)
	Writes an drange contents to storage. More...

static int	sol_memmap_write_int32 (const char name, int32_t value, void(cb)(void data, const char name, struct sol_blob blob, int status), const void data)
	Writes an int32_t contents to storage. More...

static int	sol_memmap_write_irange (const char name, struct sol_irange value, void(cb)(void data, const char name, struct sol_blob blob, int status), const void *data)
	Writes an irange contents to storage. More...

int	sol_memmap_write_raw (const char name, struct sol_blob blob, void(cb)(void data, const char name, struct sol_blob blob, int status), const void *data)
	Writes buffer contents to storage. More...

static int	sol_memmap_write_string (const char name, const char value, void(cb)(void data, const char name, struct sol_blob blob, int status), const void *data)
	Writes a string contents to storage. More...

static int	sol_memmap_write_uint8 (const char name, uint8_t value, void(cb)(void data, const char name, struct sol_blob blob, int status), const void data)
	Writes an uint8_t contents to storage. More...

Detailed Description

Memory mapped persistence storage (like NVRAM or EEPROM) API on Soletta.

A map must be provided, either directly via sol_memmap_add_map() or by informing a JSON file to Soletta runner or generator. This map needs to contain a property _version (SOL_MEMMAP_VERSION_ENTRY), which will store version of map stored. This API will refuse to work if stored map is different from map version. Note that _version field is a uint8_t and that versions should start on 1, so Soletta will know if dealing with a totally new storage. It also considers 255 (0xff) as a non-value, so fit new EEPROMs. Note that a map may define a timeout value to perform writes. This way, writings can be grouped together, as all writing operations will be performed at timeout end. That said, it's important to note that when writing is performed, no order is guaranteed for different keys, i.e., writing to 'a' and 'b' can be performed, at timeout end, as 'b' and 'a'

but for a given key, only the last write will be performed at timeout end. Multiple writes for the same key before timeout end will result in previous writes being replaced, and their callbacks will be informed with status -ECANCELED.

Macro Definition Documentation

#define CREATE_BLOB ( _val )

Value:

struct sol_blob *blob; \
    size_t _s = sizeof(*_val); \
    void *v = malloc(_s); \
    SOL_NULL_CHECK(v, -ENOMEM); \
    memcpy(v, _val, _s); \
    blob = sol_blob_new(&SOL_BLOB_TYPE_DEFAULT, NULL, v, _s); \
    if (!blob) { \
        free(v); \
        return -EINVAL; \
    }

Macro to create a struct sol_blob with value passed as argument.

Referenced by sol_memmap_write_bool(), sol_memmap_write_double(), sol_memmap_write_drange(), sol_memmap_write_int32(), sol_memmap_write_irange(), and sol_memmap_write_uint8().

#define CREATE_BUFFER ( _val )

Value:

struct sol_buffer buf = SOL_BUFFER_INIT_FLAGS(_val, \

sizeof(*(_val)), SOL_BUFFER_FLAGS_MEMORY_NOT_OWNED | SOL_BUFFER_FLAGS_NO_NUL_BYTE);

SOL_BUFFER_FLAGS_MEMORY_NOT_OWNED

Buffers where the buf->data is not owned by sol_buffer, that is, it can't be resized and free() should...

Definition: sol-buffer.h:88

SOL_BUFFER_INIT_FLAGS

#define SOL_BUFFER_INIT_FLAGS(data_, size_, flags_)

Helper macro to initialize an buffer with the given data and flags.

Definition: sol-buffer.h:164

sol_buffer

A sol_buffer is a dynamic array, that can be resized if needed.

Definition: sol-buffer.h:130

SOL_BUFFER_FLAGS_NO_NUL_BYTE

Do not reserve space for the NUL byte.

Definition: sol-buffer.h:92

Macro to create a struct sol_buffer with value passed as argument and flags SOL_BUFFER_FLAGS_MEMORY_NOT_OWNED and SOL_BUFFER_FLAGS_NO_NUL_BYTE.

Referenced by sol_memmap_read_bool(), sol_memmap_read_double(), sol_memmap_read_drange(), sol_memmap_read_int32(), sol_memmap_read_irange(), and sol_memmap_read_uint8().

#define SOL_MEMMAP_BOOL_ENTRY	(	_name,
		_offset,
		_bit_offset
	)	SOL_MEMMAP_ENTRY_BIT_SIZE(_name, _offset, 1, _bit_offset, 1)

Macro to declare a sol_memmap_entry variable for boolean.

So size and bit_size are set to 1.

#define SOL_MEMMAP_ENTRY	(	_name,
		_offset,
		_size
	)	SOL_MEMMAP_ENTRY_BIT_SIZE(_name, _offset, _size, 0, 0)

Macro to declare a sol_memmap_entry variable without bit_offset and bit_size.

#define SOL_MEMMAP_ENTRY_BIT_SIZE	(	_name,
		_offset,
		_size,
		_bit_offset,
		_bit_size
	)	static struct sol_memmap_entry _name = { .offset = (_offset), .size = (_size), .bit_size = (_bit_size), .bit_offset = (_bit_offset) }

Macro to declare a sol_memmap_entry variable setting fields with values passed by argument.

#define SOL_MEMMAP_VERSION_ENTRY "_version"

Name of property which contains stored map version.

Typedef Documentation

typedef struct sol_memmap_entry sol_memmap_entry

A memory map entry.

See Also: sol_memmap_map

typedef struct sol_memmap_map sol_memmap_map

Memory map basic struct.

This struct holds informations about a memory map.

Function Documentation

int sol_memmap_add_map ( const struct sol_memmap_map * map )

Add a map to internal list of available maps.

As Soletta will keep a reference to this map, it should be kept alive during memmap usage.

Parameters

map	map to be add.

Returns: 0 on success, a negative number on failure.

uint32_t sol_memmap_get_timeout ( const struct sol_memmap_map * map )

Get map timeout.

See Also: sol_memmap_set_timeout() for more details.

Parameters

map	map to get its timeout

Returns: timeout in milliseconds.

static int sol_memmap_read_bool	(	const char *	name,
		bool *	value
	)

inlinestatic

Reads a boolean contents.

Parameters

name	name of property. must be present in one of maps previoulsy added via sol_memmap_add_map() (if present in more than one, behaviour is undefined)
value	where result will be read into, according to its entry

return 0 on success, a negative number on failure

References CREATE_BUFFER, and sol_memmap_read_raw().

static int sol_memmap_read_double	(	const char *	name,
		double *	value
	)

inlinestatic

Reads a double contents.

Parameters

name	name of property. must be present in one of maps previoulsy added via sol_memmap_add_map() (if present in more than one, behaviour is undefined)
value	where result will be read into, according to its entry

return 0 on success, a negative number on failure

References CREATE_BUFFER, and sol_memmap_read_raw().

static int sol_memmap_read_drange	(	const char *	name,
		struct sol_drange *	value
	)

inlinestatic

Reads a drange contents.

Parameters

name	name of property. must be present in one of maps previoulsy added via sol_memmap_add_map() (if present in more than one, behaviour is undefined)
value	where result will be read into, according to its entry

return 0 on success, a negative number on failure

sol_drange

References CREATE_BUFFER, and sol_memmap_read_raw().

static int sol_memmap_read_int32	(	const char *	name,
		int32_t *	value
	)

inlinestatic

Reads an int32_t contents.

Parameters

name	name of property. must be present in one of maps previoulsy added via sol_memmap_add_map() (if present in more than one, behaviour is undefined)
value	where result will be read into, according to its entry

return 0 on success, a negative number on failure

References CREATE_BUFFER, and sol_memmap_read_raw().

static int sol_memmap_read_irange	(	const char *	name,
		struct sol_irange *	value
	)

inlinestatic

Reads an irange content.

Parameters

name	name of property. must be present in one of maps previoulsy added via sol_memmap_add_map() (if present in more than one, behaviour is undefined)
value	where result will be read into, according to its entry

return 0 on success, a negative number on failure

sol_irange

References CREATE_BUFFER, and sol_memmap_read_raw().

int sol_memmap_read_raw	(	const char *	name,
		struct sol_buffer *	buffer
	)

Read storage contents to buffer.

Parameters

name	name of property. must be present in one of maps previoulsy added via sol_memmap_add_map() (if present in more than one, behaviour is undefined)
buffer	buffer where result will be read into, according to its entry on map.

return 0 on success, a negative number on failure

Referenced by sol_memmap_read_bool(), sol_memmap_read_double(), sol_memmap_read_drange(), sol_memmap_read_int32(), sol_memmap_read_irange(), sol_memmap_read_string(), and sol_memmap_read_uint8().

static int sol_memmap_read_string	(	const char *	name,
		char **	value
	)

inlinestatic

Reads a string contents.

Parameters

name	name of property. must be present in one of maps previoulsy added via sol_memmap_add_map() (if present in more than one, behaviour is undefined)
value	where result will be read into, according to its entry

return 0 on success, a negative number on failure

References sol_buffer_fini(), SOL_BUFFER_INIT_EMPTY, sol_buffer_steal(), and sol_memmap_read_raw().

static int sol_memmap_read_uint8	(	const char *	name,
		uint8_t *	value
	)

inlinestatic

Read an uint8_t contents.

Parameters

name	name of property. must be present in one of maps previoulsy added via sol_memmap_add_map() (if present in more than one, behaviour is undefined)
value	where result will be read into, according to its entry

return 0 on success, a negative number on failure

References CREATE_BUFFER, and sol_memmap_read_raw().

int sol_memmap_remove_map ( const struct sol_memmap_map * map )

Removes a previously added map from internal list of available maps.

Parameters

map	map to be removed.

Returns: 0 on success, a negative number on failure.

int sol_memmap_set_timeout	(	struct sol_memmap_map *	map,
		uint32_t	timeout
	)

Defines map timeout to actually perform write.

Parameters

map	map to have its timeout changed
timeout	new timeout, in milliseconds.

Returns: 0 on success, a negative number on failure.

Note: This change will take effect after current active timer expires. Active ones will remain unchanged

static int sol_memmap_write_bool	(	const char *	name,
		bool	value,
		void()(void data, const char name, struct sol_blob blob, int status)	cb,
		const void *	data
	)

inlinestatic

Writes a bool contents to storage.

This funcion uses the function sol_memmap_write_raw() internally, so the same behaviour must be considered.

Parameters

name	name of property. must be present in one of maps previoulsy added via sol_memmap_add_map() (if present in more than one, behaviour is undefined)
value	the variable containing the value to be written.
cb	callback to be called when writing finishes. It contains status of writing: if failed, is lesser than zero.
data	user data to be sent to callback cb

return 0 on success, a negative number on failure

See Also: sol_memmap_write_raw()

References CREATE_BLOB, sol_blob_unref(), and sol_memmap_write_raw().

static int sol_memmap_write_double	(	const char *	name,
		double	value,
		void()(void data, const char name, struct sol_blob blob, int status)	cb,
		const void *	data
	)

inlinestatic

Writes a double contents to storage.

This funcion uses the function sol_memmap_write_raw() internally, so the same behaviour must be considered.

Parameters

name	name of property. must be present in one of maps previoulsy added via sol_memmap_add_map() (if present in more than one, behaviour is undefined)
value	the variable containing the value to be written.
cb	callback to be called when writing finishes. It contains status of writing: if failed, is lesser than zero.
data	user data to be sent to callback cb

return 0 on success, a negative number on failure

See Also: sol_memmap_write_raw()

References CREATE_BLOB, sol_blob_unref(), and sol_memmap_write_raw().

static int sol_memmap_write_drange	(	const char *	name,
		struct sol_drange *	value,
		void()(void data, const char name, struct sol_blob blob, int status)	cb,
		const void *	data
	)

inlinestatic

Writes an drange contents to storage.

This funcion uses the function sol_memmap_write_raw() internally, so the same behaviour must be considered.

Parameters

name	name of property. must be present in one of maps previoulsy added via sol_memmap_add_map() (if present in more than one, behaviour is undefined)
value	the variable containing the value to be written.
cb	callback to be called when writing finishes. It contains status of writing: if failed, is lesser than zero.
data	user data to be sent to callback cb

return 0 on success, a negative number on failure

See Also: sol_memmap_write_raw() sol_drange

References CREATE_BLOB, sol_blob_unref(), and sol_memmap_write_raw().

static int sol_memmap_write_int32	(	const char *	name,
		int32_t	value,
		void()(void data, const char name, struct sol_blob blob, int status)	cb,
		const void *	data
	)

inlinestatic

Writes an int32_t contents to storage.

This funcion uses the function sol_memmap_write_raw() internally, so the same behaviour must be considered.

Parameters

name	name of property. must be present in one of maps previoulsy added via sol_memmap_add_map() (if present in more than one, behaviour is undefined)
value	the variable containing the value to be written.
cb	callback to be called when writing finishes. It contains status of writing: if failed, is lesser than zero.
data	user data to be sent to callback cb

return 0 on success, a negative number on failure

See Also: sol_memmap_write_raw()

References CREATE_BLOB, sol_blob_unref(), and sol_memmap_write_raw().

static int sol_memmap_write_irange	(	const char *	name,
		struct sol_irange *	value,
		void()(void data, const char name, struct sol_blob blob, int status)	cb,
		const void *	data
	)

inlinestatic

Writes an irange contents to storage.

This funcion uses the function sol_memmap_write_raw() internally, so the same behaviour must be considered.

Parameters

name	name of property. must be present in one of maps previoulsy added via sol_memmap_add_map() (if present in more than one, behaviour is undefined)
value	the variable containing the value to be written.
cb	callback to be called when writing finishes. It contains status of writing: if failed, is lesser than zero.
data	user data to be sent to callback cb

return 0 on success, a negative number on failure

See Also: sol_memmap_write_raw() sol_irange

References CREATE_BLOB, sol_blob_unref(), and sol_memmap_write_raw().

int sol_memmap_write_raw	(	const char *	name,
		struct sol_blob *	blob,
		void()(void data, const char name, struct sol_blob blob, int status)	cb,
		const void *	data
	)

Writes buffer contents to storage.

Note that as writing operations are asynchronous, to check if it completely succeeded, one needs to register a callback that will inform writing result. A negative status on callback means failure; -ECANCELED for instance, means that another write to the same property took place before this one was completed.

Parameters

name	name of property. must be present in one of maps previoulsy added via sol_memmap_add_map() (if present in more than one, behaviour is undefined)
blob	blob that will be written, according to its entry on map.
cb	callback to be called when writing finishes. It contains status of writing: if failed, is lesser than zero.
data	user data to be sent to callback cb

return 0 on success, a negative number on failure

Referenced by sol_memmap_write_bool(), sol_memmap_write_double(), sol_memmap_write_drange(), sol_memmap_write_int32(), sol_memmap_write_irange(), sol_memmap_write_string(), and sol_memmap_write_uint8().

static int sol_memmap_write_string	(	const char *	name,
		const char *	value,
		void()(void data, const char name, struct sol_blob blob, int status)	cb,
		const void *	data
	)

inlinestatic

Writes a string contents to storage.

This funcion uses the function sol_memmap_write_raw() internally, so the same behaviour must be considered.

Parameters

name	name of property. must be present in one of maps previoulsy added via sol_memmap_add_map() (if present in more than one, behaviour is undefined)
value	the variable containing the value to be written.
cb	callback to be called when writing finishes. It contains status of writing: if failed, is lesser than zero.
data	user data to be sent to callback cb

return 0 on success, a negative number on failure

See Also: sol_memmap_write_raw()

References sol_blob_new(), SOL_BLOB_TYPE_DEFAULT, sol_blob_unref(), sol_memmap_write_raw(), SOL_NULL_CHECK, and SOL_NULL_CHECK_GOTO.

static int sol_memmap_write_uint8	(	const char *	name,
		uint8_t	value,
		void()(void data, const char name, struct sol_blob blob, int status)	cb,
		const void *	data
	)

inlinestatic

Writes an uint8_t contents to storage.

This funcion uses the function sol_memmap_write_raw() internally, so the same behaviour must be considered.

Parameters

name	name of property. must be present in one of maps previoulsy added via sol_memmap_add_map() (if present in more than one, behaviour is undefined)
value	the variable containing the value to be written.
cb	callback to be called when writing finishes. It contains status of writing: if failed, is lesser than zero.
data	user data to be sent to callback cb

return 0 on success, a negative number on failure

See Also: sol_memmap_write_raw()

References CREATE_BLOB, sol_blob_unref(), and sol_memmap_write_raw().

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Function Documentation