include/kvstore.h

/*
 * Copyright (c) 2018 The Fuchsia Authors
 *
 * SPDX-License-Identifier:	BSD-3-Clause
 */

#ifndef _KVSTORE_H_
#define _KVSTORE_H_

#include <common.h>
#include <stdlib.h>

typedef struct kvstore kvstore_t;

#define KVS_OK                0
#define KVS_ERR_INTERNAL     -1
#define KVS_ERR_BAD_PARAM    -2
#define KVS_ERR_OUT_OF_SPACE -3
#define KVS_ERR_NOT_FOUND    -4
#define KVS_ERR_PARSE_HDR    -5
#define KVS_ERR_PARSE_REC    -6
#define KVS_ERR_PARSE_CRC    -7

// KVStore API
// -----------

// Setup a new, empty kvstore, backed by buffer.
void kvs_init(kvstore_t* kvs, void* buffer, size_t buflen);

// Initialize a kvstore (read from disk, etc), backed by buffer.
int kvs_load(kvstore_t* kvs, void* buffer, size_t buflen);

// Prepare kvstore for saving (compute checksum & update header).
// On success kvs->data and kvs->datalen represents the data
// to write to storage.
int kvs_save(kvstore_t* kvs);


// Adds a new key and value, provided there is space.
// Does not check for duplicates.
int kvs_addn(kvstore_t* kvs, const void* key, size_t klen,
             const void* val, size_t vlen);

// Adds a new key and value, provided there is space.
// Does not check for duplicates.
int kvs_add(kvstore_t* kvs, const char* key, const char* value);


// Locates key and returns its value and OK, else NOT_FOUND
// returned pointer is not guaranteed stable if kvstore is mutated.
int kvs_getn(kvstore_t* kvs, const void* key, size_t klen,
             const void** val, size_t* vlen);

// Locates key and returns its value if found, otherwise returns fallback
// returned pointer is not guaranteed stable if kvstore is mutated.
const char* kvs_get(kvstore_t* kvs, const char* key, const char* fallback);


// Calls func() for each key/value pair.
// Return KVS_OK at the end, or stops and returns whatever func()
// returned. if func returns non-zero.
int kvs_foreach(kvstore_t* kvs, void *cookie,
                int (*func)(void *cookie, const char* key, const char* val));


// KVStore Wire Format and Internals
// ---------------------------------

// <header> <kventry>* [ <signature> ]
//
// <header> := <u64:version> <u32:flags> <u32:length> <u32:crc32> <u32:reserved>
// <kventry> := <u8:klen> <u8:vlen> <u8[klen]:key> <u8:0> <u8[vlen]:value> <u8:0>
// <signature> := TBD

// echo -n "kvstore-version-1" | sha256sum (LSB)
#define KVSTORE_VERSION 0x540f19caa7bf19dcUL

#define KVSTORE_FLAG_SIGNED 1

struct kvstore {
    void* data;
    size_t datalen;
    size_t datamax;
    size_t kvcount;
};

typedef struct kvshdr {
    uint64_t version;
    uint32_t flags;
    uint32_t length;
    uint32_t reserved;
    uint32_t crc;
} kvshdr_t;

#endif /* _KVSTORE_H_ */