From 69b88bf1276d2cb0309e2fc96df9d33a893138e3 Mon Sep 17 00:00:00 2001 From: Sol Boucher Date: Thu, 26 Feb 2015 11:47:19 -0800 Subject: fmaptool: Introduce the fmd ("flashmap descriptor") language and compiler This adds a compiler for a language whose textual representation of flashmap regions will be used to describe the layout of flash chips that contain more than just a single CBFS. Direct integration with cbfstool (via a new command-line switch for the create action) is forthcoming but will be added separately. BUG=chromium:461875 TEST=Use Chromium OS's cros_bundle_firmware script on the fmap.dts file for panther. Using the latter file as a reference, write a corresponding fmap.fmd file and feed it through fmaptool. Run both binary output files though the flashmap project's own flashmap_decode utility. Observe only the expected differences. BRANCH=None Change-Id: I06b32d138dbef0a4e5ed43c81bd31c796fd5d669 Signed-off-by: Sol Boucher Original-Commit-Id: 005ab67eb594e21489cf31036aedaea87e0c7142 Original-Change-Id: Ia08f28688efdbbfc70c255916b8eb7eb0eb07fb2 Original-Signed-off-by: Sol Boucher Original-Reviewed-on: https://chromium-review.googlesource.com/255031 Original-Reviewed-by: Julius Werner Original-Reviewed-by: Stefan Reinauer Reviewed-on: http://review.coreboot.org/9942 Tested-by: build bot (Jenkins) Reviewed-by: Patrick Georgi --- util/cbfstool/fmd.h | 143 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 143 insertions(+) create mode 100644 util/cbfstool/fmd.h (limited to 'util/cbfstool/fmd.h') diff --git a/util/cbfstool/fmd.h b/util/cbfstool/fmd.h new file mode 100644 index 0000000000..ff54cbfb4a --- /dev/null +++ b/util/cbfstool/fmd.h @@ -0,0 +1,143 @@ +/* + * 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 +#include +#include +#include + +#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 -- cgit v1.2.3