/* Copyright (C) 2005,2006      David Decotigny
 
    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 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., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
    USA.
 */
 #ifndef _SOS_BLKCACHE_H_
 #define _SOS_BLKCACHE_H_
 
 
 /**
  * @file blkcache.h
  *
  * Simple block cache interface. This implementation is based on a
  * fixed-size block cache, the size being set at construction time.
  */
 #include <sos/errno.h>
 #include <sos/blkdev.h>
 
 
 /** Opaque structure holding a cache */
 struct sos_block_cache;
 
 /** Opaque structure holding a cache entry (used as a cookie from
     blkcache_retrieve to blkcache_release) */
 struct sos_block_cache_entry;
 
 
 sos_ret_t sos_blkcache_subsystem_setup(void);
 
 
 /** Create a new block cache */
 struct sos_block_cache *
 sos_blkcache_new_cache(void * blockdev_instance_custom_data,
                        sos_size_t  block_size,
                        sos_count_t cache_size_in_blocks,
                        struct sos_blockdev_operations * blockdev_ops);
 
 
 /** Delete a block cache */
 sos_ret_t
 sos_blkcache_delete_cache(struct sos_block_cache * bc);
 
 
 /**
  * "Write-only" cached blocks are expected to be *completely*
  * overwritten by the blkdev code
  */
 typedef enum { SOS_BLKCACHE_READ_ONLY  = 0x4242,
                SOS_BLKCACHE_READ_WRITE = 0x2442,
                SOS_BLKCACHE_WRITE_ONLY = 0x4224 } sos_blkcache_access_type_t;
 
 
 /**
  * Retrieve a block from the cache
  *  @param block_contents is filled with the address of the kernel
  *    buffer holding the data
  *  @return opaque structure used by release_block, or NULL when the
  *    block could not be retrieved from disk
  *
  * @note once used and/or modified, the block must be released.
  */
 struct sos_block_cache_entry *
 sos_blkcache_retrieve_block(struct sos_block_cache * bc,
                             sos_luoffset_t block_index,
                             sos_blkcache_access_type_t access_type,
                             sos_vaddr_t */*out*/ block_contents);
 
 
 /**
  * Unreference a block previously retrieved. If is_dirty is TRUE, the
  * block MUST have been retrieved with the "read_write" or
  * "write_only" access type.
  */
 sos_ret_t
 sos_blkcache_release_block(struct sos_block_cache * bc,
                            struct sos_block_cache_entry * entry,
                            sos_bool_t is_dirty,
                            sos_bool_t force_flush);
 
 
 /** Flush any modified blocks to disk */
 sos_ret_t
 sos_blkcache_flush(struct sos_block_cache * bc);
 
 #endif