pios_flashfs_logfs.c

Go to the documentation of this file.

/*
 * 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; either version 3 of the License, or
 * (at your option) any later version.
 *
 * 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, see <http://www.gnu.org/licenses/>
 */

/* Project Includes */
#include "pios.h"

#include "pios_flash.h"              /* PIOS_FLASH_* */
#include "pios_flashfs_logfs_priv.h" /* Internal API */

#include <stdbool.h>
#include <stddef.h>             /* NULL */

#define MIN(x,y) ((x) < (y) ? (x) : (y))

/*
 * Filesystem state data tracked in RAM
 */

enum pios_flashfs_logfs_dev_magic {
        PIOS_FLASHFS_LOGFS_DEV_MAGIC = 0x94938201,
};

struct logfs_state {
        enum pios_flashfs_logfs_dev_magic magic;
        const struct flashfs_logfs_cfg *cfg;
        bool mounted;
        uint8_t active_arena_id;

        /* NOTE: num_active_slots + num_free_slots will not typically add
         *       up to the number of slots in the arena since some of the
         *       slots will be obsolete or otherwise invalidated
         */
        uint16_t num_free_slots;   /* slots in free state */
        uint16_t num_active_slots; /* slots in active state */

        /* Underlying flash partition handle */
        uintptr_t partition_id;
        uint32_t partition_size;
};

/*
 * Internal Utility functions
 */

static uintptr_t logfs_get_addr(const struct logfs_state *logfs, uint8_t arena_id, uint16_t slot_id)
{
        PIOS_Assert(arena_id < (logfs->partition_size / logfs->cfg->arena_size));
        PIOS_Assert(slot_id < (logfs->cfg->arena_size / logfs->cfg->slot_size));

        return ((arena_id * logfs->cfg->arena_size) +
                (slot_id  * logfs->cfg->slot_size));
}

/*
 * The bits within these enum values must progress ONLY
 * from 1 -> 0 so that we can write later ones on top
 * of earlier ones in NOR flash without an erase cycle.
 */
enum arena_state {
        /*
         * The STM32F30X flash subsystem is only capable of
         * writing words or halfwords. In this case we use halfwords.
         * In addition to that it is only capable to write to erased
         * cells (0xffff) or write a cell from anything to (0x0000).
         * To cope with this, the F3 needs carefully crafted enum values.
         * For this to work the underlying flash driver has to
         * check each halfword if it has changed before writing.
         */
        ARENA_STATE_ERASED   = 0xFFFFFFFF,
        ARENA_STATE_RESERVED = 0xE6E6FFFF,
        ARENA_STATE_ACTIVE   = 0xE6E66666,
        ARENA_STATE_OBSOLETE = 0x00000000,
} __attribute__((packed));

struct arena_header {
        uint32_t magic;
        enum arena_state state;
} __attribute__((packed));


/****************************************
 * Arena life-cycle transition functions
 ****************************************/

static int32_t logfs_erase_arena(const struct logfs_state *logfs, uint8_t arena_id)
{
        uintptr_t arena_addr = logfs_get_addr (logfs, arena_id, 0);

        /* Erase all of the sectors in the arena */
        if (PIOS_FLASH_erase_range(logfs->partition_id, arena_addr, logfs->cfg->arena_size) != 0) {
                return -1;
        }

        /* Mark this arena as fully erased */
        struct arena_header arena_hdr = {
                .magic = logfs->cfg->fs_magic,
                .state = ARENA_STATE_ERASED,
        };

        if (PIOS_FLASH_write_data(logfs->partition_id,
                                        arena_addr,
                                        (uint8_t *)&arena_hdr,
                                        sizeof(arena_hdr)) != 0) {
                return -2;
        }

        /* Arena is ready to be activated */
        return 0;
}

static int32_t logfs_reserve_arena (const struct logfs_state *logfs, uint8_t arena_id)
{
        uintptr_t arena_addr = logfs_get_addr (logfs, arena_id, 0);

        /* Read in the current arena header */
        struct arena_header arena_hdr;
        if (PIOS_FLASH_read_data(logfs->partition_id,
                                        arena_addr,
                                        (uint8_t *)&arena_hdr,
                                        sizeof(arena_hdr)) != 0) {
                return -1;
        }
        if (arena_hdr.state != ARENA_STATE_ERASED) {
                /* Arena was not erased, can't reserve it */
                return -2;
        }

        /* Set the arena state to reserved */
        arena_hdr.state = ARENA_STATE_RESERVED;

        /* Write the arena header back to flash */
        if (PIOS_FLASH_write_data(logfs->partition_id,
                                        arena_addr,
                                        (uint8_t *)&arena_hdr,
                                        sizeof(arena_hdr)) != 0) {
                return -3;
        }

        /* Arena is ready to be filled */
        return 0;
}

static int32_t logfs_erase_all_arenas(const struct logfs_state *logfs)
{
        uint16_t num_arenas = logfs->partition_size / logfs->cfg->arena_size;

        for (uint16_t arena = 0; arena < num_arenas; arena++) {
                if (logfs_erase_arena(logfs, arena) != 0)
                        return -1;
        }

        return 0;
}

static int32_t logfs_activate_arena(const struct logfs_state *logfs, uint8_t arena_id)
{
        uintptr_t arena_addr = logfs_get_addr(logfs, arena_id, 0);

        /* Make sure this arena has been previously erased */
        struct arena_header arena_hdr;
        if (PIOS_FLASH_read_data(logfs->partition_id,
                                        arena_addr,
                                        (uint8_t *)&arena_hdr,
                                        sizeof (arena_hdr)) != 0) {
                /* Failed to read arena header */
                return -1;
        }
        if ((arena_hdr.state != ARENA_STATE_RESERVED) &&
                (arena_hdr.state != ARENA_STATE_ERASED)) {
                /* Arena was not erased or reserved, can't activate it */
                return -2;
        }

        /* Mark this arena as active */
        arena_hdr.state = ARENA_STATE_ACTIVE;
        if (PIOS_FLASH_write_data(logfs->partition_id,
                                        arena_addr,
                                        (uint8_t *)&arena_hdr,
                                        sizeof(arena_hdr)) != 0) {
                return -3;
        }

        /* The arena is now activated and the log may be mounted */
        return 0;
}

static int32_t logfs_obsolete_arena(const struct logfs_state *logfs, uint8_t arena_id)
{
        uintptr_t arena_addr = logfs_get_addr (logfs, arena_id, 0);

        /* We shouldn't be retiring the currently active arena */
        PIOS_Assert(!logfs->mounted);

        /* Make sure this arena was previously active */
        struct arena_header arena_hdr;
        if (PIOS_FLASH_read_data(logfs->partition_id,
                                        arena_addr,
                                        (uint8_t *)&arena_hdr,
                                        sizeof (arena_hdr)) != 0) {
                /* Failed to read arena header */
                return -1;
        }

        if (arena_hdr.state != ARENA_STATE_ACTIVE) {
                /* Arena was not previously active, can't obsolete it */
                return -2;
        }

        /* Mark this arena as obsolete */
        arena_hdr.state = ARENA_STATE_OBSOLETE;
        if (PIOS_FLASH_write_data(logfs->partition_id,
                                        arena_addr,
                                        (uint8_t *)&arena_hdr,
                                        sizeof(arena_hdr)) != 0) {
                return -3;
        }

        /* Arena is now obsoleted */
        return 0;
}

static int32_t logfs_find_active_arena(const struct logfs_state *logfs)
{
        /* Search for the lowest numbered active arena */
        for (uint8_t arena_id = 0;
             arena_id < logfs->partition_size / logfs->cfg->arena_size;
             arena_id++) {
                uintptr_t arena_addr = logfs_get_addr (logfs, arena_id, 0);
                /* Load the arena header */
                struct arena_header arena_hdr;
                if (PIOS_FLASH_read_data(logfs->partition_id,
                                                arena_addr,
                                                (uint8_t *)&arena_hdr,
                                                sizeof (arena_hdr)) != 0) {
                        return -2;
                }
                if ((arena_hdr.state == ARENA_STATE_ACTIVE) &&
                        (arena_hdr.magic == logfs->cfg->fs_magic)) {
                        /* This is the first active arena */
                        return arena_id;
                }
        }

        /* Didn't find an active arena */
        return -1;
}

/*
 * The bits within these enum values must progress ONLY
 * from 1 -> 0 so that we can write later ones on top
 * of earlier ones in NOR flash without an erase cycle.
 */
enum slot_state {
        /*
         * The STM32F30X flash subsystem is only capable of
         * writing words or halfwords. In this case we use halfwords.
         * In addition to that it is only capable to write to erased
         * cells (0xffff) or write a cell from anything to (0x0000).
         * To cope with this, the F3 needs carfully crafted enum values.
         * For this to work the underlying flash driver has to
         * check each halfword if it has changed before writing.
         */
        SLOT_STATE_EMPTY    = 0xFFFFFFFF,
        SLOT_STATE_RESERVED = 0xFAFAFFFF,
        SLOT_STATE_ACTIVE   = 0xFAFAAAAA,
        SLOT_STATE_OBSOLETE = 0x00000000,
} __attribute__((packed));

struct slot_header {
        enum slot_state state;
        uint32_t obj_id;
        uint16_t obj_inst_id;
        uint16_t obj_size;
} __attribute__((packed));

/* NOTE: Must be called while holding the flash transaction lock */
static int32_t logfs_raw_copy_bytes (const struct logfs_state *logfs, uintptr_t src_addr, uint16_t src_size, uintptr_t dst_addr)
{
#define RAW_COPY_BLOCK_SIZE 16
        uint8_t data_block[RAW_COPY_BLOCK_SIZE];

        while (src_size) {
                uint16_t blk_size;
                if (src_size >= RAW_COPY_BLOCK_SIZE) {
                        /* Copy a full block */
                        blk_size = RAW_COPY_BLOCK_SIZE;
                } else {
                        /* Copy the remainder */
                        blk_size = src_size;
                }

                /* Read a block of data from source */
                if (PIOS_FLASH_read_data(logfs->partition_id,
                                                src_addr,
                                                data_block,
                                                blk_size) != 0) {
                        /* Failed to read next chunk from source */
                        return -1;
                }

                /* Write a block of data to destination */
                if (PIOS_FLASH_write_data(logfs->partition_id,
                                                dst_addr,
                                                data_block,
                                                blk_size) != 0) {
                        /* Failed to write chunk to destination */
                        return -2;
                }

                /* Update the src/dst pointers */
                src_size -= blk_size;
                src_addr += blk_size;
                dst_addr += blk_size;
        }

        return 0;
}

/*
 * Is the entire filesystem full?
 * true = all slots in the arena are in the ACTIVE state (ie. garbage collection won't free anything)
 * false = some slots in the arena are either currently free or could be free'd by garbage collection
 */
static bool logfs_fs_is_full(const struct logfs_state *logfs)
{
        return (logfs->num_active_slots == (logfs->cfg->arena_size / logfs->cfg->slot_size) - 1);
}

/*
 * Is the log full?
 * true = there are no unwritten slots left in the log (garbage collection may or may not help)
 * false = there are still some entirely unused slots left in the log
 */
static bool logfs_log_is_full(const struct logfs_state *logfs)
{
        return (logfs->num_free_slots == 0);
}

static int32_t logfs_unmount_log(struct logfs_state *logfs)
{
        PIOS_Assert (logfs->mounted);

        logfs->num_active_slots = 0;
        logfs->num_free_slots   = 0;
        logfs->mounted          = false;

        return 0;
}

static int32_t logfs_mount_log(struct logfs_state *logfs, uint8_t arena_id)
{
        PIOS_Assert (!logfs->mounted);

        logfs->num_active_slots = 0;
        logfs->num_free_slots   = 0;
        logfs->active_arena_id  = arena_id;

        /* Scan the log to find out how full it is */
        for (uint16_t slot_id = 1;
             slot_id < (logfs->cfg->arena_size / logfs->cfg->slot_size);
             slot_id++) {
                struct slot_header slot_hdr;
                uintptr_t slot_addr = logfs_get_addr (logfs, logfs->active_arena_id, slot_id);
                if (PIOS_FLASH_read_data(logfs->partition_id,
                                                slot_addr,
                                                (uint8_t *)&slot_hdr,
                                                sizeof (slot_hdr)) != 0) {
                        return -1;
                }

                /*
                 * Empty slots must be in a continguous block at the
                 * end of the arena.
                 */
                PIOS_Assert (slot_hdr.state == SLOT_STATE_EMPTY ||
                        logfs->num_free_slots == 0);

                switch (slot_hdr.state) {
                case SLOT_STATE_EMPTY:
                        logfs->num_free_slots++;
                        break;
                case SLOT_STATE_ACTIVE:
                        logfs->num_active_slots++;
                        break;
                case SLOT_STATE_RESERVED:
                case SLOT_STATE_OBSOLETE:
                        break;
                }
        }

        /* Scan is complete, mark the arena mounted */
        logfs->active_arena_id = arena_id;
        logfs->mounted = true;

        return 0;
}

static bool PIOS_FLASHFS_Logfs_validate(const struct logfs_state *logfs)
{
        return (logfs && (logfs->magic == PIOS_FLASHFS_LOGFS_DEV_MAGIC));
}

static struct logfs_state *PIOS_FLASHFS_Logfs_alloc(void)
{
        struct logfs_state *logfs;

        logfs = (struct logfs_state *)PIOS_malloc_no_dma(sizeof(*logfs));
        if (!logfs) return (NULL);

        logfs->magic = PIOS_FLASHFS_LOGFS_DEV_MAGIC;
        return(logfs);
}
static void PIOS_FLASHFS_Logfs_free(struct logfs_state *logfs)
{
        /* Invalidate the magic */
        logfs->magic = ~PIOS_FLASHFS_LOGFS_DEV_MAGIC;
        PIOS_free(logfs);
}

int32_t PIOS_FLASHFS_Logfs_Init(uintptr_t *fs_id, const struct flashfs_logfs_cfg *cfg, enum pios_flash_partition_labels partition_label)
{
        PIOS_Assert(cfg);

        /* Find the partition id for the requested partition label */
        uintptr_t partition_id;
        if (PIOS_FLASH_find_partition_id(partition_label, &partition_id) != 0) {
                return -1;
        }

        /* Query the total partition size */
        uint32_t partition_size;
        if (PIOS_FLASH_get_partition_size(partition_id, &partition_size) != 0) {
                return -1;
        }

        /* We must have at least 2 arenas for garbage collection to work */
        PIOS_Assert((partition_size / cfg->arena_size > 1));

        /* arena_size must exactly divide the partition size */
        PIOS_Assert((partition_size % cfg->arena_size) == 0);

        int8_t rc;

        struct logfs_state *logfs;

        logfs = (struct logfs_state *) PIOS_FLASHFS_Logfs_alloc();
        if (!logfs) {
                rc = -1;
                goto out_exit;
        }

        /* Bind configuration parameters to this filesystem instance */
        logfs->cfg            = cfg;    /* filesystem configuration */
        logfs->partition_id   = partition_id; /* underlying partition */
        logfs->partition_size = partition_size; /* size of underlying partition */
        logfs->mounted        = false;

        if (PIOS_FLASH_start_transaction(logfs->partition_id) != 0) {
                rc = -1;
                goto out_exit;
        }

        bool found = false;
        int32_t arena_id;
        for (uint8_t try = 0; !found && try < 2; try++) {
                /* Find the active arena */
                arena_id = logfs_find_active_arena(logfs);
                if (arena_id >= 0) {
                        /* Found the active arena */
                        found = true;
                        break;
                } else {
                        /* No active arena found, erase and activate arena 0 */
                        if (logfs_erase_arena(logfs, 0) != 0)
                                break;
                        if (logfs_activate_arena(logfs, 0) != 0)
                                break;
                }
        }

        if (!found) {
                /* Still no active arena, something is broken */
                rc = -2;
                goto out_end_trans;
        }

        /* We've found an active arena, mount it */
        if (logfs_mount_log(logfs, arena_id) != 0) {
                /* Failed to mount the log, something is broken */
                rc = -3;
                goto out_end_trans;
        }

        /* Log has been mounted */
        rc = 0;

        *fs_id = (uintptr_t) logfs;

out_end_trans:
        PIOS_FLASH_end_transaction(logfs->partition_id);

out_exit:
        return rc;
}

int32_t PIOS_FLASHFS_Logfs_Destroy(uintptr_t fs_id)
{
        int32_t rc;

        struct logfs_state *logfs = (struct logfs_state *)fs_id;

        if (!PIOS_FLASHFS_Logfs_validate(logfs)) {
                rc = -1;
                goto out_exit;
        }

        PIOS_FLASHFS_Logfs_free(logfs);
        rc = 0;

out_exit:
        return rc;
}

/* NOTE: Must be called while holding the flash transaction lock */
static int32_t logfs_garbage_collect (struct logfs_state *logfs) {
        PIOS_Assert (logfs->mounted);

        /* Source arena is the active arena */
        uint8_t src_arena_id = logfs->active_arena_id;

        /* Compute destination arena */
        uint8_t dst_arena_id = (logfs->active_arena_id + 1) % (logfs->partition_size / logfs->cfg->arena_size);

        /* Erase destination arena */
        if (logfs_erase_arena (logfs, dst_arena_id) != 0) {
                return -1;
        }

        /* Reserve the destination arena so we can start filling it */
        if (logfs_reserve_arena (logfs, dst_arena_id) != 0) {
                /* Unable to reserve the arena */
                return -2;
        }

        /* Copy active slots from active arena to destination arena */
        uint16_t dst_slot_id = 1;
        for (uint16_t src_slot_id = 1;
             src_slot_id < (logfs->cfg->arena_size / logfs->cfg->slot_size);
             src_slot_id++) {
                struct slot_header slot_hdr;
                uintptr_t src_addr = logfs_get_addr (logfs, src_arena_id, src_slot_id);
                if (PIOS_FLASH_read_data(logfs->partition_id,
                                                src_addr,
                                                (uint8_t *)&slot_hdr,
                                                sizeof (slot_hdr)) != 0) {
                        return -3;
                }

                if (slot_hdr.state == SLOT_STATE_ACTIVE) {
                        uintptr_t dst_addr = logfs_get_addr (logfs, dst_arena_id, dst_slot_id);
                        if (logfs_raw_copy_bytes(logfs,
                                                        src_addr,
                                                        sizeof(slot_hdr) + slot_hdr.obj_size,
                                                        dst_addr) != 0) {
                                /* Failed to copy all bytes */
                                return -4;
                        }
                        dst_slot_id++;
                }
        }

        /* Activate the destination arena */
        if (logfs_activate_arena (logfs, dst_arena_id) != 0) {
                return -5;
        }

        /* Unmount the source arena */
        if (logfs_unmount_log (logfs) != 0) {
                return -6;
        }

        /* Obsolete the source arena */
        if (logfs_obsolete_arena (logfs, src_arena_id) != 0) {
                return -7;
        }

        /* Mount the new arena */
        if (logfs_mount_log (logfs, dst_arena_id) != 0) {
                return -8;
        }

        return 0;
}

/* NOTE: Must be called while holding the flash transaction lock */
static int16_t logfs_object_find_next (const struct logfs_state *logfs, struct slot_header *slot_hdr, uint16_t *curr_slot, uint32_t obj_id, uint16_t obj_inst_id)
{
        PIOS_Assert(slot_hdr);
        PIOS_Assert(curr_slot);

        /* First slot in the arena is reserved for arena header, skip it. */
        if (*curr_slot == 0) *curr_slot = 1;

        for (uint16_t slot_id = *curr_slot;
             slot_id < (logfs->cfg->arena_size / logfs->cfg->slot_size);
             slot_id++) {
                uintptr_t slot_addr = logfs_get_addr (logfs, logfs->active_arena_id, slot_id);

                if (PIOS_FLASH_read_data(logfs->partition_id,
                                                slot_addr,
                                                (uint8_t *)slot_hdr,
                                                sizeof (*slot_hdr)) != 0) {
                        return -2;
                }
                if (slot_hdr->state == SLOT_STATE_EMPTY) {
                        /* We hit the end of the log */
                        break;
                }
                if (slot_hdr->state == SLOT_STATE_ACTIVE &&
                        slot_hdr->obj_id      == obj_id &&
                        slot_hdr->obj_inst_id == obj_inst_id) {
                        /* Found what we were looking for */
                        *curr_slot = slot_id;
                        return 0;
                }
        }

        /* No matching entry was found */
        return -1;
}

/* NOTE: Must be called while holding the flash transaction lock */
/* OPTIMIZE: could trust that there is at most one active version of every object and terminate the search when we find one */
static int8_t logfs_delete_object (struct logfs_state *logfs, uint32_t obj_id, uint16_t obj_inst_id)
{
        int8_t rc;

        bool more = true;
        uint16_t curr_slot_id = 0;
        do {
                struct slot_header slot_hdr;
                switch (logfs_object_find_next (logfs, &slot_hdr, &curr_slot_id, obj_id, obj_inst_id)) {
                case 0:
                        /* Found a matching slot.  Obsolete it. */
                        slot_hdr.state = SLOT_STATE_OBSOLETE;
                        uintptr_t slot_addr = logfs_get_addr (logfs, logfs->active_arena_id, curr_slot_id);

                        if (PIOS_FLASH_write_data(logfs->partition_id,
                                                        slot_addr,
                                                        (uint8_t *)&slot_hdr,
                                                        sizeof(slot_hdr)) != 0) {
                                rc = -2;
                                goto out_exit;
                        }
                        /* Object has been successfully obsoleted and is no longer active */
                        logfs->num_active_slots--;
                        break;
                case -1:
                        /* Search completed, object not found */
                        more = false;
                        rc = 0;
                        break;
                default:
                        /* Error occurred during search */
                        rc = -1;
                        goto out_exit;
                }
        } while (more);

out_exit:
        return rc;
}

/* NOTE: Must be called while holding the flash transaction lock */
static int8_t logfs_reserve_free_slot (struct logfs_state *logfs, uint16_t *slot_id, struct slot_header *slot_hdr, uint32_t obj_id, uint16_t obj_inst_id, uint16_t obj_size)
{
        PIOS_Assert(slot_id);
        PIOS_Assert(slot_hdr);

        if (logfs->num_free_slots < 1) {
                /* No free slots to allocate */
                return -1;
        }

        if (obj_size > (logfs->cfg->slot_size - sizeof (slot_hdr))) {
                /* This object is too big for the slot */
                return -2;
        }

        uint16_t candidate_slot_id = (logfs->cfg->arena_size / logfs->cfg->slot_size) - logfs->num_free_slots;
        PIOS_Assert(candidate_slot_id > 0);

        uintptr_t slot_addr = logfs_get_addr (logfs, logfs->active_arena_id, candidate_slot_id);

        if (PIOS_FLASH_read_data(logfs->partition_id,
                                        slot_addr,
                                        (uint8_t *)slot_hdr,
                                        sizeof (*slot_hdr)) != 0) {
                /* Failed to read slot header for candidate slot */
                return -3;
        }

        if (slot_hdr->state != SLOT_STATE_EMPTY) {
                /* Candidate slot isn't empty!  Something is broken. */
                PIOS_DEBUG_Assert(0);
                return -4;
        }

        /* Mark this slot as RESERVED */
        slot_hdr->state       = SLOT_STATE_RESERVED;
        slot_hdr->obj_id      = obj_id;
        slot_hdr->obj_inst_id = obj_inst_id;
        slot_hdr->obj_size    = obj_size;

        if (PIOS_FLASH_write_data(logfs->partition_id,
                                        slot_addr,
                                        (uint8_t *)slot_hdr,
                                        sizeof(*slot_hdr)) != 0) {
                /* Failed to write the slot header */
                return -5;
        }

        /* FIXME: If the header write (above) failed, may have partially written data, thus corrupting that slot but we would have missed decrementing this counter */
        logfs->num_free_slots--;

        *slot_id = candidate_slot_id;
        return 0;
}

/* NOTE: Must be called while holding the flash transaction lock */
static int8_t logfs_append_to_log (struct logfs_state *logfs, uint32_t obj_id, uint16_t obj_inst_id, uint8_t *obj_data, uint16_t obj_size)
{
        /* Reserve a free slot for our new object */
        uint16_t free_slot_id;
        struct slot_header slot_hdr;
        if (logfs_reserve_free_slot (logfs, &free_slot_id, &slot_hdr, obj_id, obj_inst_id, obj_size) != 0) {
                /* Failed to reserve a free slot */
                return -1;
        }

        /* Compute slot address */
        uintptr_t slot_addr = logfs_get_addr (logfs, logfs->active_arena_id, free_slot_id);

        /* Write the data into the reserved slot, starting after the slot header */
        if (obj_size > 0) {
                uintptr_t slot_offset = sizeof(slot_hdr);

                if (PIOS_FLASH_write_data(logfs->partition_id,
                                                slot_addr + slot_offset,
                                                obj_data,
                                                obj_size) != 0) {
                        /* Failed to write the object data to the slot */
                        return -2;
                }
        }

        /* Mark this slot active in one atomic step */
        slot_hdr.state = SLOT_STATE_ACTIVE;
        if (PIOS_FLASH_write_data(logfs->partition_id,
                                        slot_addr,
                                        (uint8_t *)&slot_hdr,
                                        sizeof(slot_hdr)) != 0) {
                /* Failed to mark the slot active */
                return -4;
        }

        /* Object has been successfully written to the slot */
        logfs->num_active_slots++;
        return 0;
}


/**********************************
 *
 * Provide a PIOS_FLASHFS_* driver
 *
 *********************************/
#include "pios_flashfs.h"       /* API for flash filesystem */

int32_t PIOS_FLASHFS_ObjSave(uintptr_t fs_id, uint32_t obj_id, uint16_t obj_inst_id, uint8_t *obj_data, uint16_t obj_size)
{
        int8_t rc;

        struct logfs_state *logfs = (struct logfs_state *)fs_id;

        if (!PIOS_FLASHFS_Logfs_validate(logfs)) {
                rc = -1;
                goto out_exit;
        }

        PIOS_Assert(obj_size <= (logfs->cfg->slot_size - sizeof(struct slot_header)));

        if (PIOS_FLASH_start_transaction(logfs->partition_id) != 0) {
                rc = -2;
                goto out_exit;
        }

        if (logfs_delete_object (logfs, obj_id, obj_inst_id) != 0) {
                rc = -3;
                goto out_end_trans;
        }

        /*
         * All old versions of this object + instance have been invalidated.
         * Write the new object.
         */

        /* Check if the arena is entirely full. */
        if (logfs_fs_is_full(logfs)) {
                /* Note: Filesystem Full means we're full of *active* records so gc won't help at all. */
                rc = -4;
                goto out_end_trans;
        }

        /* Is garbage collection required? */
        if (logfs_log_is_full(logfs)) {
                /* Note: Log Full means the log is full but may contain obsolete slots so gc may free some space */
                if (logfs_garbage_collect(logfs) != 0) {
                        rc = -5;
                        goto out_end_trans;
                }
                /* Check one more time just to be sure we actually free'd some space */
                if (logfs_log_is_full(logfs)) {
                        /*
                         * Log is still full even after gc!
                         * NOTE: This should not happen since the filesystem wasn't full
                         *       when we checked above so gc should have helped.
                         */
                        PIOS_DEBUG_Assert(0);
                        rc = -6;
                        goto out_end_trans;
                }
        }

        /* We have room for our new object.  Append it to the log. */
        if (logfs_append_to_log(logfs, obj_id, obj_inst_id, obj_data, obj_size) != 0) {
                /* Error during append */
                rc = -7;
                goto out_end_trans;
        }

        /* Object successfully written to the log */
        rc = 0;

out_end_trans:
        PIOS_FLASH_end_transaction(logfs->partition_id);

out_exit:
        return rc;
}

int32_t PIOS_FLASHFS_ObjLoad(uintptr_t fs_id, uint32_t obj_id, uint16_t obj_inst_id, uint8_t *obj_data, uint16_t obj_size)
{
        int8_t rc;

        struct logfs_state *logfs = (struct logfs_state *)fs_id;

        if (!PIOS_FLASHFS_Logfs_validate(logfs)) {
                rc = -1;
                goto out_exit;
        }

        PIOS_Assert(obj_size <= (logfs->cfg->slot_size - sizeof(struct slot_header)));

        if (PIOS_FLASH_start_transaction(logfs->partition_id) != 0) {
                rc = -2;
                goto out_exit;
        }

        /* Find the object in the log */
        uint16_t slot_id = 0;
        struct slot_header slot_hdr;
        if (logfs_object_find_next (logfs, &slot_hdr, &slot_id, obj_id, obj_inst_id) != 0) {
                /* Object does not exist in fs */
                rc = -3;
                goto out_end_trans;
        }

        /* Sanity check what we've found */
        if (slot_hdr.obj_size != obj_size) {
                /* Object sizes don't match.  Not safe to copy contents. */
                rc = -4;
                goto out_end_trans;
        }

        /* Read the contents of the object from the log */
        if (obj_size > 0) {
                uintptr_t slot_addr = logfs_get_addr (logfs, logfs->active_arena_id, slot_id);
                if (PIOS_FLASH_read_data(logfs->partition_id,
                                                slot_addr + sizeof(slot_hdr),
                                                (uint8_t *)obj_data,
                                                obj_size) != 0) {
                        /* Failed to read object data from the log */
                        rc = -5;
                        goto out_end_trans;
                }
        }

        /* Object successfully loaded */
        rc = 0;

out_end_trans:
        PIOS_FLASH_end_transaction(logfs->partition_id);

out_exit:
        return rc;
}

int32_t PIOS_FLASHFS_ObjDelete(uintptr_t fs_id, uint32_t obj_id, uint16_t obj_inst_id)
{
        int8_t rc;

        struct logfs_state *logfs = (struct logfs_state *)fs_id;

        if (!PIOS_FLASHFS_Logfs_validate(logfs)) {
                rc = -1;
                goto out_exit;
        }

        if (PIOS_FLASH_start_transaction(logfs->partition_id) != 0) {
                rc = -2;
                goto out_exit;
        }

        if (logfs_delete_object (logfs, obj_id, obj_inst_id) != 0) {
                rc = -3;
                goto out_end_trans;
        }

        /* Object successfully deleted from the log */
        rc = 0;

out_end_trans:
        PIOS_FLASH_end_transaction(logfs->partition_id);

out_exit:
        return rc;
}

int32_t PIOS_FLASHFS_Format(uintptr_t fs_id)
{
        int32_t rc;

        struct logfs_state *logfs = (struct logfs_state *)fs_id;

        if (!PIOS_FLASHFS_Logfs_validate(logfs)) {
                rc = -1;
                goto out_exit;
        }

        if (logfs->mounted) {
                logfs_unmount_log(logfs);
        }

        if (PIOS_FLASH_start_transaction(logfs->partition_id) != 0) {
                rc = -2;
                goto out_exit;
        }

        if (logfs_erase_all_arenas(logfs) != 0) {
                rc = -3;
                goto out_end_trans;
        }

        /* Reinitialize arena 0 */
        if (logfs_activate_arena(logfs, 0) != 0) {
                rc = -4;
                goto out_end_trans;
        }

        /* Mount arena 0 */
        if (logfs_mount_log(logfs, 0) != 0) {
                rc = -5;
                goto out_end_trans;
        }

        /* Chip erased and log remounted successfully */
        rc = 0;

out_end_trans:
        PIOS_FLASH_end_transaction(logfs->partition_id);

out_exit:
        return rc;
}