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