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

#ifndef _ZIRCON_UBOOT_PARTITION_H_
#define _ZIRCON_UBOOT_PARTITION_H_

/**
 * DOC: Zircon Partitions
 *
 * This header describes an interface for "zircon partitions".
 * A zircon partition is an abstraction for interacting with
 * the standard partitions required by zircon:
 * Ex. zircon_a, zircon_b, zircon_r, misc, vbmeta_a, etc.
 *
 * These partitions may or may not exist in the GPT, but this
 * interface will abstract the details of how to access them.
 */

#define ZIRCON_PARTITION_PREFIX "zircon"

typedef struct zircon_partition_data_t zircon_partition_data_t;

typedef struct zircon_partition zircon_partition;
struct zircon_partition {
	// partition size in bytes
	uint64_t size;

	/**
	 * read() - Read from zircon partition.
	 *
	 * @part:	This zircon partition instance
	 * @offset:	Offset in bytes at which to read data.
	 * @buffer:	Buffer to read into
	 * @length:	Number of bytes to read.
	 *
	 * Return:	0 if OK, non-zero value on error.
	 */
	int (*read)(const zircon_partition *part, uint64_t offset, void *buffer,
		    size_t length);

	/**
	 * write() - Write to zircon partition.
	 *
	 * @part:	This zircon partition instance
	 * @offset:	Offset in bytes at which to write data.
	 * @buffer:	Buffer of data to write
	 * @length:	Number of bytes to write.
	 *
	 * Return:	0 if OK, non-zero value on error.
	 */
	int (*write)(const zircon_partition *part, uint64_t offset,
		     const void *buffer, size_t length);

	/**
	 * erase() - Erase zircon partition.
	 *
	 * @part:	This zircon partition instance
	 *
	 * Return:	0 if OK, non-zero value on error.
	 */
	int (*erase)(const zircon_partition *part);

	// Internal partition data, do not touch.
	zircon_partition_data_t *data;
};

/**
 * zircon_get_partition() - Get zircon_partition by name
 *
 * @name:	Zircon partition name.
 *
 * Return:	Pointer to zircon_partition instance if it exists.
 * 		Must be freed with `zircon_free_partition`.
 * 		Returns NULL if partition name does not exist.
 */
zircon_partition *zircon_get_partition(const char *name);

/**
 * zircon_get_fastboot_partition() - Get zircon_partition by name for fastboot
 *
 * The returned zircon_partition only contains the functions currently available.
 * For example, if a partition is write-restricted and the device is locked,
 * this will return a zircon_partition with a NULL write function pointer.
 *
 * @name:	Zircon partition name.
 *
 * Return:	Pointer to zircon_partition instance if it exists.
 * 		Must be freed with `zircon_free_partition`.
 * 		Returns NULL if partition name does not exist.
 */
zircon_partition *zircon_get_fastboot_partition(const char *name);

/**
 * zircon_free_partition() - Frees zircon_partition
 *
 * @part:	Zircon Partition instance to free.
 */
void zircon_free_partition(zircon_partition *part);

#endif /* _ZIRCON_UBOOT_PARTITION_H_ */