meshx_kv_engine.h File Reference

Portable Key-Value Engine for MeshX. More...

#include "meshx_err.h"
#include "interface/utils/meshx_fal_interface.h"
#include <stdint.h>
#include <stdbool.h>

Go to the source code of this file.

Functions
meshx_err_t	meshx_kv_engine_init (const meshx_fal_partition_t *part)
	Initialize the KV engine.
meshx_err_t	meshx_kv_engine_read (const char *key, void *buf, uint16_t len)
	Read a value from the KV engine.
meshx_err_t	meshx_kv_engine_set (const char *key, const void *buf, uint16_t len)
	Buffer a write operation in RAM.
meshx_err_t	meshx_kv_engine_commit (void)
	Commit all buffered changes to flash.
meshx_err_t	meshx_kv_engine_remove (const char *key)
	Remove a key from the KV engine.
meshx_err_t	meshx_kv_engine_erase_all (void)
	Erase the entire KV partition.

Detailed Description

Portable Key-Value Engine for MeshX.

Copyright © 2024 - 2025 MeshX

This engine provides a lightweight KV store with built-in wear-leveling and power-fail safety, designed to run on top of the FAL interface.

Author

Pranjal Chanda

Function Documentation

meshx_kv_engine_commit()

meshx_err_t meshx_kv_engine_commit

(

void

)

Commit all buffered changes to flash.

Returns

meshx_err_t MESHX_SUCCESS on success, or error code.

< "MX"

< "MX"

{
    kv_pending_t *cur = pending_list;
    while (cur) {
        kv_header_t header = {
            .magic = KV_MAGIC,
            .status = KV_STATUS_VALID,
            .key_len = (uint8_t)strlen(cur->key),
            .val_len = cur->len,
            .seq_id = kv_next_seq_id++,
            .crc = kv_calc_crc(cur->data, cur->len)
        };
 
        uint32_t size = kv_align(sizeof(header) + header.key_len + header.val_len);
        if (kv_write_pos + size > kv_part->size) {
            meshx_err_t err = kv_engine_gc();
            if (err != MESHX_SUCCESS) return err;
        }
 
        meshx_fal_write(kv_part, kv_write_pos, &header, sizeof(header));
        meshx_fal_write(kv_part, kv_write_pos + sizeof(header), cur->key, header.key_len);
        meshx_fal_write(kv_part, kv_write_pos + sizeof(header) + header.key_len, cur->data, header.val_len);
 
        // Verification
        kv_header_t v_header;
        meshx_fal_read(kv_part, kv_write_pos, &v_header, sizeof(v_header));
        if (v_header.magic != KV_MAGIC) {
            MESHX_LOGE(MODULE_ID_COMPONENT_MESHX_NVS, "KV Verify FAILED at pos %u! (read: 0x%04x)", kv_write_pos, v_header.magic);
        }
 
        MESHX_LOGD(MODULE_ID_COMPONENT_MESHX_NVS, "KV Commit: key=%s, seq=%u, pos=%u", cur->key, header.seq_id, kv_write_pos);
        kv_write_pos += size;
 
        kv_pending_t *prev = cur;
        cur = cur->next;
        free(prev->data);
        free(prev);
    }
    pending_list = NULL;
    return MESHX_SUCCESS;
}

meshx_kv_engine_erase_all()

meshx_err_t meshx_kv_engine_erase_all

(

void

)

Erase the entire KV partition.

Returns

meshx_err_t MESHX_SUCCESS on success, or error code.

{
    meshx_err_t err = meshx_fal_erase(kv_part, 0, kv_part->size);
    if (err == MESHX_SUCCESS) {
        kv_write_pos = 0;
        kv_next_seq_id = 1;
    }
    return err;
}

meshx_kv_engine_init()

meshx_err_t meshx_kv_engine_init

(

const meshx_fal_partition_t *

part

)

Initialize the KV engine.

Parameters

[in]

part

Pointer to the flash partition to use.

Returns

meshx_err_t MESHX_SUCCESS on success, or error code.

< "MX"

{
    if (!part) return MESHX_INVALID_ARG;
    kv_part = part;
    kv_write_pos = 0;
    kv_next_seq_id = 1;
 
    // Scan to find write head and max seq_id
    kv_header_t header;
    while (kv_write_pos + sizeof(header) <= kv_part->size) {
        meshx_err_t err = meshx_fal_read(kv_part, kv_write_pos, &header, sizeof(header));
        if (err) return err;
 
        if (header.magic != KV_MAGIC || header.status == KV_STATUS_EMPTY) {
            break;
        }
 
        if (header.key_len > KV_MAX_KEY_LEN || header.val_len > 256) {
            MESHX_LOGE(MODULE_ID_COMPONENT_MESHX_NVS, "KV Init: Invalid lengths at pos %u (key:%d, val:%d)", kv_write_pos, header.key_len, header.val_len);
            break;
        }
 
        if (header.seq_id >= kv_next_seq_id) {
            kv_next_seq_id = header.seq_id + 1;
        }
 
        char kbuf[KV_MAX_KEY_LEN];
        meshx_fal_read(kv_part, kv_write_pos + sizeof(header), kbuf, header.key_len < KV_MAX_KEY_LEN ? header.key_len : KV_MAX_KEY_LEN-1);
        kbuf[header.key_len < KV_MAX_KEY_LEN ? header.key_len : KV_MAX_KEY_LEN-1] = '\0';
#ifdef KV_DEBUG_EN
        MESHX_LOGD(MODULE_ID_COMPONENT_MESHX_NVS, "  Found Record: key=%s, seq=%u, pos=%u", kbuf, header.seq_id, kv_write_pos);
#endif /* KV_DEBUG_EN */
        kv_write_pos += kv_align(sizeof(header) + header.key_len + header.val_len);
    }
 
    MESHX_LOGD(MODULE_ID_COMPONENT_MESHX_NVS, "KV Engine Init: Pos=%u, SeqID=%u", kv_write_pos, kv_next_seq_id);
    return MESHX_SUCCESS;
}

meshx_kv_engine_read()

meshx_err_t meshx_kv_engine_read	(	const char *	key,
		void *	buf,
		uint16_t	len )

Read a value from the KV engine.

Parameters

[in]	key	Key name.
[out]	buf	Buffer to store read data.
[in]	len	Length of the data to read.

Returns

meshx_err_t MESHX_SUCCESS on success, or error code.

< "MX"

{
    if (!kv_part || !key || !buf) return MESHX_INVALID_ARG;
 
    // Check pending writes first (most recent)
    kv_pending_t *pending = pending_list;
    while (pending) {
        if (strncmp(pending->key, key, KV_MAX_KEY_LEN - 1) == 0) {
            uint16_t to_copy = (len < pending->len) ? len : pending->len;
            memcpy(buf, pending->data, to_copy);
            return MESHX_SUCCESS;
        }
        pending = pending->next;
    }
 
    uint32_t pos = 0;
    kv_header_t header;
    uint32_t best_pos = 0xFFFFFFFF;
    uint32_t max_seq = 0;
    uint16_t found_val_len = 0;
 
    while (pos < kv_write_pos) {
        if (meshx_fal_read(kv_part, pos, &header, sizeof(header)) != MESHX_SUCCESS) break;
        if (header.magic != KV_MAGIC) break;
 
        if (header.status == KV_STATUS_VALID && header.key_len == strlen(key)) {
            char found_key[KV_MAX_KEY_LEN];
            meshx_fal_read(kv_part, pos + sizeof(header), found_key, header.key_len);
            if (strncmp(found_key, key, header.key_len) == 0) {
                if (header.seq_id >= max_seq) {
                    max_seq = header.seq_id;
                    best_pos = pos;
                    found_val_len = header.val_len;
                }
            }
        }
        pos += kv_align(sizeof(header) + header.key_len + header.val_len);
    }
 
    if (best_pos != 0xFFFFFFFF) {
        uint16_t to_read = (len < found_val_len) ? len : found_val_len;
        kv_header_t h;
        meshx_fal_read(kv_part, best_pos, &h, sizeof(h));
        meshx_fal_read(kv_part, best_pos + sizeof(h) + h.key_len, buf, to_read);
        MESHX_LOGD(MODULE_ID_COMPONENT_MESHX_NVS, "KV Read Success: key=%s, seq=%u, len=%d", key, max_seq, to_read);
        return MESHX_SUCCESS;
    }
 
    MESHX_LOGD(MODULE_ID_COMPONENT_MESHX_NVS, "KV Read Not Found: key=%s", key);
    return MESHX_NOT_FOUND;
}

meshx_kv_engine_remove()

meshx_err_t meshx_kv_engine_remove

(

const char *

key

)

Remove a key from the KV engine.

Parameters

[in]

key

Key name.

Returns

meshx_err_t MESHX_SUCCESS on success, or error code.

{
    // Removing in log-structured means appending a "Deleted" record or marking status
    // Here we append a record with status OBSOLETE or just set length to 0
    uint8_t dummy = 0;
    return meshx_kv_engine_set(key, &dummy, 0);
    // The next read will find this (seq_id will be higher) and we can treat len=0 as deleted
}

meshx_kv_engine_set()

meshx_err_t meshx_kv_engine_set	(	const char *	key,
		const void *	buf,
		uint16_t	len )

Buffer a write operation in RAM.

Parameters

[in]	key	Key name.
[in]	buf	Buffer containing data to write.
[in]	len	Length of the data.

Returns

meshx_err_t MESHX_SUCCESS on success, or error code.

{
    kv_pending_t *node = malloc(sizeof(kv_pending_t));
    if (!node) return MESHX_NO_MEM;
    strncpy(node->key, key, KV_MAX_KEY_LEN - 1);
    node->data = malloc(len);
    memcpy(node->data, buf, len);
    node->len = len;
    node->next = pending_list;
    pending_list = node;
    return MESHX_SUCCESS;
}