/* Copyright 2016 The Chromium OS Authors. All rights reserved.
 * Use of this source code is governed by a BSD-style license that can be
 * found in the LICENSE file.
 */

#ifndef __EC_INCLUDE_NVMEM_VARS_H
#define __EC_INCLUDE_NVMEM_VARS_H

/*
 * CONFIG_FLASH_NVMEM provides persistent, atomic-update storage in
 * flash. The storage is logically divided into one or more "user regions", as
 * configured in board.h and board.c
 *
 * CONFIG_FLASH_NVMEM_VARS stores a set of <KEY, VALUE> tuples in the nvmem
 * user region designated by CONFIG_FLASH_NVMEM_VARS_USER_NUM (in board.h)
 *
 * Tuples are stored and managed using this struct:
 */

struct tuple {
	uint8_t key_len;			/* 1 - 255 */
	uint8_t val_len;			/* 1 - 255 */
	uint8_t flags;				/* RESERVED, will be zeroed */
	uint8_t data_[0];			/* Opaque. Don't look here. */
};

/*
 * Both KEY and VALUE can be any binary blob between 1 and 255 bytes (flash
 * memory is limited, so if you need longer values just use two keys and
 * concatenate the blobs). Zero-length KEYs or VALUEs are not allowed.
 * Assigning a zero-length VALUE to a KEY just deletes that tuple (if it
 * existed).
 *
 * The expected usage is:
 *
 * 1. At boot, call initvars() to ensure that the variable storage region is
 *    valid. If it isn't, this will initialize it to an empty set.
 *
 * 2. Call getenv() or setenv() as needed. The first call to either will copy
 *    the storage regsion from flash into a RAM buffer. Any changes made with
 *    setenv() will affect only that RAM buffer.
 *
 * 3. Call writevars() to commit the RAM buffer to flash and free it.
 *
 * CAUTION: The underlying CONFIG_FLASH_NVMEM implementation allows access by
 * multiple tasks, provided each task access only one user region. There is no
 * support for simultaneous access to the *same* user region by multiple tasks.
 * CONFIG_FLASH_NVMEM_VARS stores all variables in one user region, so if
 * variable access by multiple tasks is required, the tasks should establish
 * their own locks or mutexes to fit their usage. In general that would mean
 * aquiring a lock before calling getvar() or setvar(), and releasing it after
 * calling writevars().
 */

/*
 * Initialize the persistent storage. This checks the user region to ensure
 * that all tuples are valid and that there is one additional '\0' at the end.
 * If any discrepancies are found, it erases all values. This should return
 * EC_SUCCESS unless there is a problem writing to flash.
 */
int initvars(void);

/*
 * Look up a key, return a pointer to the tuple. If the key is not found,
 * return NULL. WARNING: The returned pointer is only valid until the next call
 * to setvar() or writevars(). Use it or lose it.
 */
const struct tuple *getvar(const uint8_t *key, uint8_t key_len);

/* Use these to access the data components of a valid struct tuple pointer */
const uint8_t *tuple_key(const struct tuple *);
const uint8_t *tuple_val(const struct tuple *);

/*
 * Save the tuple in the RAM buffer. If val is NULL or val_len is 0, the
 * tuple is deleted (if it existed). Returns EC_SUCCESS or error code.
 */
int setvar(const uint8_t *key, uint8_t key_len,
	   const uint8_t *val, uint8_t val_len);

/*
 * Commit any changes made with setvar() to persistent memory, and invalidate
 * the RAM buffer. Return EC_SUCCESS or error code on failure.
 */
int writevars(void);

#endif	/* __EC_INCLUDE_NVMEM_VARS_H */