util/cbfstool/partitioned_file.h

/*
 * 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.
 */

#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 The image's overall filesize, regardless of whether it's flat. */
size_t partitioned_file_total_size(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