persist/persist.h header reference
[Persistent configuration service module]

The source code of this header can be browsed online.

Description  

Persistent configuration library

Members  

Types  

Functions  

  • ENUM_DESCRIPTOR(persist_type_e , strip:PERSIST_, upper )
  • void persist_context_init(struct persist_context_s *ctx, uintptr_t dev_addr, size_t dev_size, size_t page_size)
  • void persist_erase(struct persist_context_s *ctx, struct persist_rq_s *rq)
  • void persist_pack(struct persist_context_s *ctx, struct persist_rq_s *rq)
  • void persist_read(struct persist_context_s *ctx, struct persist_rq_s *rq)
  • void persist_remove(struct persist_context_s *ctx, struct persist_rq_s *rq)
  • error_t persist_wait_counter_read(struct persist_context_s *ctx, const struct persist_descriptor_s *desc, uint16_t uid_offset, uint64_t *value)
  • error_t persist_wait_erase(struct persist_context_s *ctx)
  • error_t persist_wait_inc(struct persist_context_s *ctx, const struct persist_descriptor_s *desc, uint16_t uid_offset)
  • error_t persist_wait_pack(struct persist_context_s *ctx)
  • error_t persist_wait_read(struct persist_context_s *ctx, const struct persist_descriptor_s *desc, uint16_t uid_offset, const void **data)
  • error_t persist_wait_remove(struct persist_context_s *ctx, const struct persist_descriptor_s *desc, uint16_t uid_offset)
  • error_t persist_wait_write(struct persist_context_s *ctx, const struct persist_descriptor_s *desc, uint16_t uid_offset, const void *data)
  • void persist_write(struct persist_context_s *ctx, struct persist_rq_s *rq)
  • void persist_sched_init(struct persist_rq_s *rq, struct persist_status_s *status)
  • void persist_sched_wait(struct persist_status_s *status)

Macro  

Members detail  

ENUM_DESCRIPTOR(persist_type_e , strip:PERSIST_, upper )  

#define CONFIG_PERSIST_RAM_BACKEND_PAGESIZE  

This macro is declared in persist/persist.h source file, line 42.

Documentation from alternate declaration:

Token description: Set page size for the compiled test, default is 0x1000

This token is declared in libpersist/persist.config, line 13.

This token depends on:

Preprocessor condition: defined( CONFIG_PERSIST_RAM_BACKEND ) and not defined( CONFIG_PERSIST_RAM_BACKEND_PAGESIZE )

#define PERSIST_FLASH_ERASE_VALUE  

This macro is declared in persist/persist.h source file, line 40.

backend choice

Preprocessor condition: defined( CONFIG_PERSIST_RAM_BACKEND )

#define __PERSIST_H__  

This macro is declared in persist/persist.h source file, line 28.

struct persist_config  

This struct is declared in persist/persist.h source file, line 60.

Persist config

FieldDescription
uintptr_t dev_addr;
size_t dev_size;
size_t page_size;

void persist_context_init(struct persist_context_s *ctx, uintptr_t dev_addr, size_t dev_size, size_t page_size)  

Initialize a context for access to a persistent storage in a memory area.

struct persist_context_s  

This struct is declared in persist/persist.h source file, line 68.

Persistent storage context

FieldDescription
uintptr_t addr;
size_t page_size;
size_t slot_size;
uint8_t current_slot;
size_t used;
size_t reclaimable;
size_t available;

struct persist_descriptor_s  

This struct is declared in persist/persist.h source file, line 101.

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.

void persist_erase(struct persist_context_s *ctx, struct persist_rq_s *rq)  

Erase all entries, start fresh with a blank storage. This does not check for previous storage contents.

This is available when CONFIG_PERSIST is defined.

void persist_pack(struct persist_context_s *ctx, struct persist_rq_s *rq)  

Pack storage. Collect all erased entries.

This is available when CONFIG_PERSIST is defined.

void persist_read(struct persist_context_s *ctx, struct persist_rq_s *rq)  

Read an entry. Caller will get data pointer set to start of value if present.

This is available when CONFIG_PERSIST is defined.

void persist_remove(struct persist_context_s *ctx, struct persist_rq_s *rq)  

Remove a given entry, if present.

This is available when CONFIG_PERSIST is defined.

struct persist_rq_s  

This struct is declared in persist/persist.h source file, line 115.

Persist request object.

FieldDescription
struct kroutine_s kr;Executed when request done
void * pvdata;Reserved for application
const struct persist_descriptor_s * descriptor;Value descriptor
uint16_t uid_offset;UID offset to add to descriptor's base UID
error_t error;Access return status
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.
};

enum persist_type_e  

This enum is declared in persist/persist.h source file, line 84.

Value type

IdentifierDescription
PERSIST_BLOBA blob may hold any value. It is reallocated when written to.
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 persist_wait_counter_read(struct persist_context_s *ctx, const struct persist_descriptor_s *desc, uint16_t uid_offset, uint64_t *value)  

This function is declared in persist/persist.h source file, line 361.

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_PERSIST and CONFIG_MUTEK_CONTEXT_SCHED are both defined.

error_t persist_wait_erase(struct persist_context_s *ctx)  

This function is declared in persist/persist.h source file, line 313.

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_PERSIST and CONFIG_MUTEK_CONTEXT_SCHED are both defined.

error_t persist_wait_inc(struct persist_context_s *ctx, const struct persist_descriptor_s *desc, uint16_t uid_offset)  

This function is declared in persist/persist.h source file, line 336.

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_PERSIST and CONFIG_MUTEK_CONTEXT_SCHED are both defined.

error_t persist_wait_pack(struct persist_context_s *ctx)  

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

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_PERSIST and CONFIG_MUTEK_CONTEXT_SCHED are both defined.

error_t persist_wait_read(struct persist_context_s *ctx, const struct persist_descriptor_s *desc, uint16_t uid_offset, const void **data)  

This function is declared in persist/persist.h source file, line 231.

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_PERSIST and CONFIG_MUTEK_CONTEXT_SCHED are both defined.

error_t persist_wait_remove(struct persist_context_s *ctx, const struct persist_descriptor_s *desc, uint16_t uid_offset)  

This function is declared in persist/persist.h source file, line 277.

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_PERSIST and CONFIG_MUTEK_CONTEXT_SCHED are both defined.

error_t persist_wait_write(struct persist_context_s *ctx, const struct persist_descriptor_s *desc, uint16_t uid_offset, const void *data)  

This function is declared in persist/persist.h source file, line 255.

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_PERSIST and CONFIG_MUTEK_CONTEXT_SCHED are both defined.

void persist_write(struct persist_context_s *ctx, struct persist_rq_s *rq)  

Write an entry. Entry will be replaced if present already. This may pack existing storage.

This is available when CONFIG_PERSIST is defined.

void persist_sched_init(struct persist_rq_s *rq, struct persist_status_s *status)  

This function is for internal use only.

void persist_sched_wait(struct persist_status_s *status)  

This function is for internal use only.

enum persist_state_e  

This enum is declared in persist/persist.h source file, line 49.

This enum is for internal use only.

IdentifierDescription
PERSIST_STATE_ERASED
PERSIST_STATE_WRITTEN
PERSIST_STATE_BUSY
PERSIST_STATE_FREE

struct persist_status_s  

This struct is declared in persist/persist.h source file, line 194.

This struct is for internal use only.

Preprocessor condition: defined( CONFIG_MUTEK_CONTEXT_SCHED )

FieldDescription
lock_t lock;
struct sched_context_s * ctx;
bool_t done;

Valid XHTML 1.0 StrictGenerated by diaxen on Wed Oct 17 21:18:39 2018 using MkDoc