LXR 6.1/​cpukit/​include/​rtems/​rtl/​rtl-obj-cache.h	Source navigation Diff markup Identifier search General search
	Version: 6.1 Revert   Change

File indexing completed on 2025-05-11 08:24:12

 /* SPDX-License-Identifier: BSD-2-Clause */
 
 /*
  *  COPYRIGHT (c) 2012, 2018 Chris Johns <chrisj@rtems.org>
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions
  * are met:
  * 1. Redistributions of source code must retain the above copyright
  *    notice, this list of conditions and the following disclaimer.
  * 2. Redistributions in binary form must reproduce the above copyright
  *    notice, this list of conditions and the following disclaimer in the
  *    documentation and/or other materials provided with the distribution.
  *
  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  */
 /**
  * @file
  *
  * @ingroup rtems_rtl
  *
  * @brief RTEMS Run-Time Linker Object File cache buffers a section of the
  *        object file in a buffer to localise read performance.
  *
  * This is a simple object file cache that holds a buffer of data from the
  * offset in the file the read is requested from. Writes are not supported.
  *
  * The cache holds the file descriptor, the offset into the file and the amount
  * of valid data in the cache. If the file is ever modified the user of the
  * cache to responsible for flushing the cache. For example the cache should be
  * flused if the file is closed.
  *
  * The cache can return by reference or by value. By reference allow access to
  * the cache buffer. Do not modify the cache's data. By value will copy the
  * requested data into the user supplied buffer.
  *
  * The read by reference call allows you to probe the file's data. For example
  * a string in an object file can be an unknown length. You can request a read
  * up to the cache's size by reference. The code will attempt to have this data
  * in the buffer. If there is not enough data in the file the length will be
  * modifed to reflect this.
  *
  * You can have more than one cache for a single file all looking at different
  * parts of the file.
  */
 
 #if !defined (_RTEMS_RTL_OBJ_CACHE_H_)
 #define _RTEMS_RTL_OBJ_CACHE_H_
 
 #include <fcntl.h>
 #include <stdbool.h>
 #include <stdint.h>
 #include <stdlib.h>
 
 #ifdef __cplusplus
 extern "C" {
 #endif /* __cplusplus */
 
 /**
  * The buffer cache.
  */
 typedef struct rtems_rtl_obj_cache
 {
   int      fd;        /**< The file descriptor of the data in the cache. */
   size_t   file_size; /**< The size of the file. */
   off_t    offset;    /**< The base offset of the buffer. */
   size_t   size;      /**< The size of the cache. */
   size_t   level;     /**< The amount of data in the cache. A file can be
                        * smaller than the cache file. */
   uint8_t* buffer;    /**< The buffer */
 } rtems_rtl_obj_cache;
 
 /**
  * Open a cache allocating a single buffer of the size passed. The default
  * state of the cache is flushed. No already open checks are made.
  *
  * @param cache The cache to initialise.
  * @param size The size of the cache.
  * @retval true The cache is open.
  * @retval false The cache is not open. The RTL error is set.
  */
 bool rtems_rtl_obj_cache_open (rtems_rtl_obj_cache* cache, size_t size);
 
 /**
  * Close a cache.
  *
  * @param cache The cache to close.
  */
 void rtems_rtl_obj_cache_close (rtems_rtl_obj_cache* cache);
 
 /**
  * Flush the cache. Any further read will read the data from the file.
  *
  * @param cache The cache to flush.
  */
 void rtems_rtl_obj_cache_flush (rtems_rtl_obj_cache* cache);
 
 /**
  * Read data by reference. The length contains the amount of data that should
  * be available in the cache and referenced by the buffer handle. It must be
  * less than or equal to the size of the cache. This call will return the
  * amount of data that is available. It can be less than you ask if the offset
  * and size is past the end of the file.
  *
  * @param cache The cache to reference data from.
  * @param fd The file descriptor. Must be an open file.
  * @param offset The offset in the file to reference the data to.
  * @param buffer The location to reference the data from.
  * @param length The length of data to reference. Can be modified to a
  *               lesser value and true is still returned so check it.
  * @retval true The data referenced is in the cache.
  * @retval false The read failed and the RTL error has been set.
  */
 bool rtems_rtl_obj_cache_read (rtems_rtl_obj_cache* cache,
                                int                  fd,
                                off_t                offset,
                                void**               buffer,
                                size_t*              length);
 
 /**
  * Read data by value. The data is copied to the user supplied buffer.
  *
  * @param cache The cache to read the data from.
  * @param fd The file descriptor. Must be an open file.
  * @param offset The offset in the file to read the data from.
  * @param buffer The location the data is written into.
  * @param length The length of data to read.
  * @retval true The data has been read from the cache.
  * @retval false The read failed and the RTL error has been set.
  */
 bool rtems_rtl_obj_cache_read_byval (rtems_rtl_obj_cache* cache,
                                      int                  fd,
                                      off_t                offset,
                                      void*                buffer,
                                      size_t               length);
 
 #ifdef __cplusplus
 }
 #endif /* __cplusplus */
 
 #endif

This page was automatically generated by the 2.3.7 LXR engine. The LXR team