/* parser frontend and utility functions for flashmap descriptor language */
/* SPDX-License-Identifier: GPL-2.0-only */

#ifndef FMD_H_
#define FMD_H_

#include <limits.h>
#include <stdbool.h>
#include <stddef.h>
#include <stdio.h>

#define FMD_NOTFOUND UINT_MAX

/**
 * Flags used by flashmap_descriptor.
 * These flags can be set by adding (NAME) after description name.
 * For example, declaring a CBFS section named as COREBOOT for 16k:
 *   COREBOOT(CBFS) 16k
 */
union flashmap_flags {
	struct {
		unsigned int cbfs: 1;  /* The section contains a CBFS area. */
		unsigned int preserve: 1;  /* Preserve the section before update. */
	} f;
	int v;
};

struct flashmap_descriptor {
	char *name;
	bool offset_known;
	/**
	 * Offset relative to that of the parent node.
	 * Exception: for the root node in the descriptor tree, it is optional.
	 * In this case, if absent, it indicates that the flash chip will not be
	 * memory mapped at runtime; otherwise, its value indicates the base
	 * address of the flash chip in the virtual address space rather than
	 * representing an offset into the flash image itself.
	 * It is an error to read this field unless offset_known is set.
	 */
	unsigned offset;
	bool size_known;
	/** It is an error to read this field unless size_known is set. */
	unsigned size;
	size_t list_len;
	union flashmap_flags flags;
	/** It is an error to dereference this array if list_len is 0. */
	struct flashmap_descriptor **list;
};

/**
 * **Client-defined** callback for flag "CBFS".
 * This call is used to notify client code that the user has requested the given
 * section node to be flagged with "CBFS". Implementations of this function
 * should use their return type to tell the compiler whether the flag can be
 * applied and can perform whatever actions are necessary.
 * It's worth reiterating that this is only called on section nodes, and will
 * never be called with the final, complete flashmap_descriptor because
 * it is impossible to set flags for the image as a whole.
 *
 * @param flashmap_descriptor The section node with flag set
 * @return                    Whether this flag can be applied
 */
bool fmd_process_flag_cbfs(const struct flashmap_descriptor *node);

/**
 * Parse and validate a flashmap descriptor from the specified stream.
 * As part of this process, any fields that were omitted in the input are
 * inferred from whatever information is known, if possible. The result is a
 * tree with all its offset and size fields filled, except possibly the former
 * part of the root node in the case of non--memory mapped flash. If a syntax
 * error causes the parser to fail, or if there is not enough information given
 * in the input file to determine any single missing value, the specific error
 * is reported to standard error and this function returns NULL.
 *
 * @param stream File from which to read the (partial) flashmap descriptor
 * @return       Populated flashmap descriptor tree, or NULL on failure
 */
struct flashmap_descriptor *fmd_create(FILE *stream);

/** @param victim Valid descriptor tree to be cleaned up, or NULL for no-op */
void fmd_cleanup(struct flashmap_descriptor *victim);

/**
 * @param tree Must be non-NULL
 * @return     The number of nodes in the tree, including the root
 */
size_t fmd_count_nodes(const struct flashmap_descriptor *tree);

/**
 * @param root The flashmap descriptor to search
 * @param name The name of the sought-after section
 * @return     The desired section node, or NULL if none was found
 */
const struct flashmap_descriptor *fmd_find_node(
		const struct flashmap_descriptor *root, const char *name);

/**
 * @param root Parent node to whose start the "absolute" offset will be relative
 * @param name The name of the node whose offset to determine
 * @return     The "absolute" offset, or FMD_NOTFOUND if the node wasn't found
 */
unsigned fmd_calc_absolute_offset(const struct flashmap_descriptor *root,
							const char *name);

/** @param tree Must be non-NULL */
void fmd_print(const struct flashmap_descriptor *tree);

typedef struct flashmap_descriptor **flashmap_descriptor_iterator_t;

/*
 * Run the subsequent statement once on each descendant of the specified node.
 *
 * @param iterator A flashmap_descriptor_iterator_t (automatically declared)
 * @param parent   The parent node of those over which the loop should iterate
 */
#define fmd_foreach_child_iterator(iterator, parent) \
	for (flashmap_descriptor_iterator_t iterator = parent->list; \
		iterator < parent->list + parent->list_len; ++iterator)

/*
 * Run the subsequent statement once on each descendant of the specified node.
 *
 * @param child  A struct flashmap_descriptor * (automatically declared)
 * @param parent The parent node of those over which the loop should iterate
 */
#define fmd_foreach_child(child, parent) \
	for (struct flashmap_descriptor **fmd_foreach_child_iterator_ = \
						parent->list, *child = NULL; \
						fmd_foreach_child_iterator_ < \
					parent->list + parent->list_len && \
				(child = *fmd_foreach_child_iterator_); \
						++fmd_foreach_child_iterator_)

#endif