coreboot-kgpe-d16/util/cbfstool/fmd.h

144 lines
5.9 KiB
C

/*
* fmd.h, parser frontend and utility functions for flashmap descriptor language
*
* Copyright (C) 2015 Google, Inc.
*
* 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; version 2 of the License.
*
* 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., 51 Franklin St, Fifth Floor, Boston, MA, 02110-1301 USA
*/
#ifndef FMD_H_
#define FMD_H_
#include <limits.h>
#include <stdbool.h>
#include <stddef.h>
#include <stdio.h>
#define FMD_NOTFOUND UINT_MAX
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;
/** It is an error to dereference this array if list_len is 0. */
struct flashmap_descriptor **list;
};
/**
* **Client-defined** callback.
* This call is used to notify client code that the user has annotated the given
* section node by accompanying it with a string enclosed in parentheses. It is
* only invoked for nodes that have annotations, and then only once per node.
* The annotations' syntactic validity and semantic meaning are not determined
* by the compiler; rather, implementations of this function should use their
* return type to tell the compiler whether the annotation was valid syntax, as
* well as perform whatever actions are necessary given the particular
* annotation. 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 annotate the image as a whole. Note that, although the
* node received by this function will be preserved in memory as part of the
* ultimate flashmap_descriptor, the annotation string will only persist during
* this function call: if the implementation needs it longer, it must copy it.
*
* @param flashmap_descriptor The section node carrying the annotation
* @param annotation What the user wrote (only valid during callback)
* @return Whether this annotation represented valid syntax
*/
bool fmd_process_annotation_impl(const struct flashmap_descriptor *node,
const char *annotation);
/**
* 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