/**
* @file
*
* @brief RTEMS File Systems Block Management
*
* @ingroup rtems_rfs
*
* RTEMS File Systems Block Management.
*
* These functions manage the blocks used in the file system.
*/
/*
* COPYRIGHT (c) 2010 Chris Johns <chrisj@rtems.org>
*
* The license and distribution terms for this file may be
* found in the file LICENSE in this distribution or at
* http://www.rtems.org/license/LICENSE.
*/
#if !defined (_RTEMS_RFS_BLOCK_H_)
#define _RTEMS_RFS_BLOCK_H_
#include <rtems/rfs/rtems-rfs-block-pos.h>
#include <rtems/rfs/rtems-rfs-buffer.h>
#include <rtems/rfs/rtems-rfs-data.h>
#include <rtems/rfs/rtems-rfs-file-system.h>
/**
* Get a block number in the media format and return it in the host format.
*
* @param[in] _h is the buffer handle of the block.
* @param[in] _b is the block number index.
*
* @retval block The block number.
*/
#define rtems_rfs_block_get_number(_h, _b) \
((rtems_rfs_block_no) \
(rtems_rfs_read_u32 (rtems_rfs_buffer_data (_h) + \
((_b) * sizeof (rtems_rfs_block_no)))))
/**
* Set a block number in the media format given a number in the host format.
*
* @param[in] _h is the buffer handle of the block.
* @param[in] _b is the block number index, ie the number of block number not the
* buffer offset.
* @param[in] _n is the block number.
*/
#define rtems_rfs_block_set_number(_h, _b, _n) \
do { \
rtems_rfs_write_u32 (rtems_rfs_buffer_data (_h) + \
((_b) * sizeof (rtems_rfs_block_no)), (_n)); \
rtems_rfs_buffer_mark_dirty (_h); \
} while (0)
/**
* A block map manges the block lists that originate from an inode. The inode
* contains a number of block numbers. A block map takes those block numbers
* and manages them.
*
* The blocks cannot have all ones as a block number nor block 0. The block map
* is series of block numbers in a blocks. The size of the map determines the
* way the block numbers are stored. The map uses the following:
*
* @li @e Direct Access,
* @li @e Single Indirect Access, and
* @li @e Double Indirect Access.
*
* Direct access has the blocks numbers in the inode slots. The Single Indirect
* Access has block numbers in the inode slots that pointer to a table of block
* numbers that point to data blocks. The Double Indirect Access has block
* numbers in the inode that point to Single Indirect block tables.
*
* The inode can hold a number of Direct, Single Indirect, and Double Indirect
* block tables. The move from Direct to Single occurs then the block count in
* the map is above the number of slots in the inode. The move from Single to
* Double occurs when the map block count is greated than the block numbers per
* block multipled by the slots in the inode. The move from Single to Double
* occurs when the map block count is over the block numbers per block squared
* multipled by the number of slots in the inode.
*
* The block map can managed files of the follow size verses block size with 5
* inode slots:
*
* @li 41,943,040 bytes for a 512 byte block size,
* @li 335,544,320 bytes for a 1024 byte block size,
* @li 2,684,354,560 bytes for a 2048 byte block size, and
* @li 21,474,836,480 bytes for a 4096 byte block size.
*/
typedef struct rtems_rfs_block_map_s
{
/**
* Is the map dirty ?
*/
bool dirty;
/**
* The inode this map is attached to.
*/
rtems_rfs_inode_handle* inode;
/**
* The size of the map.
*/
rtems_rfs_block_size size;
/**
* The block map position. Used to navigate the map when seeking. The find
* call is to a position in the file/directory and is a block number plus
* offset. The block find only needs to locate a block and not worry about
* the offset while a seek can be less than a block size yet move across a
* block boundary. Therefore the position a block map has to maintain must
* include the offset so seeks work.
*/
rtems_rfs_block_pos bpos;
/**
* The last map block allocated. This is used as the goal when allocating a
* new map block.
*/
rtems_rfs_block_no last_map_block;
/**
* The last data block allocated. This is used as the goal when allocating a
* new data block.
*/
rtems_rfs_block_no last_data_block;
/**
* The block map.
*/
uint32_t blocks[RTEMS_RFS_INODE_BLOCKS];
/**
* Singly Buffer handle.
*/
rtems_rfs_buffer_handle singly_buffer;
/**
* Doubly Buffer handle.
*/
rtems_rfs_buffer_handle doubly_buffer;
} rtems_rfs_block_map;
/**
* Is the map dirty ?
*/
#define rtems_rfs_block_map_is_dirty(_m) ((_m)->dirty)
/**
* Return the block count in the map.
*/
#define rtems_rfs_block_map_count(_m) ((_m)->size.count)
/**
* Return the map's size element.
*/
#define rtems_rfs_block_map_size(_m) (&((_m)->size))
/**
* Return the size offset for the map.
*/
#define rtems_rfs_block_map_size_offset(_m) ((_m)->size.offset)
/**
* Are we at the last block in the map ?
*/
#define rtems_rfs_block_map_last(_m) \
rtems_rfs_block_pos_last_block (&(_m)->bpos, &(_m)->size)
/**
* Is the position past the end of the block ?
*/
#define rtems_rfs_block_map_past_end(_m, _p) \
rtems_rfs_block_pos_past_end (_p, &(_m)->size)
/**
* Return the current position in the map.
*/
#define rtems_rfs_block_map_pos(_f, _m) \
rtems_rfs_block_get_pos (_f, &(_m)->bpos)
/**
* Return the map's current block number.
*/
#define rtems_rfs_block_map_block(_m) ((_m)->bpos.bno)
/**
* Return the map's current block offset.
*/
#define rtems_rfs_block_map_block_offset(_m) ((_m)->bpos.boff)
/**
* Set the size offset for the map. The map is tagged as dirty.
*
* @param[in] map is a pointer to the open map to set the offset in.
* @param[in] offset is the offset to set in the map's size.
*/
static inline void
rtems_rfs_block_map_set_size_offset (rtems_rfs_block_map* map,
rtems_rfs_block_off offset)
{
map->size.offset = offset;
map->dirty = true;
}
/**
* Set the map's size. The map is tagged as dirty.
*
* @param[in] map is a pointer to the open map to set the offset in.
* @param[in] size is the size to set in the map's size.
*/
static inline void
rtems_rfs_block_map_set_size (rtems_rfs_block_map* map,
rtems_rfs_block_size* size)
{
rtems_rfs_block_copy_size (&map->size, size);
map->dirty = true;
}
/**
* Open a block map. The block map data in the inode is copied into the
* map. The buffer handles are opened. The block position is set to the start
* so a seek of offset 0 will return the first block.
*
* @param[in] fs is the file system data.
* @param[in] inode is a pointer to the inode the map belongs to.
* @param[in] map is a pointer to the map that is opened.
*
* @retval 0 Successful operation.
* @retval error_code An error occurred.
*/
int rtems_rfs_block_map_open (rtems_rfs_file_system* fs,
rtems_rfs_inode_handle* inode,
rtems_rfs_block_map* map);
/**
* Close the map. The buffer handles are closed and any help buffers are
* released.
*
* @param[in] fs is the file system data.
* @param[in] map is a pointer to the map that is opened.
*
* @retval 0 Successful operation.
* @retval error_code An error occurred.
*/
int rtems_rfs_block_map_close (rtems_rfs_file_system* fs,
rtems_rfs_block_map* map);
/**
* Find a block number in the map from the position provided.
*
* @param[in] fs is the file system data.
* @param[in] map is a pointer to the map to search.
* @param[in] bpos is a pointer to the block position to find.
* @param[out] block will contain the block in when found.
*
* @retval 0 Successful operation.
* @retval error_code An error occurred.
*/
int rtems_rfs_block_map_find (rtems_rfs_file_system* fs,
rtems_rfs_block_map* map,
rtems_rfs_block_pos* bpos,
rtems_rfs_buffer_block* block);
/**
* Seek around the map.
*
* @param[in] fs is the file system data.
* @param[in] map is a pointer to the map to search.
* @param[in] offset is the distance to seek. It is signed.
* @param[out] block will contain the block in when found.
*
* @retval 0 Successful operation.
* @retval ENXIO Failed to seek because it is outside the block map.
* @retval error_code An error occurred.
*/
int rtems_rfs_block_map_seek (rtems_rfs_file_system* fs,
rtems_rfs_block_map* map,
rtems_rfs_pos_rel offset,
rtems_rfs_buffer_block* block);
/**
* Seek to the next block.
*
* @param[in] fs is the file system data.
* @param[in] map is a pointer to the map to search.
* @param[out] block will contain the block in when found.
*
* @retval 0 Successful operation.
* @retval ENXIO Failed to seek because it is outside the block map.
* @retval error_code An error occurred.
*/
int rtems_rfs_block_map_next_block (rtems_rfs_file_system* fs,
rtems_rfs_block_map* map,
rtems_rfs_buffer_block* block);
/**
* Grow the block map by the specified number of blocks.
*
* @param[in] fs is the file system data.
* @param[in] map is a pointer to the open map to grow.
* @param[in] blocks is the number of blocks to grow the map by.
* @param[out] new_block will contain first of the blocks allocated
* to the map.
*
* @retval 0 Successful operation.
* @retval error_code An error occurred.
*/
int rtems_rfs_block_map_grow (rtems_rfs_file_system* fs,
rtems_rfs_block_map* map,
size_t blocks,
rtems_rfs_block_no* new_block);
/**
* Grow the block map by the specified number of blocks.
*
* @param[in] fs is the file system data.
* @param[in] map is a pointer to the open map to shrink.
* @param[in] blocks is the number of blocks to shrink the map by. If more
* than the number of blocks the map is emptied.
*
* @retval 0 Successful operation.
* @retval error_code An error occurred.
*/
int rtems_rfs_block_map_shrink (rtems_rfs_file_system* fs,
rtems_rfs_block_map* map,
size_t blocks);
/**
* Free all blocks in the map.
*
* @param[in] fs is the file system data.
* @param[in] map is a pointer to the open map to free all blocks from.
*
* @retval 0 Successful operation.
* @retval error_code An error occurred.
*/
int rtems_rfs_block_map_free_all (rtems_rfs_file_system* fs,
rtems_rfs_block_map* map);
#endif
