Table of contents   List of declarations
Previous   Next
MutekH reference manual » Developer reference » List of headers » device/class/persist.h header reference

device/class/persist.h header reference
[Devices support library module]

The source code of this header can be browsed online.

Description  

See also DRIVER_CLASS_PERSIST.

Description  

persist driver class exists to offer a basic and simple configuration storage backend based on the usual request pattern.

Operations involve:

  • Read a value,

  • Write a value,

  • Delete a value,

  • Pack storage backend (reclaim unused space),

  • Erase storage.

persist devices can hold up to 2^16 values, distinguished through their UID (unique identifier).

Stored values must have a static declaration (). Values may be of one of two types:

  • Blobs, binary objects read/write verbatim;

  • Counters, 64 bit values that can either be added to or erased.

In order to be able to share a declaration among various similar values, requests may set an uid_offset that gets added to the descriptor's UID when looking up value in storage backend.

Storage backend takes all possible measures to ensure value validity and durability. In particular, special care is taken to ensure no data is lost in case of power outage during write phases.

Size of blobs is known in advance and is part of their declaration. They cannot extend beyond their preallocated size.

Size of counters must be at least 8 bytes, They make no interest under 9 bytes. Any byte beyond 8-th serves as an optimization on increment operations: increments are done in-place using spare bits as an unary value that adds to the counter. This makes sense on flash-based storage backends where a page-erase operation is required before writing new data. Optimal size to allocate to a counter is a usage-dependant tradeof.

See also struct dev_persist_descriptor_s.

Members  

Types  

Functions  

  • struct dev_request_s * dev_persist_rq_s_base(struct dev_persist_rq_s *x)
  • struct dev_persist_rq_s * dev_persist_rq_s_cast(struct dev_request_s *x)
  • error_t dev_persist_spin_op(struct device_persist_s *accessor, struct dev_persist_rq_s *rq)
  • error_t dev_persist_wait_counter_read(struct device_persist_s *accessor, const struct dev_persist_descriptor_s *desc, uint16_t uid_offset, uint64_t *value)
  • error_t dev_persist_wait_inc(struct device_persist_s *accessor, const struct dev_persist_descriptor_s *desc, uint16_t uid_offset)
  • error_t dev_persist_wait_op(struct device_persist_s *accessor, struct dev_persist_rq_s *rq)
  • error_t dev_persist_wait_read(struct device_persist_s *accessor, const struct dev_persist_descriptor_s *desc, uint16_t uid_offset, const void **data)
  • error_t dev_persist_wait_remove(struct device_persist_s *accessor, const struct dev_persist_descriptor_s *desc, uint16_t uid_offset)
  • error_t dev_persist_wait_write(struct device_persist_s *accessor, const struct dev_persist_descriptor_s *desc, uint16_t uid_offset, const void *data)
  • struct device_accessor_s * device_persist_s_base(struct device_persist_s *x)
  • struct device_persist_s * device_persist_s_cast(struct device_accessor_s *x)

Constants  

Macros  

Members detail  

#define DEV_PERSIST_INFO(n)  

This macro is declared in device/class/persist.h source file, line 237.

this macro retrieves statistics about persist device.

#define DEV_PERSIST_REQUEST(n)  

This macro is declared in device/class/persist.h source file, line 244.

this macro requests operations on a persist device.

#define DRIVER_PERSIST_METHODS(prefix)  

This macro is declared in device/class/persist.h source file, line 253.

#define __DEVICE_PERSIST_H__  

This macro is declared in device/class/persist.h source file, line 75.

struct dev_persist_descriptor_s  

This struct is declared in device/class/persist.h source file, line 129.

Value descriptor.

FieldDescription
uint16_t uid;Platform-wise identifier. rq->uid_offset is added to this id.
uint16_t type:1;Type
uint16_t state:3;Reseved bits.
uint16_t size:12;Byte size for blobs, size of integer part for counters.

struct dev_persist_info_s  

This struct is declared in device/class/persist.h source file, line 226.

this struct contains statistics about device's backing storage.

Sizes, used and total, may not actually equal the sum of all stored values. There may be some overhead in storage of each value.

FieldDescription
size_t storage_size;Total theorical size
size_t used_size;Total bytes used

const char dev_persist_op_e[]  

This variable is declared in ENUM_DESCRIPTOR function like macro expansion, line 1 in device/class/persist.h source file, line 141.

Alternate declarations with same identifier: [1], [2].

enum dev_persist_op_e  

This enum is declared in device/class/persist.h source file, line 147.

Request access types.

Alternate declarations with same identifier: [1], [2].

IdentifierDescription
DEV_PERSIST_ERASEErase all entries, start fresh with a blank storage. This does not check for previous storage contents.
DEV_PERSIST_PACKPack storage. Collect all erased entries.
DEV_PERSIST_READRead an entry. Caller will get data pointer set to start of value if present.
DEV_PERSIST_WRITEWrite an entry. Entry will be replaced if present already. This may pack existing storage.
DEV_PERSIST_REMOVERemove a given entry, if present.

struct dev_persist_rq_s  

This struct is declared in device/class/persist.h source file, line 181.

Persist class request.

FieldDescription
struct dev_request_s rq;
error_t err;Access return status
const struct dev_persist_descriptor_s * descriptor;Value descriptor
enum dev_persist_op_e op:3;Type of access
uint16_t uid_offset;UID offset to add to descriptor's base UID
union <anonymous> {
const void * data;
  • for blob write accesses, this holds buffer to copy to persist storage.
  • for blob read accesses, this will be set to an address that points to actual copy of data.
uint64_t counter;
  • for counter write accesses, this holds an offset to add to counter. Most write operations will take 1 here.
  • for counter read accesses, this will contain actual counter value upon successful operation.
};

struct dev_request_s * dev_persist_rq_s_base(struct dev_persist_rq_s *x)  

This function is declared in device/class/persist.h source file, line 233.

struct dev_persist_rq_s * dev_persist_rq_s_cast(struct dev_request_s *x)  

This function is declared in device/class/persist.h source file, line 233.

error_t dev_persist_spin_op(struct device_persist_s *accessor, struct dev_persist_rq_s *rq)  

This function is declared in device/class/persist.h source file, line 266.

Use of a busy-waiting function is bad programming practice. This function should be used for test purpose only.

This is available when CONFIG_DEVICE_PERSIST is defined.

const char dev_persist_type_e[]  

This variable is declared in ENUM_DESCRIPTOR function like macro expansion, line 1 in device/class/persist.h source file, line 103.

Alternate declarations with same identifier: [1], [2].

enum dev_persist_type_e  

This enum is declared in device/class/persist.h source file, line 109.

Value type

Alternate declarations with same identifier: [1], [2].

IdentifierDescription
DEV_PERSIST_BLOBA blob may hold any value. It is reallocated when written to.
DEV_PERSIST_COUNTERA counter can only be incremented or reset. It is stored in two fields in backing storage: a counter part, and a bitfield part. Single increments changes single bits in the bitfield part as long as there are some left. When all bytes got consumed, value is reallocated. This minimizes wear on backing storage.
Writes to counters actually increment counter with passed value.

error_t dev_persist_wait_counter_read(struct device_persist_s *accessor, const struct dev_persist_descriptor_s *desc, uint16_t uid_offset, uint64_t *value)  

This function is declared in device/class/persist.h source file, line 363.

This is available when CONFIG_DEVICE_PERSIST and CONFIG_MUTEK_CONTEXT_SCHED are both defined.

error_t dev_persist_wait_inc(struct device_persist_s *accessor, const struct dev_persist_descriptor_s *desc, uint16_t uid_offset)  

This function is declared in device/class/persist.h source file, line 346.

This is available when CONFIG_DEVICE_PERSIST and CONFIG_MUTEK_CONTEXT_SCHED are both defined.

error_t dev_persist_wait_op(struct device_persist_s *accessor, struct dev_persist_rq_s *rq)  

This function is declared in device/class/persist.h source file, line 281.

Synchronous persist device operation function. This function use the scheduler api to put current context in wait state during the request.

This is available when CONFIG_DEVICE_PERSIST and CONFIG_MUTEK_CONTEXT_SCHED are both defined.

error_t dev_persist_wait_read(struct device_persist_s *accessor, const struct dev_persist_descriptor_s *desc, uint16_t uid_offset, const void **data)  

This function is declared in device/class/persist.h source file, line 295.

This is available when CONFIG_DEVICE_PERSIST and CONFIG_MUTEK_CONTEXT_SCHED are both defined.

error_t dev_persist_wait_remove(struct device_persist_s *accessor, const struct dev_persist_descriptor_s *desc, uint16_t uid_offset)  

This function is declared in device/class/persist.h source file, line 331.

This is available when CONFIG_DEVICE_PERSIST and CONFIG_MUTEK_CONTEXT_SCHED are both defined.

error_t dev_persist_wait_write(struct device_persist_s *accessor, const struct dev_persist_descriptor_s *desc, uint16_t uid_offset, const void *data)  

This function is declared in device/class/persist.h source file, line 315.

This is available when CONFIG_DEVICE_PERSIST and CONFIG_MUTEK_CONTEXT_SCHED are both defined.

struct device_persist_s  

This struct is declared in DRIVER_CLASS_TYPES function like macro expansion, line 19 in device/class/persist.h source file, line 252.

This struct is the device accessor object type for the persist device class. This accessor must be initialized by calling the device_get_accessor function.

See also DRIVER_CLASS_PERSIST, struct device_accessor_s and Device accessor.

FieldDescription
union <anonymous> {
struct device_accessor_s base;
struct <anonymous> {
struct device_s * dev;
struct driver_persist_s * api;
uint_fast8_t number;
};
};

struct device_accessor_s * device_persist_s_base(struct device_persist_s *x)  

This function is declared in DRIVER_CLASS_TYPES function like macro expansion, line 40 in device/class/persist.h source file, line 252.

This function casts a persist device accessor to a generic device accessor

struct device_persist_s * device_persist_s_cast(struct device_accessor_s *x)  

This function is declared in DRIVER_CLASS_TYPES function like macro expansion, line 33 in device/class/persist.h source file, line 252.

This function casts a generic device accessor to a persist device accessor

typedef void (devpersist_info_t)(struct device_persist_s *accessor, struct dev_persist_info_s *info)   

This typedef is declared in device/class/persist.h source file, line 240.

This declaration involves expansion of the DEV_PERSIST_INFO macro.

typedef void (devpersist_request_t)(struct device_persist_s *accessor, struct dev_persist_rq_s *rq)   

This typedef is declared in device/class/persist.h source file, line 247.

This declaration involves expansion of the DEV_PERSIST_REQUEST macro.

struct driver_persist_s  

This struct is declared in DRIVER_CLASS_TYPES function like macro expansion, line 5 in device/class/persist.h source file, line 252.

This struct is the driver API descriptor for the persist device class.

See also DRIVER_CLASS_PERSIST and struct driver_class_s.

FieldDescription
uint16_t class_;
uint16_t ctx_offset;
devpersist_info_t * f_info;
devpersist_request_t * f_request;

enum dev_persist_state_e  

This enum is declared in device/class/persist.h source file, line 96.

This enum is for internal use only.

IdentifierDescription
DEV_PERSIST_STATE_ERASED
DEV_PERSIST_STATE_WRITTEN
DEV_PERSIST_STATE_BUSY
DEV_PERSIST_STATE_FREE

Valid XHTML 1.0 StrictGenerated by diaxen on Wed Feb 14 18:35:02 2018 using MkDoc