include/zircon-estelle/partition.h

/*
 * Copyright (c) 2018 The Fuchsia Authors
 *
 * SPDX-License-Identifier:	BSD-3-Clause
 */

#ifndef _ZIRCON_PARTITION_H_
#define _ZIRCON_PARTITION_H_

#include <zircon/boot/image.h>

#define ZIRCON_PARTITION_PREFIX "zircon_"

/* TODO(dmitryya@) add descriptions for API */

/* Gets zircon partition layout */
const zbi_partition_map_t *zircon_get_partition_map(void);

/* Gets |name| partition size from zircon partition layout.
 */
int zircon_get_partititon_size(const char *name, uint64_t *size);

/* Writes |size| bytes from the buffer starting at |data| to the
 * |name| zircon partition.
 */
int zircon_partition_write(const char *name, uint64_t offset,
			   const unsigned char *data, size_t size);

/* Attempts to read |size| bytes from |name| zircon partition
 * into the buffer starting at |data|.
 */
int zircon_partition_read(const char *name, uint64_t offset,
			  unsigned char *data, size_t size);

/* Reads data + OOB bytes from NAND.
 *
 * Data is read as interleaved data->oob->data->oob->... bytes. Read failures
 * are marked by an 8-char error code with the rest of the page all 0s. See
 * constants below for the possible error codes.
 *
 * This function is designed to support sequential calls to fetch chunks of
 * partitions at a time if the partition is too large to fit in the buffer.
 * |offset_out| gives the next offset to start at, or 0 if we reached the
 * end of the partition.
 *
 * @name: partition name.
 * @offset: partition byte offset to start reading at; must be page-aligned.
 * @buffer: buffer to read into.
 * @size: buffer size; may not be filled completely if the partition ends
 *        early or we can't fit another whole page.
 * @offset_out: offset to start the next read at, or 0 if we reached the
 *              partition end.
 * @size_out: total number of bytes (data + OOB) copied into buffer; always
 *            contains complete pages.
 *
 * Returns 0 on success, nonzero on failure.
 */
int zircon_partition_read_oob(const char *name, uint64_t offset,
			      uint8_t *buffer, size_t size,
			      uint64_t *offset_out, size_t *size_out);

/* Encountered a known bad block and skipped without attempting to read. */
#define READ_OOB_ERROR_CODE_BAD_BLOCK "BADBLOCK"

/* Attempted to read multiple times but failed each time. */
#define READ_OOB_ERROR_CODE_READ_FAILURE "READFAIL"

/* Erase |name| partition */
int zircon_partition_erase(const char *name);

#endif /* _ZIRCON_PARTITION_H_ */