FreeRTOS-Plus/Source/Reliance-Edge/fse/fse.c

/*             ----> DO NOT REMOVE THE FOLLOWING NOTICE <----

                   Copyright (c) 2014-2015 Datalight, Inc.
                       All Rights Reserved Worldwide.

    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; use version 2 of the License.

    This program is distributed in the hope that it will be useful,
    but "AS-IS," 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 Street, Fifth Floor, Boston, MA 02110-1301 USA.
*/
/*  Businesses and individuals that for commercial or other reasons cannot
    comply with the terms of the GPLv2 license may obtain a commercial license
    before incorporating Reliance Edge into proprietary software for
    distribution in any form.  Visit http://www.datalight.com/reliance-edge for
    more information.
*/
/** @file
    @brief Implementation of the Reliance Edge FSE API.
*/
#include <redfs.h>

#if REDCONF_API_FSE == 1

/** @defgroup red_group_fse The File System Essentials Interface
    @{
*/

#include <redvolume.h>
#include <redcoreapi.h>
#include <redfse.h>


static REDSTATUS FseEnter(uint8_t bVolNum);
static void FseLeave(void);


static bool gfFseInited;    /* Whether driver is initialized. */


/** @brief Initialize the Reliance Edge file system driver.

    Prepares the Reliance Edge file system driver to be used.  Must be the first
    Reliance Edge function to be invoked: no volumes can be mounted until the
    driver has been initialized.

    If this function is called when the Reliance Edge driver is already
    initialized, it does nothing and returns success.

    This function is not thread safe: attempting to initialize from multiple
    threads could leave things in a bad state.

    @return A negated ::REDSTATUS code indicating the operation result.

    @retval 0   Operation was successful.
*/
REDSTATUS RedFseInit(void)
{
    REDSTATUS ret;

    if(gfFseInited)
    {
        ret = 0;
    }
    else
    {
        ret = RedCoreInit();

        if(ret == 0)
        {
            gfFseInited = true;
        }
    }

    return ret;
}


/** @brief Uninitialize the Reliance Edge file system driver.

    Tears down the Reliance Edge file system driver.  Cannot be used until all
    Reliance Edge volumes are unmounted.  A subsequent call to RedFseInit()
    will initialize the driver again.

    If this function is called when the Reliance Edge driver is already
    uninitialized, it does nothing and returns success.

    This function is not thread safe: attempting to uninitialize from multiple
    threads could leave things in a bad state.

    @return A negated ::REDSTATUS code indicating the operation result.

    @retval 0           Operation was successful.
    @retval -RED_EBUSY  At least one volume is still mounted.
*/
REDSTATUS RedFseUninit(void)
{
    REDSTATUS ret = 0;

    if(!gfFseInited)
    {
        ret = 0;
    }
    else
    {
        uint8_t bVolNum;

      #if REDCONF_TASK_COUNT > 1U
        RedOsMutexAcquire();
      #endif

        for(bVolNum = 0U; bVolNum < REDCONF_VOLUME_COUNT; bVolNum++)
        {
            if(gaRedVolume[bVolNum].fMounted)
            {
                ret = -RED_EBUSY;
                break;
            }
        }

        if(ret == 0)
        {
            gfFseInited = false;
        }

      #if REDCONF_TASK_COUNT > 1U
        RedOsMutexRelease();
      #endif

        if(ret == 0)
        {
            ret = RedCoreUninit();
        }
    }

    return ret;
}


/** @brief Mount a file system volume.

    Prepares the file system volume to be accessed.  Mount will fail if the
    volume has never been formatted, or if the on-disk format is inconsistent
    with the compile-time configuration.

    If the volume is already mounted, this function does nothing and returns
    success.

    @param bVolNum  The volume number of the volume to be mounted.

    @return A negated ::REDSTATUS code indicating the operation result.

    @retval 0           Operation was successful.
    @retval -RED_EINVAL @p bVolNum is an invalid volume number; or the driver is
                        uninitialized.
    @retval -RED_EIO    Volume not formatted, improperly formatted, or corrupt.
*/
REDSTATUS RedFseMount(
    uint8_t     bVolNum)
{
    REDSTATUS   ret;

    ret = FseEnter(bVolNum);

    if(ret == 0)
    {
        if(!gpRedVolume->fMounted)
        {
            ret = RedCoreVolMount();
        }

        FseLeave();
    }

    return ret;
}


/** @brief Unmount a file system volume.

    This function discards the in-memory state for the file system and marks it
    as unmounted.  Subsequent attempts to access the volume will fail until the
    volume is mounted again.

    If unmount automatic transaction points are enabled, this function will
    commit a transaction point prior to unmounting.  If unmount automatic
    transaction points are disabled, this function will unmount without
    transacting, effectively discarding the working state.

    Before unmounting, this function will wait for any active file system
    thread to complete by acquiring the FS mutex.  The volume will be marked as
    unmounted before the FS mutex is released, so subsequent FS threads will
    possibly block and then see an error when attempting to access a volume
    which is unmounting or unmounted.

    If the volume is already unmounted, this function does nothing and returns
    success.

    @param bVolNum  The volume number of the volume to be unmounted.

    @return A negated ::REDSTATUS code indicating the operation result.

    @retval 0           Operation was successful.
    @retval -RED_EINVAL @p bVolNum is an invalid volume number; or the driver is
                        uninitialized.
    @retval -RED_EIO    I/O error during unmount automatic transaction point.
*/
REDSTATUS RedFseUnmount(
    uint8_t     bVolNum)
{
    REDSTATUS   ret;

    ret = FseEnter(bVolNum);

    if(ret == 0)
    {
        if(gpRedVolume->fMounted)
        {
            ret = RedCoreVolUnmount();
        }

        FseLeave();
    }

    return ret;
}


#if (REDCONF_READ_ONLY == 0) && (REDCONF_API_FSE_FORMAT == 1)
/** @brief Format a file system volume.

    Uses the statically defined volume configuration.  After calling this
    function, the volume needs to be mounted -- see RedFseMount().

    An error is returned if the volume is mounted.

    @param bVolNum  The volume number of the volume to be formatted.

    @return A negated ::REDSTATUS code indicating the operation result.

    @retval 0           Operation was successful.
    @retval -RED_EBUSY  The volume is mounted.
    @retval -RED_EINVAL @p bVolNum is an invalid volume number; or the driver is
                        uninitialized.
    @retval -RED_EIO    I/O error formatting the volume.
*/
REDSTATUS RedFseFormat(
    uint8_t     bVolNum)
{
    REDSTATUS   ret;

    ret = FseEnter(bVolNum);

    if(ret == 0)
    {
        ret = RedCoreVolFormat();

        FseLeave();
    }

    return ret;
}
#endif


/** @brief Read from a file.

    Data which has not yet been written, but which is before the end-of-file
    (sparse data), shall read as zeroes.  A short read -- where the number of
    bytes read is less than requested -- indicates that the requested read was
    partially or, if zero bytes were read, entirely beyond the end-of-file.

    If @p ullFileOffset is at or beyond the maximum file size, it is treated
    like any other read entirely beyond the end-of-file: no data is read and
    zero is returned.

    @param bVolNum          The volume number of the file to read.
    @param ulFileNum        The file number of the file to read.
    @param ullFileOffset    The file offset to read from.
    @param ulLength         The number of bytes to read.
    @param pBuffer          The buffer to populate with the data read.  Must be
                            at least ulLength bytes in size.

    @return The number of bytes read (nonnegative) or a negated ::REDSTATUS
            code indicating the operation result (negative).

    @retval >=0         The number of bytes read from the file.
    @retval -RED_EBADF  @p ulFileNum is not a valid file number.
    @retval -RED_EINVAL @p bVolNum is an invalid volume number or not mounted;
                        or @p pBuffer is `NULL`; or @p ulLength exceeds
                        INT32_MAX and cannot be returned properly.
    @retval -RED_EIO    A disk I/O error occurred.
*/
int32_t RedFseRead(
    uint8_t     bVolNum,
    uint32_t    ulFileNum,
    uint64_t    ullFileOffset,
    uint32_t    ulLength,
    void       *pBuffer)
{
    int32_t     ret;

    if(ulLength > (uint32_t)INT32_MAX)
    {
        ret = -RED_EINVAL;
    }
    else
    {
        ret = FseEnter(bVolNum);
    }

    if(ret == 0)
    {
        uint32_t ulReadLen = ulLength;

        ret = RedCoreFileRead(ulFileNum, ullFileOffset, &ulReadLen, pBuffer);

        FseLeave();

        if(ret == 0)
        {
            ret = (int32_t)ulReadLen;
        }
    }

    return ret;
}


#if REDCONF_READ_ONLY == 0
/** @brief Write to a file.

    If the write extends beyond the end-of-file, the file size will be
    increased.

    A short write -- where the number of bytes written is less than requested
    -- indicates either that the file system ran out of space but was still
    able to write some of the request; or that the request would have caused
    the file to exceed the maximum file size, but some of the data could be
    written prior to the file size limit.

    If an error is returned (negative return), either none of the data was
    written or a critical error occurred (like an I/O error) and the file
    system volume will be read-only.

    @param bVolNum          The volume number of the file to write.
    @param ulFileNum        The file number of the file to write.
    @param ullFileOffset    The file offset to write at.
    @param ulLength         The number of bytes to write.
    @param pBuffer          The buffer containing the data to be written.  Must
                            be at least ulLength bytes in size.

    @return The number of bytes written (nonnegative) or a negated ::REDSTATUS
            code indicating the operation result (negative).

    @retval >0          The number of bytes written to the file.
    @retval -RED_EBADF  @p ulFileNum is not a valid file number.
    @retval -RED_EFBIG  No data can be written to the given file offset since
                        the resulting file size would exceed the maximum file
                        size.
    @retval -RED_EINVAL @p bVolNum is an invalid volume number or not mounted;
                        or @p pBuffer is `NULL`; or @p ulLength exceeds
                        INT32_MAX and cannot be returned properly.
    @retval -RED_EIO    A disk I/O error occurred.
    @retval -RED_ENOSPC No data can be written because there is insufficient
                        free space.
    @retval -RED_EROFS  The file system volume is read-only.
*/
int32_t RedFseWrite(
    uint8_t     bVolNum,
    uint32_t    ulFileNum,
    uint64_t    ullFileOffset,
    uint32_t    ulLength,
    const void *pBuffer)
{
    int32_t     ret;

    if(ulLength > (uint32_t)INT32_MAX)
    {
        ret = -RED_EINVAL;
    }
    else
    {
        ret = FseEnter(bVolNum);
    }

    if(ret == 0)
    {
        uint32_t ulWriteLen = ulLength;

        ret = RedCoreFileWrite(ulFileNum, ullFileOffset, &ulWriteLen, pBuffer);

        FseLeave();

        if(ret == 0)
        {
            ret = (int32_t)ulWriteLen;
        }
    }

    return ret;
}
#endif


#if (REDCONF_READ_ONLY == 0) && (REDCONF_API_FSE_TRUNCATE == 1)
/** @brief Truncate a file (set the file size).

    Allows the file size to be increased, decreased, or to remain the same.  If
    the file size is increased, the new area is sparse (will read as zeroes).
    If the file size is decreased, the data beyond the new end-of-file will
    return to free space once it is no longer part of the committed state
    (either immediately or after the next transaction point).

    This function can fail when the disk is full if @p ullNewFileSize is
    non-zero.  If decreasing the file size, this can be fixed by transacting and
    trying again: Reliance Edge guarantees that it is possible to perform a
    truncate of at least one file that decreases the file size after a
    transaction point.  If disk full transactions are enabled, this will happen
    automatically.

    @param bVolNum          The volume number of the file to truncate.
    @param ulFileNum        The file number of the file to truncate.
    @param ullNewFileSize   The new file size, in bytes.

    @return A negated ::REDSTATUS code indicating the operation result.

    @retval 0           Operation was successful.
    @retval -RED_EBADF  @p ulFileNum is not a valid file number.
    @retval -RED_EFBIG  @p ullNewFileSize exceeds the maximum file size.
    @retval -RED_EINVAL @p bVolNum is an invalid volume number or not mounted.
    @retval -RED_EIO    A disk I/O error occurred.
    @retval -RED_ENOSPC Insufficient free space to perform the truncate.
    @retval -RED_EROFS  The file system volume is read-only.
*/
REDSTATUS RedFseTruncate(
    uint8_t     bVolNum,
    uint32_t    ulFileNum,
    uint64_t    ullNewFileSize)
{
    REDSTATUS   ret;

    ret = FseEnter(bVolNum);

    if(ret == 0)
    {
        ret = RedCoreFileTruncate(ulFileNum, ullNewFileSize);

        FseLeave();
    }

    return ret;
}
#endif


/** @brief Retrieve the size of a file.

    @param bVolNum      The volume number of the file whose size is being read.
    @param ulFileNum    The file number of the file whose size is being read.

    @return The size of the file (nonnegative) or a negated ::REDSTATUS code
            indicating the operation result (negative).

    @retval >=0         The size of the file.
    @retval -RED_EBADF  @p ulFileNum is not a valid file number.
    @retval -RED_EINVAL @p bVolNum is an invalid volume number or not mounted.
    @retval -RED_EIO    A disk I/O error occurred.
*/
int64_t RedFseSizeGet(
    uint8_t     bVolNum,
    uint32_t    ulFileNum)
{
    int64_t     ret;

    ret = FseEnter(bVolNum);

    if(ret == 0)
    {
        uint64_t ullSize;

        ret = RedCoreFileSizeGet(ulFileNum, &ullSize);

        FseLeave();

        if(ret == 0)
        {
            /*  Unless there is an on-disk format change, the maximum file size
                is guaranteed to be less than INT64_MAX, and so it can be safely
                returned in an int64_t.
            */
            REDASSERT(ullSize < (uint64_t)INT64_MAX);

            ret = (int64_t)ullSize;
        }
    }

    return ret;
}


#if (REDCONF_READ_ONLY == 0) && (REDCONF_API_FSE_TRANSMASKSET == 1)
/** @brief Update the transaction mask.

    The following events are available:

    - #RED_TRANSACT_UMOUNT
    - #RED_TRANSACT_WRITE
    - #RED_TRANSACT_TRUNCATE
    - #RED_TRANSACT_VOLFULL

    The #RED_TRANSACT_MANUAL macro (by itself) may be used to disable all
    automatic transaction events.  The #RED_TRANSACT_MASK macro is a bitmask of
    all transaction flags, excluding those representing excluded functionality.

    Attempting to enable events for excluded functionality will result in an
    error.

    @param bVolNum      The volume number of the volume whose transaction mask
                        is being changed.
    @param ulEventMask  A bitwise-OR'd mask of automatic transaction events to
                        be set as the current transaction mode.

    @return A negated ::REDSTATUS code indicating the operation result.

    @retval 0           Operation was successful.
    @retval -RED_EINVAL @p bVolNum is an invalid volume number or not mounted;
                        or @p ulEventMask contains invalid bits.
    @retval -RED_EROFS  The file system volume is read-only.
*/
REDSTATUS RedFseTransMaskSet(
    uint8_t     bVolNum,
    uint32_t    ulEventMask)
{
    REDSTATUS   ret;

    ret = FseEnter(bVolNum);

    if(ret == 0)
    {
        ret = RedCoreTransMaskSet(ulEventMask);

        FseLeave();
    }

    return ret;
}
#endif


#if REDCONF_API_FSE_TRANSMASKGET == 1
/** @brief Read the transaction mask.

    If the volume is read-only, the returned event mask is always zero.

    @param bVolNum      The volume number of the volume whose transaction mask
                        is being retrieved.
    @param pulEventMask Populated with a bitwise-OR'd mask of automatic
                        transaction events which represent the current
                        transaction mode for the volume.

    @return A negated ::REDSTATUS code indicating the operation result.

    @retval 0           Operation was successful.
    @retval -RED_EINVAL @p bVolNum is an invalid volume number or not mounted;
                        or @p pulEventMask is `NULL`.
*/
REDSTATUS RedFseTransMaskGet(
    uint8_t     bVolNum,
    uint32_t   *pulEventMask)
{
    REDSTATUS   ret;

    ret = FseEnter(bVolNum);

    if(ret == 0)
    {
        ret = RedCoreTransMaskGet(pulEventMask);

        FseLeave();
    }

    return ret;
}
#endif


#if REDCONF_READ_ONLY == 0
/** @brief Commit a transaction point.

    Reliance Edge is a transactional file system.  All modifications, of both
    metadata and filedata, are initially working state.  A transaction point
    is a process whereby the working state atomically becomes the committed
    state, replacing the previous committed state.  Whenever Reliance Edge is
    mounted, including after power loss, the state of the file system after
    mount is the most recent committed state.  Nothing from the committed
    state is ever missing, and nothing from the working state is ever included.

    @param bVolNum  The volume number of the volume to transact.

    @return A negated ::REDSTATUS code indicating the operation result.

    @retval 0           Operation was successful.
    @retval -RED_EINVAL @p bVolNum is an invalid volume number or not mounted.
    @retval -RED_EIO    A disk I/O error occurred.
    @retval -RED_EROFS  The file system volume is read-only.
*/
REDSTATUS RedFseTransact(
    uint8_t     bVolNum)
{
    REDSTATUS   ret;

    ret = FseEnter(bVolNum);

    if(ret == 0)
    {
        ret = RedCoreVolTransact();

        FseLeave();
    }

    return ret;
}
#endif

/** @} */

/** @brief Enter the file system driver.

    @param bVolNum  The volume to be accessed.

    @return A negated ::REDSTATUS code indicating the operation result.

    @retval 0           Operation was successful.
    @retval -RED_EINVAL The file system driver is uninitialized; or @p bVolNum
                        is not a valid volume number.
*/
static REDSTATUS FseEnter(
    uint8_t   bVolNum)
{
    REDSTATUS ret;

    if(gfFseInited)
    {
      #if REDCONF_TASK_COUNT > 1U
        RedOsMutexAcquire();
      #endif

        /*  This also serves to range-check the volume number (even in single
            volume configurations).
        */
        ret = RedCoreVolSetCurrent(bVolNum);

      #if REDCONF_TASK_COUNT > 1U
        if(ret != 0)
        {
            RedOsMutexRelease();
        }
      #endif
    }
    else
    {
        ret = -RED_EINVAL;
    }

    return ret;
}


/** @brief Leave the file system driver.
*/
static void FseLeave(void)
{
    REDASSERT(gfFseInited);

  #if REDCONF_TASK_COUNT > 1U
    RedOsMutexRelease();
  #endif
}


#endif /* REDCONF_API_FSE == 1 */