path: root/ubi-utils/src/bootenv.h

#ifndef __BOOTENV_H__
#define __BOOTENV_H__
/*
 * Copyright (c) International Business Machines Corp., 2006
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See
 * the GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 */

#include <stdio.h> /* FILE */
#include <stdint.h>
#include <pfiflash.h>

/* DOXYGEN DOCUMENTATION */

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @file bootenv.h
 * @author oliloh@de.ibm.com
 * @version 1.3
 *
 * 1.3 Some renaming
 */

/**
 * @mainpage Usage
 *
 * @section intro Introduction
 * This library provides all functionality to handle with the so-called
 * platform description data (PDD) and the bootparameters defined in
 * U-Boot. It is able to apply the defined PDD operations in PDD update
 * scenarios. For more information about the PDD and bootparameter
 * environment "bootenv" confer the PDD documentation.
 *
 * @section ret Return codes
 * This library defines some return codes which will be delivered classified
 * as warnings or errors. See the "Defines" section for details and numeric
 * values.
 *
 * @section benv Bootenv format description
 * There are two different input formats:
 *	- text files
 *	- binary files
 *
 * @subsection txt Text Files
 * Text files have to be specified like:
 * @verbatim key1=value1,value2,value7\n key2=value55,value1\n key4=value1\n@endverbatim
 *
 * @subsection bin Binary files
 * Binary files have to be specified like:
 * @verbatim<CRC32-bit>key1=value1,value2,value7\0key2=value55,value1\0... @endverbatim
 * You can confer the U-Boot documentation for more details.
 *
 * @section benvlists Bootenv lists format description.
 * Values referenced in the preceeding subsection can be
 * defined like lists:
 * @verbatim value1,value2,value3 @endverbatim
 * There are some situation where a conversion of a comma
 * seperated list can be useful, e.g. to get a list
 * of defined PDD entries.
 */

#define BOOTENV_MAXSIZE (1024 * 100) /* max 100kiB space for bootenv */

/**
 * @def BOOTENV_ECRC
 *	@brief Given binary file is to large.
 * @def BOOTENV_EFMT
 *	@brief Given bootenv section has an invalid format
 * @def BOOTENV_EBADENTRY
 *	@brief Bad entry in the bootenv section.
 * @def BOOTENV_EINVAL
 *	@brief Invalid bootenv defintion.
 * @def BOOTENV_ENOPDD
 *	@brief Given bootenv sectoin has no PDD defintion string (pdd=...).
 * @def BOOTENV_EPDDINVAL
 *	@brief Given bootenv section has an invalid PDD defintion.
 * @def BOOTENV_ENOTIMPL
 *	@brief Functionality not implemented.
 * @def BOOTENV_ECOPY
 *	@brief Bootenv memory copy error
 * @def BOOTENV_ENOTFOUND
 *	@brief Given key has has no value.
 * @def BOOTENV_EMAX
 *	@brief Highest error value.
 */
#define BOOTENV_ETOOBIG		1
#define BOOTENV_EFMT		2
#define BOOTENV_EBADENTRY	3
#define BOOTENV_EINVAL		4
#define BOOTENV_ENOPDD		5
#define BOOTENV_EPDDINVAL	6
#define BOOTENV_ENOTIMPL	7
#define BOOTENV_ECOPY		8
#define BOOTENV_ENOTFOUND	9
#define BOOTENV_EMAX		10

/**
 * @def BOOTENV_W
 *	@brief A warning which is handled internally as an error
 *	 but can be recovered by manual effort.
 * @def BOOTENV_WPDD_STRING_DIFFERS
 *	@brief The PDD strings of old and new PDD differ and
 *	can cause update problems, because new PDD values
 *	are removed from the bootenv section completely.
 */
#define BOOTENV_W		     20
#define BOOTENV_WPDD_STRING_DIFFERS  21
#define BOOTENV_WMAX 22 /* highest warning value */


typedef struct bootenv *bootenv_t;
	/**< A bootenv library handle. */

typedef struct bootenv_list *bootenv_list_t;
	/**< A handle for a value list. */

typedef int(*pdd_func_t)(bootenv_t, bootenv_t, bootenv_t*,
		int*, char*, size_t);


/**
 * @brief Get a new handle.
 * @return 0
 * @return or error
 * */
int bootenv_create(bootenv_t *env);

/**
 * @brief	Cleanup structure.
 * @param env	Bootenv structure which shall be destroyed.
 * @return 0
 * @return or error
 */
int bootenv_destroy(bootenv_t *env);

/**
 * @brief Copy a bootenv handle.
 * @param in	The input bootenv.
 * @param out	The copied output bootenv. Discards old data.
 * @return 0
 * @return or error
 */
int bootenv_copy_bootenv(bootenv_t in, bootenv_t *out);

/**
 * @brief Looks for a value inside the bootenv data.
 * @param env Handle to a bootenv structure.
 * @param key The key.
 * @return NULL	 key not found
 * @return !NULL ptr to value
 */
int bootenv_get(bootenv_t env, const char *key, const char **value);


/**
 * @brief Looks for a value inside the bootenv data and converts it to num.
 * @param env Handle to a bootenv structure.
 * @param key The key.
 * @param value A pointer to the resulting numerical value
 * @return NULL	 key not found
 * @return !NULL ptr to value
 */
int bootenv_get_num(bootenv_t env, const char *key, uint32_t *value);

/**
 * @brief Set a bootenv value by key.
 * @param env   Handle to a bootenv structure.
 * @param key	Key.
 * @param value	Value to set.
 * @return 0
 * @return or error
 */
int bootenv_set(bootenv_t env, const char *key, const char *value);

/**
 * @brief Remove the given key (and its value) from a bootenv structure.
 * @param env	Handle to a bootenv structure.
 * @param key	Key.
 * @return 0
 * @return or error
 */
int bootenv_unset(bootenv_t env, const char *key);


/**
 * @brief Get a vector of all keys which are currently set
 *        within a bootenv handle.
 * @param env	Handle to a bootenv structure.
 * @param size	The size of the allocated array structure.
 * @param sort	Flag, if set the vector is sorted ascending.
 * @return NULL on error.
 * @return !NULL a pointer to the first element the allocated vector.
 * @warning Free the allocate memory yourself!
 */
int bootenv_get_key_vector(bootenv_t env, size_t *size, int sort,
				const char ***vector);

/**
 * @brief Calculate the size in bytes which are necessary to write the
 *        current bootenv section in a *binary file.
 * @param env	bootenv handle.
 * @param size  The size in bytes of the bootenv handle.
 * @return 0
 * @return or ERROR.
 */
int bootenv_size(bootenv_t env, size_t *size);

/**
 * @brief Read a binary bootenv file.
 * @param fp	File pointer to input stream.
 * @param env	bootenv handle.
 * @param size  maximum data size.
 * @return 0
 * @return or ERROR.
 */
int bootenv_read(FILE* fp, bootenv_t env, size_t size);

/**
 * @param ret_crc  return value of crc of read data
 */
int bootenv_read_crc(FILE* fp, bootenv_t env, size_t size, uint32_t *ret_crc);

/**
 * @brief Read bootenv data from an text/ascii file.
 * @param fp	File pointer to ascii PDD file.
 * @param env	bootenv handle
 * @return 0
 * @return or ERROR.
 */
int bootenv_read_txt(FILE* fp, bootenv_t env);

/**
 * @brief Write a bootenv structure to the given location (binary).
 * @param fp	Filepointer to binary file.
 * @param env	Bootenv structure which shall be written.
 * @return 0
 * @return or error
 */
int bootenv_write(FILE* fp, bootenv_t env);

/**
 * @param ret_crc  return value of crc of read data
 */
int bootenv_write_crc(FILE* fp, bootenv_t env, uint32_t* ret_crc);

/**
 * @brief Write a bootenv structure to the given location (text).
 * @param fp	Filepointer to text file.
 * @param env	Bootenv structure which shall be written.
 * @return 0
 * @return or error
 */
int bootenv_write_txt(FILE* fp, bootenv_t env);

/**
 * @brief Compare bootenvs using memcmp().
 * @param first	First bootenv.
 * @param second	Second bootenv.
 * @return 0 if bootenvs are equal
 * @return < 0 if error
 * @return > 0 if unequal
 */
int bootenv_compare(bootenv_t first, bootenv_t second);

/**
 * @brief Prototype for a PDD handling funtion
 */

/**
 * @brief The PDD keep operation.
 * @param env_old The old bootenv structure.
 * @param env_new The new bootenv structure.
 * @param env_res The result of PDD keep.
 * @param warnings A flag which marks any warnings.
 * @return 0
 * @return or error
 * @note For a complete documentation about the algorithm confer the
 *       PDD documentation.
 */
int bootenv_pdd_keep(bootenv_t env_old, bootenv_t env_new,
		bootenv_t *env_res, int *warnings,
		char *err_buf, size_t err_buf_size);


/**
 * @brief The PDD merge operation.
 * @param env_old The old bootenv structure.
 * @param env_new The new bootenv structure.
 * @param env_res The result of merge-pdd.
 * @param warnings A flag which marks any warnings.
 * @return 0
 * @return or error
 * @note For a complete documentation about the algorithm confer the
 *       PDD documentation.
 */
int bootenv_pdd_merge(bootenv_t env_old, bootenv_t env_new,
		bootenv_t *env_res, int *warnings,
		char *err_buf, size_t err_buf_size);

/**
 * @brief The PDD overwrite operation.
 * @param env_old The old bootenv structure.
 * @param env_new The new bootenv structure.
 * @param env_res The result of overwrite-pdd.
 * @param warnings A flag which marks any warnings.
 * @return 0
 * @return or error
 * @note For a complete documentation about the algorithm confer the
 *       PDD documentation.
 */
int bootenv_pdd_overwrite(bootenv_t env_new,
		bootenv_t env_old, bootenv_t *env_res, int *warnings,
		char *err_buf, size_t err_buf_size);

/**
 * @brief Dump a bootenv structure to stdout. (Debug)
 * @param env	Handle to a bootenv structure.
 * @return 0
 * @return or error
 */
int bootenv_dump(bootenv_t env);

/**
 * @brief Validate a bootenv structure.
 * @param env Handle to a bootenv structure.
 * @return 0
 * @return or error
 */
int bootenv_valid(bootenv_t env);

/**
 * @brief Create a new bootenv list structure.
 * @return NULL on error
 * @return or a new list handle.
 * @note This structure is used to store values in a list.
 *       A useful addition when handling PDD strings.
 */
int bootenv_list_create(bootenv_list_t *list);

/**
 * @brief Destroy a bootenv list structure
 * @param list	Handle to a bootenv list structure.
 * @return 0
 * @return or error
 */
int bootenv_list_destroy(bootenv_list_t *list);

/**
 * @brief Import a list from a comma seperated string
 * @param list	Handle to a bootenv list structure.
 * @param str		Comma seperated string list.
 * @return 0
 * @return or error
 */
int bootenv_list_import(bootenv_list_t list, const char *str);

/**
 * @brief Export a list to a string of comma seperated values.
 * @param list	Handle to a bootenv list structure.
 * @return NULL one error
 * @return or pointer to a newly allocated string.
 * @warning Free the allocated memory by yourself!
 */
int bootenv_list_export(bootenv_list_t list, char **string);

/**
 * @brief Add an item to the list.
 * @param list	A handle of a list structure.
 * @param item	An item.
 * @return 0
 * @return or error
 */
int bootenv_list_add(bootenv_list_t list, const char *item);

/**
 * @brief Remove an item from the list.
 * @param list	A handle of a list structure.
 * @param item	An item.
 * @return 0
 * @return or error
 */
int bootenv_list_remove(bootenv_list_t list, const char *item);

/**
 * @brief Check if a given item is in a given list.
 * @param list	A handle of a list structure.
 * @param item	An item.
 * @return 1 Item is in list.
 * @return 0 Item is not in list.
 */
int bootenv_list_is_in(bootenv_list_t list, const char *item);


/**
 * @brief Convert a list into a vector of all values inside the list.
 * @param list	Handle to a bootenv structure.
 * @param size	The size of the allocated vector structure.
 * @return 0
 * @return or error
 * @warning Free the allocate memory yourself!
 */
int bootenv_list_to_vector(bootenv_list_t list, size_t *size,
			   const char ***vector);

/**
 * @brief Convert a list into a vector of all values inside the list.
 * @param list	Handle to a bootenv structure.
 * @param size	The size of the allocated vector structure.
 * @return 0
 * @return or error
 * @warning Free the allocate memory yourself!
 */
int bootenv_list_to_num_vector(bootenv_list_t list, size_t *size,
					uint32_t **vector);

#ifdef __cplusplus
}
#endif
#endif /*__BOOTENV_H__ */