cbfstool: Restructure around support for reading/writing portions of files

The buffer API that cbfstool uses to read and write files only directly supports
one-shot operations on whole files. This adds an intermediate partitioned_file
module that sits on top of the buffer system and has an awareness of FMAP
entries. It provides an easy way to get a buffer for an individual region of a
larger image file based on FMAP section name, as well as incrementally write
those smaller buffers back to the backing file at the appropriate offset. The
module has two distinct modes of operation:
- For new images whose layout is described exclusively by an FMAP section, all
the aforementioned functionality will be available.
- For images in the current format, where the CBFS master header serves as the
root of knowledge of the image's size and layout, the module falls back to a
legacy operation mode, where it only allows manipulation of the entire image
as one unit, but exposes this support through the same interface by mapping
the region named SECTION_NAME_PRIMARY_CBFS ("COREBOOT") to the whole file.

The tool is presently only ported onto the new module running in legacy mode:
higher-level support for true "partitioned" images will be forthcoming. However,
as part of this change, the crusty cbfs_image_from_file() and
cbfs_image_write_file() abstractions are removed and replaced with a single
cbfs_image function, cbfs_image_from_buffer(), as well as centralized image
reading/writing directly in cbfstool's main() function. This reduces the
boilerplate required to implement each new action, makes the create action much
more similar to the others, and will make implementing additional actions and
adding in support for the new format much easier.

BUG=chromium:470407
TEST=Build panther and nyan_big coreboot.rom images with and without this patch
and diff their hexdumps. Ensure that no differences occur at different locations
from the diffs between subsequent builds of an identical source tree. Then flash
a full new build onto nyan_big and watch it boot normally.
BRANCH=None

Change-Id: I25578c7b223bc8434c3074cb0dd8894534f8c500
Signed-off-by: Sol Boucher <solb@chromium.org>
Original-Commit-Id: 7e1c96a48e7a27fc6b90289d35e6e169d5e7ad20
Original-Change-Id: Ia4a1a4c48df42b9ec2d6b9471b3a10eb7b24bb39
Original-Signed-off-by: Sol Boucher <solb@chromium.org>
Original-Reviewed-on: https://chromium-review.googlesource.com/265581
Original-Reviewed-by: Aaron Durbin <adurbin@chromium.org>
Reviewed-on: http://review.coreboot.org/10134
Tested-by: build bot (Jenkins)
Reviewed-by: Patrick Georgi <pgeorgi@google.com>

1 files changed, 174 insertions, 0 deletions

diff --git a/util/cbfstool/partitioned_file.h b/util/cbfstool/partitioned_file.h
new file mode 100644
index 0000000000..97d1b57bed
--- /dev/null
+++ b/util/cbfstool/partitioned_file.h
@@ -0,0 +1,174 @@
+/*
+ * partitioned_file.h, read and write binary file "partitions" described by FMAP
+ *
+ * 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 PARITITONED_FILE_H_
+#define PARITITONED_FILE_H_
+
+#include "common.h"
+#include "flashmap/fmap.h"
+
+#include <stdbool.h>
+#include <stddef.h>
+
+typedef struct partitioned_file partitioned_file_t;
+
+/** @return Whether the specific existing file should be opened in flat mode. */
+typedef bool (*partitioned_file_flat_decider_t)(struct buffer *buffer);
+
+/** Pass to partitioned_file_reopen() to force opening as a partitioned file. */
+#define partitioned_file_open_as_partitioned NULL
+
+/** Pass to partitioned_file_reopen() to force opening as a flat file. */
+extern const partitioned_file_flat_decider_t partitioned_file_open_as_flat;
+
+/**
+ * Create a new filesystem-backed flat buffer.
+ * This backwards-compatibility function creates a new in-memory buffer and
+ * backing binary file of the specified size. Although the file won't actually
+ * have multiple regions, it'll still be possible to access and manipulate it
+ * using this module; this is accomplished by requesting the special region
+ * whose name matches SECTION_NAME_PRIMARY_CBFS, which maps to the whole file.
+ * Note that the caller will be responsible for calling partitioned_file_close()
+ * on the returned object, and that this function will overwrite any existing
+ * file with the given name without warning.
+ *
+ * @param filename   Name of the backing file
+ * @param image_size Size of the image
+ * @return           Caller-owned partitioned file, or NULL on error
+ */
+partitioned_file_t *partitioned_file_create_flat(const char *filename,
+							size_t image_size);
+
+/**
+ * Create a new filesystem-backed partitioned buffer.
+ * This creates a new in-memory buffer and backing binary file. Both are
+ * segmented into regions according to the provided flashmap's sections, and the
+ * flashmap itself is automatically copied into the region named
+ * SECTION_NAME_FMAP: a section with this name must already exist in the FMAP.
+ * After calling this function, it is safe for the caller to clean up flashmap
+ * at any time. The partitioned_file_t returned from this function is separately
+ * owned by the caller, and must later be passed to partitioned_file_close().
+ * Note that this function will overwrite any existing file with the given name
+ * without warning.
+ *
+ * @param filename Name of the backing file
+ * @param flashmap Buffer containing an FMAP file layout
+ * @return         Caller-owned partitioned file, or NULL on error
+ */
+partitioned_file_t *partitioned_file_create(const char *filename,
+						struct buffer *flashmap);
+
+/**
+ * Read a file back in from the disk.
+ * An in-memory buffer is created and populated with the file's contents. If
+ * flat_override is NULL and the image contains an FMAP, it will be opened as a
+ * full partitioned file; otherwise, it will be opened as a flat file as if it
+ * had been created by partitioned_file_create_flat(). This selection behavior
+ * is extensible: if a flat_override function is provided, it is invoked before
+ * searching for an FMAP, and has the option of explicitly instructing the
+ * module to open the image as a flat file based on its contents.
+ * The partitioned_file_t returned from this function is separately owned by the
+ * caller, and must later be passed to partitioned_file_close();
+ *
+ * @param filename      Name of the file to read in
+ * @param flat_override Callback that can decide to open it as flat, or NULL
+ * @return              Caller-owned partitioned file, or NULL on error
+ */
+partitioned_file_t *partitioned_file_reopen(const char *filename,
+				partitioned_file_flat_decider_t flat_override);
+
+/**
+ * Write a buffer's contents to its original region within a segmented file.
+ * This function should only be called on buffers originally retrieved by a call
+ * to partitioned_file_read_region() on the same partitioned file object. The
+ * contents of this buffer are copied back to the same region of the buffer and
+ * backing file that the region occupied before.
+ *
+ * @param file   Partitioned file to which to write the data
+ * @param buffer Modified buffer obtained from partitioned_file_read_region()
+ * @return       Whether the operation was successful
+ */
+bool partitioned_file_write_region(partitioned_file_t *file,
+						const struct buffer *buffer);
+
+/**
+ * Obtain one particular region of a segmented file.
+ * The result is owned by the partitioned_file_t and shared among every caller
+ * of this function. Thus, it is an error to buffer_delete() it; instead, clean
+ * up the entire partitioned_file_t once it's no longer needed with a single
+ * call to partitioned_file_close().
+ * Note that, if the buffer obtained from this function is modified, the changes
+ * will be reflected in any buffers handed out---whether earlier or later---for
+ * any region inclusive of the altered location(s). However, the backing file
+ * will not be updated until someone calls partitioned_file_write_region() on a
+ * buffer that includes the alterations.
+ *
+ * @param dest   Empty destination buffer for the data
+ * @param file   Partitioned file from which to read the data
+ * @param region Name of the desired FMAP region
+ * @return       Whether the copy was performed successfully
+ */
+bool partitioned_file_read_region(struct buffer *dest,
+			const partitioned_file_t *file, const char *region);
+
+/** @param file Partitioned file to flush and cleanup */
+void partitioned_file_close(partitioned_file_t *file);
+
+/** @return Whether the file is partitioned (i.e. not flat). */
+bool partitioned_file_is_partitioned(const partitioned_file_t *file);
+
+/** @return Whether the specified region begins with the magic bytes. */
+bool partitioned_file_region_check_magic(const partitioned_file_t *file,
+		const char *region, const char *magic, size_t magic_len);
+
+/** @return Whether the specified region exists and contains nested regions. */
+bool partitioned_file_region_contains_nested(const partitioned_file_t *file,
+							const char *region);
+
+/** @return An immutable reference to the FMAP, or NULL for flat images. */
+const struct fmap *partitioned_file_get_fmap(const partitioned_file_t *file);
+
+/** @return Whether to include area in the running count. */
+typedef bool (*partitioned_file_fmap_selector_t)
+				(const struct fmap_area *area, const void *arg);
+
+/**
+ * Count the number of FMAP entries fulfilling a certain criterion.
+ * The result is always 0 if run on a flat (non-partitioned) image.
+ *
+ * @param file     File on whose FMAP entries the operation should be run
+ * @param callback Decider answering whether each individual region should count
+ * @param arg      Additional information to furnish to the decider on each call
+ * @return         The number of FMAP sections with that property
+ */
+unsigned partitioned_file_fmap_count(const partitioned_file_t *file,
+		partitioned_file_fmap_selector_t callback, const void *arg);
+
+/** Selector that counts every single FMAP section. */
+extern const partitioned_file_fmap_selector_t partitioned_file_fmap_select_all;
+
+/** Selector that counts FMAP sections that are descendants of fmap_area arg. */
+extern const partitioned_file_fmap_selector_t
+				partitioned_file_fmap_select_children_of;
+
+/** Selector that counts FMAP sections that contain the fmap_area arg. */
+extern const partitioned_file_fmap_selector_t
+					partitioned_file_fmap_select_parents_of;
+
+#endif