Sol Boucher | 69b88bf | 2015-02-26 11:47:19 -0800 | [diff] [blame] | 1 | /* |
| 2 | * fmd.h, parser frontend and utility functions for flashmap descriptor language |
| 3 | * |
| 4 | * Copyright (C) 2015 Google, Inc. |
| 5 | * |
| 6 | * This program is free software; you can redistribute it and/or modify |
| 7 | * it under the terms of the GNU General Public License as published by |
| 8 | * the Free Software Foundation; version 2 of the License. |
| 9 | * |
| 10 | * This program is distributed in the hope that it will be useful, |
| 11 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 12 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| 13 | * GNU General Public License for more details. |
Sol Boucher | 69b88bf | 2015-02-26 11:47:19 -0800 | [diff] [blame] | 14 | */ |
| 15 | |
| 16 | #ifndef FMD_H_ |
| 17 | #define FMD_H_ |
| 18 | |
| 19 | #include <limits.h> |
| 20 | #include <stdbool.h> |
| 21 | #include <stddef.h> |
| 22 | #include <stdio.h> |
| 23 | |
| 24 | #define FMD_NOTFOUND UINT_MAX |
| 25 | |
Hung-Te Lin | 9497fcb | 2019-03-04 14:28:37 +0800 | [diff] [blame] | 26 | /** |
| 27 | * Flags used by flashmap_descriptor. |
| 28 | * These flags can be set by adding (NAME) after description name. |
| 29 | * For example, declaring a CBFS section named as COREBOOT for 16k: |
| 30 | * COREBOOT(CBFS) 16k |
| 31 | */ |
| 32 | union flashmap_flags { |
| 33 | struct { |
| 34 | int cbfs: 1; /* The section contains a CBFS area. */ |
Hung-Te Lin | 49a4450 | 2019-03-04 15:41:09 +0800 | [diff] [blame] | 35 | int preserve: 1; /* Preserve the section before update. */ |
Hung-Te Lin | 9497fcb | 2019-03-04 14:28:37 +0800 | [diff] [blame] | 36 | } f; |
| 37 | int v; |
| 38 | }; |
| 39 | |
Sol Boucher | 69b88bf | 2015-02-26 11:47:19 -0800 | [diff] [blame] | 40 | struct flashmap_descriptor { |
| 41 | char *name; |
| 42 | bool offset_known; |
| 43 | /** |
| 44 | * Offset relative to that of the parent node. |
| 45 | * Exception: for the root node in the descriptor tree, it is optional. |
| 46 | * In this case, if absent, it indicates that the flash chip will not be |
| 47 | * memory mapped at runtime; otherwise, its value indicates the base |
| 48 | * address of the flash chip in the virtual address space rather than |
| 49 | * representing an offset into the flash image itself. |
| 50 | * It is an error to read this field unless offset_known is set. |
| 51 | */ |
| 52 | unsigned offset; |
| 53 | bool size_known; |
| 54 | /** It is an error to read this field unless size_known is set. */ |
| 55 | unsigned size; |
| 56 | size_t list_len; |
Hung-Te Lin | 9497fcb | 2019-03-04 14:28:37 +0800 | [diff] [blame] | 57 | union flashmap_flags flags; |
Sol Boucher | 69b88bf | 2015-02-26 11:47:19 -0800 | [diff] [blame] | 58 | /** It is an error to dereference this array if list_len is 0. */ |
| 59 | struct flashmap_descriptor **list; |
| 60 | }; |
| 61 | |
| 62 | /** |
Hung-Te Lin | 9497fcb | 2019-03-04 14:28:37 +0800 | [diff] [blame] | 63 | * **Client-defined** callback for flag "CBFS". |
| 64 | * This call is used to notify client code that the user has requested the given |
| 65 | * section node to be flagged with "CBFS". Implementations of this function |
| 66 | * should use their return type to tell the compiler whether the flag can be |
| 67 | * applied and can perform whatever actions are necessary. |
| 68 | * It's worth reiterating that this is only called on section nodes, and will |
| 69 | * never be called with the final, complete flashmap_descriptor because |
| 70 | * it is impossible to set flags for the image as a whole. |
Sol Boucher | 69b88bf | 2015-02-26 11:47:19 -0800 | [diff] [blame] | 71 | * |
Hung-Te Lin | 9497fcb | 2019-03-04 14:28:37 +0800 | [diff] [blame] | 72 | * @param flashmap_descriptor The section node with flag set |
| 73 | * @return Whether this flag can be applied |
Sol Boucher | 69b88bf | 2015-02-26 11:47:19 -0800 | [diff] [blame] | 74 | */ |
Hung-Te Lin | 9497fcb | 2019-03-04 14:28:37 +0800 | [diff] [blame] | 75 | bool fmd_process_flag_cbfs(const struct flashmap_descriptor *node); |
Sol Boucher | 69b88bf | 2015-02-26 11:47:19 -0800 | [diff] [blame] | 76 | |
| 77 | /** |
| 78 | * Parse and validate a flashmap descriptor from the specified stream. |
| 79 | * As part of this process, any fields that were omitted in the input are |
| 80 | * inferred from whatever information is known, if possible. The result is a |
| 81 | * tree with all its offset and size fields filled, except possibly the former |
| 82 | * part of the root node in the case of non--memory mapped flash. If a syntax |
| 83 | * error causes the parser to fail, or if there is not enough information given |
| 84 | * in the input file to determine any single missing value, the specific error |
| 85 | * is reported to standard error and this function returns NULL. |
| 86 | * |
| 87 | * @param stream File from which to read the (partial) flashmap descriptor |
| 88 | * @return Populated flashmap descriptor tree, or NULL on failure |
| 89 | */ |
| 90 | struct flashmap_descriptor *fmd_create(FILE *stream); |
| 91 | |
| 92 | /** @param victim Valid descriptor tree to be cleaned up, or NULL for no-op */ |
| 93 | void fmd_cleanup(struct flashmap_descriptor *victim); |
| 94 | |
| 95 | /** |
| 96 | * @param tree Must be non-NULL |
| 97 | * @return The number of nodes in the tree, including the root |
| 98 | */ |
| 99 | size_t fmd_count_nodes(const struct flashmap_descriptor *tree); |
| 100 | |
| 101 | /** |
| 102 | * @param root The flashmap descriptor to search |
| 103 | * @param name The name of the sought-after section |
| 104 | * @return The desired section node, or NULL if none was found |
| 105 | */ |
| 106 | const struct flashmap_descriptor *fmd_find_node( |
| 107 | const struct flashmap_descriptor *root, const char *name); |
| 108 | |
| 109 | /** |
| 110 | * @param root Parent node to whose start the "absolute" offset will be relative |
| 111 | * @param name The name of the node whose offset to determine |
| 112 | * @return The "absolute" offset, or FMD_NOTFOUND if the node wasn't found |
| 113 | */ |
| 114 | unsigned fmd_calc_absolute_offset(const struct flashmap_descriptor *root, |
| 115 | const char *name); |
| 116 | |
| 117 | /** @param tree Must be non-NULL */ |
| 118 | void fmd_print(const struct flashmap_descriptor *tree); |
| 119 | |
| 120 | typedef struct flashmap_descriptor **flashmap_descriptor_iterator_t; |
| 121 | |
| 122 | /* |
| 123 | * Run the subsequent statement once on each descendant of the specified node. |
| 124 | * |
| 125 | * @param iterator A flashmap_descriptor_iterator_t (automatically declared) |
| 126 | * @param parent The parent node of those over which the loop should iterate |
| 127 | */ |
| 128 | #define fmd_foreach_child_iterator(iterator, parent) \ |
| 129 | for (flashmap_descriptor_iterator_t iterator = parent->list; \ |
| 130 | iterator < parent->list + parent->list_len; ++iterator) |
| 131 | |
| 132 | /* |
| 133 | * Run the subsequent statement once on each descendant of the specified node. |
| 134 | * |
| 135 | * @param child A struct flashmap_descriptor * (automatically declared) |
| 136 | * @param parent The parent node of those over which the loop should iterate |
| 137 | */ |
| 138 | #define fmd_foreach_child(child, parent) \ |
| 139 | for (struct flashmap_descriptor **fmd_foreach_child_iterator_ = \ |
| 140 | parent->list, *child = NULL; \ |
| 141 | fmd_foreach_child_iterator_ < \ |
| 142 | parent->list + parent->list_len && \ |
| 143 | (child = *fmd_foreach_child_iterator_); \ |
| 144 | ++fmd_foreach_child_iterator_) |
| 145 | |
| 146 | #endif |