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