rtems/rtl/rtl-obj-comp.h

0001 /* SPDX-License-Identifier: BSD-2-Clause */
0002
0003 /*
0004  *  COPYRIGHT (c) 2012, 2018 Chris Johns <chrisj@rtems.org>
0005  *
0006  * Redistribution and use in source and binary forms, with or without
0007  * modification, are permitted provided that the following conditions
0008  * are met:
0009  * 1. Redistributions of source code must retain the above copyright
0010  *    notice, this list of conditions and the following disclaimer.
0011  * 2. Redistributions in binary form must reproduce the above copyright
0012  *    notice, this list of conditions and the following disclaimer in the
0013  *    documentation and/or other materials provided with the distribution.
0014  *
0015  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
0016  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
0017  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
0018  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
0019  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
0020  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
0021  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
0022  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
0023  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
0024  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
0025  * POSSIBILITY OF SUCH DAMAGE.
0026  */
0027 /**
0028  * @file
0029  *
0030  * @ingroup rtems_rtl
0031  *
0032  * @brief RTEMS Run-Time Linker Object File Compression manages a
0033  *        compressed stream of data.
0034  *
0035  * This is a simple interface to the object file cache to stream data from
0036  * from a compressed object file. There is no ability to seek with the
0037  * data from a compressed file. The module exists to allocate the output
0038  * buffer when the loader starts and use the cache buffers will have been
0039  * allocated.
0040  */
0041
0042 #if !defined (_RTEMS_RTL_OBJ_COMP_H_)
0043 #define _RTEMS_RTL_OBJ_COMP_H_
0044
0045 #include <rtems/rtl/rtl-obj-cache.h>
0046
0047 #ifdef __cplusplus
0048 extern "C" {
0049 #endif /* __cplusplus */
0050
0051 /**
0052  * The amount of input data read at a time from the file.
0053  */
0054 #define RTEMS_RTL_DECOMP_INPUT_SIZE (256)
0055
0056 /**
0057  * The types of supported compression.
0058  */
0059 #define RTEMS_RTL_COMP_NONE (0)
0060 #define RTEMS_RTL_COMP_LZ77 (1)
0061
0062 /**
0063  * The compressed file.
0064  */
0065 typedef struct rtems_rtl_obj_cpmp
0066 {
0067   rtems_rtl_obj_cache* cache;       /**< The cache provides the input
0068                                        *   buffer. */
0069   int                  fd;          /**< The file descriptor. */
0070   int                  compression; /**< The type of compression. */
0071   off_t                offset;      /**< The base offset of the buffer. */
0072   size_t               size;        /**< The size of the output buffer. */
0073   size_t               level;       /**< The amount of data in the buffer. */
0074   uint8_t*             buffer;      /**< The buffer */
0075   uint32_t             read;        /**< The amount of data read. */
0076 } rtems_rtl_obj_comp;
0077
0078 /**
0079  * Return the input level.
0080  */
0081 static inline uint32_t rtems_rtl_obj_comp_input (rtems_rtl_obj_comp* comp)
0082 {
0083   return comp->read;
0084 }
0085
0086 /**
0087  * Open a compressor allocating the output buffer.
0088  *
0089  * @param comp The compressor  to initialise.
0090  * @param size The size of the compressor's output buffer.
0091  * @retval true The compressor is open.
0092  * @retval false The compressor is not open. The RTL error is set.
0093  */
0094 bool rtems_rtl_obj_comp_open (rtems_rtl_obj_comp*  comp,
0095                               size_t               size);
0096
0097 /**
0098  * Close a compressor.
0099  *
0100  * @param comp The compressor to close.
0101  */
0102 void rtems_rtl_obj_comp_close (rtems_rtl_obj_comp* comp);
0103
0104 /**
0105  * Set the cache and offset in the file the compressed stream starts.
0106  *
0107  * @param comp The compressor to set the offset in.
0108  * @param cache The cache to read the file in by.
0109  * @param fd The file descriptor. Must be an open file.
0110  * @param compression The type of compression being streamed.
0111  * @param offset The offset in the file the compressed stream starts.
0112  */
0113 void rtems_rtl_obj_comp_set (rtems_rtl_obj_comp*  comp,
0114                              rtems_rtl_obj_cache* cache,
0115                              int                  fd,
0116                              int                  compression,
0117                              off_t                offset);
0118
0119 /**
0120  * Read decompressed data. The length contains the amount of data that should
0121  * be available in the cache and referenced by the buffer handle. It must be
0122  * less than or equal to the size of the cache. This call will return the
0123  * amount of data that is available. It can be less than you ask if the offset
0124  * and size is past the end of the file.
0125  *
0126  * @param comp The compressor to read data from.
0127  * @param buffer The buffer the output is written too.
0128  * @param length The length of data to read. Can be modified to a
0129  *               lesser value and true is still returned so check it.
0130  * @retval true The data referenced is in the cache.
0131  * @retval false The read failed and the RTL error has been set.
0132  */
0133 bool rtems_rtl_obj_comp_read (rtems_rtl_obj_comp* comp,
0134                               void*               buffer,
0135                               size_t              length);
0136
0137 #ifdef __cplusplus
0138 }
0139 #endif /* __cplusplus */
0140
0141 #endif