[bertos.git] / bertos / io / kblock.h

/**
 * \file
 * <!--
 * This file is part of BeRTOS.
 *
 * Bertos 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 2 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, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
 *
 * As a special exception, you may use this file as part of a free software
 * library without restriction.  Specifically, if other files instantiate
 * templates or use macros or inline functions from this file, or you compile
 * this file and link it with other files to produce an executable, this
 * file does not by itself cause the resulting executable to be covered by
 * the GNU General Public License.  This exception does not however
 * invalidate any other reasons why the executable file might be covered by
 * the GNU General Public License.
 *
 * Copyright 2009 Develer S.r.l. (http://www.develer.com/)
 *
 * -->
 *
 * \author Francesco Sacchi <batt@develer.com>
 *
 * \brief KBlock interface
 */

#ifndef IO_KBLOCK_H
#define IO_KBLOCK_H

#include <cfg/compiler.h>
#include <cfg/debug.h>

/** Type for addressing blocks in the device. */
typedef uint32_t block_idx_t;

// Fwd Declaration
struct KBlock;

/**
 * \name Prototypes for KBlock access functions.
 * 
 * A KBlock user can choose which function subset to implement,
 * but has to set to NULL unimplemented features.
 * 
 *  \{ 
 */
typedef size_t (* kblock_read_t)    (struct KBlock *b, void *buf, size_t offset, size_t size);
typedef size_t (* kblock_write_t)   (struct KBlock *b, const void *buf, size_t offset, size_t size);
typedef int    (* kblock_load_t)    (struct KBlock *b, block_idx_t index);
typedef int    (* kblock_store_t)   (struct KBlock *b, block_idx_t index);
typedef void * (* kblock_map_t)     (struct KBlock *b, size_t offset, size_t size);
typedef int    (* kblock_unmap_t)   (struct KBlock *b, size_t offset, size_t size);
typedef int    (* kblock_error_t)   (struct KBlock *b);
typedef int    (* kblock_clearerr_t)(struct KBlock *b);
typedef int    (* kblock_close_t)   (struct KBlock *b);
/* \} */

/**
 * Table of interface functions for a KBlock device.
 */
typedef struct KBlockVTable
{
    kblock_read_t  readBuf;  ///< \sa kblock_readBuf()
        kblock_write_t writeBuf; ///< \sa kblock_writeBuf()
        kblock_load_t  load;     ///< \sa kblock_load()
        kblock_store_t store;    ///< \sa kblock_store()

        kblock_map_t   map;   ///< \sa kblock_map()
        kblock_unmap_t unmap; ///< \sa kblock_unmap()
        
        kblock_error_t    error;    ///< \sa kblock_error()
        kblock_clearerr_t clearerr; ///< \sa kblock_clearerr()
        
        kblock_close_t  close; ///< \sa kblock_close()
} KBlockVTable;


/**
 * KBlock status and error codes.
 */
typedef enum KBlockStatus
{
        /* Status flags */
        KBS_MAPPED,  ///< Status: The current loaded block from the device is memory mapped.
        
        /* Errors */
        KBS_ERR_ALREADY_MAPPED,    ///< Error: trying to memory map a block already mapped.
        KBS_ERR_NOT_MAPPED,        ///< Error: trying to memory unmap a block not yet mapped.
        KBS_ERR_MAP_NOT_AVAILABLE, ///< Error: mapping methods not implemented.

        #define KBS_STATUS_MASK (BV(KBS_MAPPER) | 0 /* Add status flags here */)
        
        #define KBS_ERROR_MASK (BV(KBS_ERR_ALREADY_MAPPED) | BV(KBS_ERR_ALREADY_MAPPED) \
                | BV(KBS_ERR_MAP_NOT_AVAILABLE) | 0 /* Add error flags here */)
}  KBlockStatus;


/**
 * KBlock private members.
 * These are the private members of the KBlock class, please do not
 * access these directly, use the KBlock API.
 */ 
typedef struct KBlockPriv
{
        DB(id_t type);         ///< Used to keep track, at runtime, of the class type.
        void *pagebuf;         ///< Pointer to a buffer used as page buffer when memory mapping is active. \sa kblock_map(), kblock_unmap()
        size_t pagebuf_size;   ///< Size of the page buffer used for memory mapping. \sa kblock_map(), kblock_unmap()
        KBlockStatus flags;    ///< Status and error flags.
        block_idx_t blk_start; ///< Start block number when the device is trimmed. \sa kblock_trim()
        DB(size_t map_off);    ///< When mapping is active, this is the mapped data offset inside the block. \sa kblock_map(), kblock_unmap()
        DB(size_t map_size);   ///< When mapping is active, this is the mapped data size inside the block. \sa kblock_map(), kblock_unmap()
} KBlockPriv;

/**
 * KBlock: interface for a generic block device.
 * 
 * A block device is a device which can only be read/written
 * with data blocks of constant size: flash memories,
 * SD cards, hard disks, etc...
 * 
 * This interface is designed to adapt to most block devices and 
 * use peculiar features in order to save CPU time and memory space.
 * 
 * You do not have to use this structure directly, specific implementations
 * will be supplied in the peripheral drivers.
 */
typedef struct KBlock
{
        KBlockPriv priv;         ///< Interface private data, do not use directly.
        
        /* Public access members/methods */
        size_t blk_size;         ///< Block size.
        block_idx_t blk_cnt;     ///< Number of blocks available in the device.
        struct KBlockVTable *vt; ///< Virtual table of interface functions.
} KBlock;


/**
 * Add generic memory mapping functionality to a block device.
 * 
 * If the device has an hardware page buffer mechanism, the map/unmap
 * functions are unimplemented.
 * If you need to use the mapping functions of such device, this function
 * will add generic software mapping features wrapping the KBlock methods.
 * 
 * \param dev the block device.
 * \param buf the buffer to be used as page buffer for memory mapping functions.
 * \param size the size of the buffer. This is the maximum size that can be
 *        memory mapped. If you want to map a full block, a size of at least
 *        dev->blk_size have to be supplied.
 * 
 * \sa kblock_map(), kblock_unmap(), kblock_readBuf(), kblock_writeBuf()
 */
void kblock_addMapping(struct KBlock *dev, void *buf, size_t size);

/**
 * Use a subset of the blocks on the device.
 * 
 * This function is useful for partitioning a device and use it for
 * different purposes at the same time.
 * 
 * This function will limit the number of blocks used on the device by setting
 * a start index and a number of blocks to be used counting from that index.
 * 
 * The blocks outside this range are no more accessible.
 * 
 * Logical block indexes will be mapped to physical indexes inside this new
 * range automatically. Even following calls to kblock_trim() will use logical
 * indexes, so, once trimmed, access can only be limited further and never
 * expanded back.
 * 
 * Example:
 * \code
 * //...init KBlock device dev
 * kblock_trim(dev, 200, 1500); // Restrict access to the 200-1700 physical block range.
 * kblock_load(dev, 0);  // Load the physical block #200.
 * kblock_trim(dev, 0, 300); // Restrict access to the 200-500 physical block range.
 * \endcode
 * 
 * \param b KBlock device.
 * \param start The index of the start block for the limiting window in logical addressing units.
 * \param count The number of blocks to be used.
 * 
 */ 
INLINE void kblock_trim(struct KBlock *b, block_idx_t start, block_idx_t count)
{
        ASSERT(start + count <= b->blk_cnt);
        b->priv.blk_start += start;
        b->blk_cnt = count;
}

/**
 * Transfer data from the internal page buffer to user memory.
 * 
 * This function accesses the internal page buffer of the block device and copy
 * the data to \a buf. The content is copied from the current cached block.
 * 
 * \param b KBlock device.
 * \param buf User buffer to copy the data to.
 * \param offset Address offset within the block, from which to copy data.
 * \param size Size, in bytes, of the data to be copied.
 * 
 * \return The number of bytes copied. Can be less than \a size on errors.
 * 
 * \sa kblock_writeBuf()
 */
INLINE size_t kblock_readBuf(struct KBlock *b, void *buf, size_t offset, size_t size)
{
        ASSERT(b->vt);
        ASSERT(b->vt->readBuf);
        ASSERT(offset + size <= b->blk_size);
        
        return b->vt->readBuf(b, buf, offset, size);
}

/**
 * Write to the page buffer.
 * 
 * Copies data from user memory to the device page buffer. The data is written
 * in the current cached block buffer.
 * 
 * \param b KBlock device.
 * \param buf User buffer to copy the data from.
 * \param offset Address offset within the block, from which data has to be written.
 * \param size Size, in bytes, of the data to be written.
 * 
 * \return The number of bytes written. Can be less than \a size on errors.
 * 
 * \sa kblock_readBuf()
 */
INLINE size_t kblock_writeBuf(struct KBlock *b, const void *buf, size_t offset, size_t size)
{
        ASSERT(b->vt);
        ASSERT(b->vt->writeBuf);
        ASSERT(offset + size <= b->blk_size);
        return b->vt->writeBuf(b, buf, offset, size);
}

/**
 * Load a block from the device to the page buffer.
 * 
 * The block \a index will be loaded in the internal page buffer.
 * 
 * \param b KBlock device.
 * \param index Logical index of the block to be loaded.
 * 
 * \return 0 on success, EOF on errors.
 */
INLINE int kblock_load(struct KBlock *b, block_idx_t index)
{
        ASSERT(b->vt);
        ASSERT(b->vt->load);
        ASSERT(index < b->blk_cnt);
        
        return b->vt->load(b, b->priv.blk_start + index);
}

/**
 * Store a block from the page buffer to the device.
 * 
 * The current content of the page buffer will be flushed to the block \a index.
 * 
 * \param b KBlock device.
 * \param index Logical index of the block to be stored.
 * 
 * \return 0 on success, EOF on errors.
 */
INLINE int kblock_store(struct KBlock *b, block_idx_t index)
{
        ASSERT(b->vt);
        ASSERT(b->vt->store);
        ASSERT(index < b->blk_cnt);
        
        return b->vt->store(b, b->priv.blk_start + index);
}


/**
 * Memory map the current page buffer.
 * 
 * To speed up access, instead of using kblock_readBuf() and kblock_writeBuf(),
 * you can memory map the page buffer and access it directly through the
 * returned pointer. You can freely access the pointer in any way you
 * like. Once done, call kblock_unmap() to release the lock on the page_buffer.
 * 
 * \note This function may be not available on all drivers, since the page
 *       buffer can be in the hardware and not directly accessible through memory.
 *       For this devices you can still add generic software mapping features
 *       thanks to kblock_addMapping().
 * 
 * \note Only one mapping is available at a time, trying to map the page buffer
 *       again before releasing it is an error.
 * 
 * \param b KBlock device.
 * \param offset Address offset within the page buffer, from which data has to 
 *               be memory mapped.
 * \param size Size of the memory to be mapped.
 * 
 * \return A pointer to the mapped region of the page buffer or NULL on errors.
 * 
 * \sa kblock_addMapping(), kblock_unmap()
 */
INLINE void * kblock_map(struct KBlock *b, size_t offset, size_t size)
{
        ASSERT(b->vt);
        ASSERT(b->vt->map);
        
        if (b->priv.flags & BV(KBS_MAPPED))
        {
                b->priv.flags |= BV(KBS_ERR_ALREADY_MAPPED);
                return NULL;
        }
        
        ASSERT(size < b->priv.pagebuf_size);
        ASSERT(offset + size <= b->blk_size);
        DB(b->priv.map_off = offset);
        DB(b->priv.map_size = size);

        void *ret = b->vt->map(b, offset, size);
        
        if (ret)
                b->priv.flags |= BV(KBS_MAPPED);

        return ret;
}


/**
 * Release the memory map on the page buffer.
 * 
 * This function has to be called when memory mapped access has finished.
 * This is needed because only one mapping is allowed at a time.
 * The \a offset and \a size passed should be the same passed to 
 * kblock_map() when the page buffer has been mapped.
 * 
 * \note Trying to unmap the page buffer when there is no mapping ongoing is
 *       an error.
 * 
 * \param b KBlock device.
 * \param offset Address offset within the page buffer, from which data has been
 *               memory mapped. Must be the same value passed to kblock_map()
 *               when the memory was mapped.
 * \param size Size of the memory mapped. Must be the same value passed to
 *             kblock_map() when the memory was mapped.
 * 
 * \return 0 on success, EOF on errors.
 * 
 * \sa kblock_addMapping(), kblock_map()
 */ 
INLINE int kblock_unmap(struct KBlock *b, size_t offset, size_t size)
{
        ASSERT(b->vt);
        ASSERT(b->vt->unmap);
        
        if (!(b->priv.flags & BV(KBS_MAPPED)))
        {
                b->priv.flags |= BV(KBS_ERR_NOT_MAPPED);
                return EOF;
        }
        
        ASSERT(b->priv.map_off == offset);
        ASSERT(b->priv.map_size == size);
        int ret = b->vt->unmap(b, offset, size);
        
        if (ret == 0)
                b->priv.flags &= ~BV(KBS_MAPPED);
        return ret;
}

/**
 * Get the current errors for the device.
 * 
 * \note Calling this function will not clear the errors. 
 * 
 * \param b KBlock device.
 * 
 * \return 0 if no error is present, a driver specific mask of errors otherwise.
 * 
 * \sa kblock_clearerr()
 */
INLINE int kblock_error(struct KBlock *b)
{
        ASSERT(b->vt);
        ASSERT(b->vt->error);
        /* Automatically mask status flags */
        return b->vt->error(b) & ~KBS_STATUS_MASK;
}

/**
 * Clear the errors of the device.
 * 
 * \param b KBlock device.
 * 
 * \return 0 on success, EOF on errors.
 * 
 * \sa kblock_error()
 */
INLINE int kblock_clearerr(struct KBlock *b)
{
        ASSERT(b->vt);
        ASSERT(b->vt->clearerr);
        /* Automatically clear error flags */
        b->priv.flags &= ~KBS_ERROR_MASK;
        return b->vt->clearerr(b);
}

/**
 * Close the device.
 * 
 * \param b KBlock device.
 * 
 * \return 0 on success, EOF on errors.
 */
INLINE int kblock_close(struct KBlock *b)
{
        ASSERT(b->vt);
        ASSERT(b->vt->close);
        return b->vt->close(b);
}

#endif /* IO_KBLOCK_H */