/*
 * Copyright © 2014 Kosma Moczek <kosma@cloudyourcar.com>
 * This program is free software. It comes without any warranty, to the extent
 * permitted by applicable law. You can redistribute it and/or modify it under
 * the terms of the Do What The Fuck You Want To Public License, Version 2, as
 * published by Sam Hocevar. See the COPYING file for more details.
 */

#ifndef RINGFS_H
#define RINGFS_H

/**
 * @defgroup ringfs_api RingFS API
 * @{
 */

#include <stdint.h>
#include <stdio.h>
#include <stddef.h>
//#include <unistd.h>
typedef size_t ssize_t;

#ifndef NDEBUG
#define RFS_ASSERT(x)	((void)(x))
#else /* debugging enabled */
void ringfs_assert_failed(int8_t* func, int8_t* file, uint32_t line);
#define RFS_ASSERT(e)       ((e) ? (void)0 : ringfs_assert_failed(#e, __FILE__, __LINE__))	
#endif	/* NDEBUG */

/**
 * Flash memory+parition descriptor.
 */
struct ringfs_flash_partition
{
    int sector_size;            /**< Sector size, in bytes. */
    int sector_offset;          /**< Partition offset, in sectors. */
    int sector_count;           /**< Partition size, in sectors. */

    /**
     * Erase a sector.
     * @param address Any address inside the sector.
     * @returns Zero on success, -1 on failure.
		 * 擦除扇区。
		 * @param address扇区内的任何地址。
		 * @return 成功时为零，失败时为-1。
     */
    int (*sector_erase)(struct ringfs_flash_partition *flash, int address);
    /**
     * Program flash memory bits by toggling them from 1 to 0.
     * @param address Start address, in bytes.
     * @param data Data to program.
     * @param size Size of data.
     * @returns size on success, -1 on failure.
     */
    ssize_t (*program)(struct ringfs_flash_partition *flash, int address, const void *data, size_t size);
    /**
     * Read flash memory.
     * @param address Start address, in bytes.
     * @param data Buffer to store read data.
     * @param size Size of data.
     * @returns size on success, -1 on failure.
     */
    ssize_t (*read)(struct ringfs_flash_partition *flash, int address, void *data, size_t size);
};

/** @private */
struct ringfs_loc {
    int sector;
    int slot;
};

/**
 * RingFS instance. Should be initialized with ringfs_init() befure use.
 * Structure fields should not be accessed directly.
	*RingFS实例。应在使用前使用ringfs_init（）初始化。
	*不应直接访问结构字段。
 * */
struct ringfs {
    /* Constant values, set once at ringfs_init(). */
    struct ringfs_flash_partition *flash;
    uint32_t version;
    int object_size;
    /* Cached values. */
    int slots_per_sector;

    /* Read/write pointers. Modified as needed. */
    struct ringfs_loc read;
    struct ringfs_loc write;
    struct ringfs_loc cursor;
};

/**
 * Initialize a RingFS instance. Must be called before the instance can be used
 * with the other ringfs_* functions.
 * 初始化RingFS实例。必须在使用实例之前调用
 * 与其他ringfs_*函数一起使用。
 * @param fs RingFS instance to be initialized.
 * @param flash Flash memory interface. Must be implemented externally.
 * @param version Object version. Should be incremented whenever the object's
 *                semantics or size change in a backwards-incompatible way.
 * @param object_size Size of one stored object, in bytes.
 * @returns Zero on success, -1 on failure.
 */
int ringfs_init(struct ringfs *fs, struct ringfs_flash_partition *flash, uint32_t version, int object_size);

/**
 * Format the flash memory.
 * 格式化FLASH 存储器。
 *
 * @param fs Initialized RingFS instance.
 * @returns Zero on success, -1 on failure.
 */
int ringfs_format(struct ringfs *fs);

/**
 * Scan the flash memory for a valid filesystem.
 * 扫描FLASH 存储器以获取有效的文件系统
 *
 * @param fs Initialized RingFS instance.
 * @returns Zero on success, -1 on failure.
 */
int ringfs_scan(struct ringfs *fs);

/**
 * Calculate maximum RingFS capacity.
 * 计算RingFS最大容量。
 *
 * @param fs Initialized RingFS instance.
 * @returns Maximum capacity on success, -1 on failure.
 */
int ringfs_capacity(struct ringfs *fs);

/**
 * Calculate approximate object count.
 * Runs in O(1).
 * 计算近似对象数。
 * 在O（1）中运行。
 *
 * @param fs Initialized RingFS instance.
 * @returns Estimated object count on success, -1 on failure.
 */
int ringfs_count_estimate(struct ringfs *fs);

/**
 * Calculate exact object count.
 * Runs in O(n).
 * 计算确切的对象数量。
 * 以O（n）运行。
 * 
 * @param fs Initialized RingFS instance.
 * @returns Exact object count on success, -1 on failure.
 */
int ringfs_count_exact(struct ringfs *fs);

/**
 * Append an object at the end of the ring. Deletes oldest objects as needed.
 * 在RingFS末端附加一个对象。根据需要删除最旧的对象。
 * @param fs Initialized RingFS instance.
 * @param object Object to be stored.
 * @returns Zero on success, -1 on failure.
 */
int ringfs_append(struct ringfs *fs, const void *object);
/**
 *  Deletes newest objects.
 *  根据删除最新可用的对象。
 * @param fs Initialized RingFS instance.
 * @param object Object to be stored.
 * @returns Zero on success, -1 on failure.
 */
int ringfs_pop(struct ringfs *fs, void *object);
/**
 *  Deletes cur valid objects.
 *  根据当前向前删除可用的对象。
 * @param fs Initialized RingFS instance.
 * @param object Object to be stored.
 * @returns Zero on success, -1 on failure.
 */
int ringfs_del(struct ringfs *fs, void *object);
/**
 *  Deletes newest objects.
 *  根据删除最新可用的对象。
 * @param fs Initialized RingFS instance.
 * @param object Object to be stored.
 * @returns Zero on success, -1 on failure.
 */
int ringfs_pop(struct ringfs *fs, void *object);

/**
 * Fetch next object from the ring, oldest-first. Advances read cursor.
 * 从RingFS中取出下一个对象，先取出最旧的。前进读取光标。
 *
 * @param fs Initialized RingFS instance.
 * @param object Buffer to store retrieved object.
 * @returns Zero on success, -1 on failure.
 */
int ringfs_fetch(struct ringfs *fs, void *object);

/**
 * Discard all fetched objects up to the read cursor.
 * 丢弃到读取光标为止的所有提取对象。
 *
 * @param fs Initialized RingFS instance.
 * @returns Zero on success, -1 on failure.
 */
int ringfs_discard(struct ringfs *fs);

int ringfs_item_discard(struct ringfs *fs);

/**
 * Rewind the read cursor back to the oldest object.
 * 将读取光标回退到最旧的对象。
 * @param fs Initialized RingFS instance.
 * @returns Zero on success, -1 on failure.
 */
int ringfs_rewind(struct ringfs *fs);

/**
 * Rewind the read cursor advance to the newest object.
 * 将读取光标前进到最新的对象。
 * @param fs Initialized RingFS instance.
 * @returns Zero on success, -1 on failure.
 */
int ringfs_end(struct ringfs *fs);

/**
 * Dump filesystem metadata. For debugging purposes.
 * 转储文件系统元数据。用于调试目的。
 * @param stream File stream to write to.
 * @param fs Initialized RingFS instance.
 */
void ringfs_dump(FILE *stream, struct ringfs *fs);

/**
 * 修正读取位置。
 * @param stream File stream to write to.
 * @param fs Initialized RingFS instance.
 */
int ringfs_check(struct ringfs *fs);

/**
 * @}
 */

#endif

/* vim: set ts=4 sw=4 et: */