rtems/rtl/rtl-allocator.h

0001 /* SPDX-License-Identifier: BSD-2-Clause */
0002
0003 /*
0004  *  COPYRIGHT (c) 2012, 2018, 2023 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 Allocator
0033  */
0034
0035 #if !defined (_RTEMS_RTL_ALLOCATOR_H_)
0036 #define _RTEMS_RTL_ALLOCATOR_H_
0037
0038 #include <stdbool.h>
0039
0040 #include "rtl-indirect-ptr.h"
0041
0042 #ifdef __cplusplus
0043 extern "C" {
0044 #endif /* __cplusplus */
0045
0046 /**
0047  * Define the types of allocation the loader requires.
0048  *
0049  * @note It is best to use the object tag for general memory allocation and to
0050  *       leave the tags with specific access properties to the module data
0051  */
0052 enum rtems_rtl_alloc_tags {
0053   RTEMS_RTL_ALLOC_OBJECT,     /**< A generic memory object. */
0054   RTEMS_RTL_ALLOC_SYMBOL,     /**< Memory used for symbols. */
0055   RTEMS_RTL_ALLOC_EXTERNAL,   /**< Memory used for external symbols. */
0056   RTEMS_RTL_ALLOC_READ,       /**< The memory is read only. */
0057   RTEMS_RTL_ALLOC_READ_WRITE, /**< The memory is read and write. */
0058   RTEMS_RTL_ALLOC_READ_EXEC   /**< The memory is read and executable. */
0059 };
0060
0061 /**
0062  * The allocator tag type.
0063  */
0064 typedef enum rtems_rtl_alloc_tags rtems_rtl_alloc_tag;
0065
0066 /**
0067  * Define the allocation command the loader requires.
0068  */
0069 enum rtems_rtl_alloc_cmd {
0070   RTEMS_RTL_ALLOC_NEW,        /**< Allocate new memory. */
0071   RTEMS_RTL_ALLOC_DEL,        /**< Delete allocated memory. */
0072   RTEMS_RTL_ALLOC_RESIZE,     /**< Resize allocated memory. */
0073   RTEMS_RTL_ALLOC_LOCK,       /**< Lock the allocator. */
0074   RTEMS_RTL_ALLOC_UNLOCK,     /**< Unlock the allocator. */
0075   RTEMS_RTL_ALLOC_WR_ENABLE,  /**< Enable writes to the memory. */
0076   RTEMS_RTL_ALLOC_WR_DISABLE, /**< Disable writes to the memory. */
0077 };
0078
0079 /**
0080  * The allocator command type.
0081  */
0082 typedef enum rtems_rtl_alloc_cmd rtems_rtl_alloc_cmd;
0083
0084 /**
0085  * The number of tags.
0086  */
0087 #define RTEMS_RTL_ALLOC_TAGS ((size_t) (RTEMS_RTL_ALLOC_READ_EXEC + 1))
0088
0089 /**
0090  * Allocator handler handles all RTL allocations. It can be hooked and
0091  * overridded for customised allocation schemes or memory maps.
0092  *
0093  * @param allocation The request command.
0094  * @param tag The type of allocation request.
0095  * @param address Pointer to the memory address. If an allocation the value is
0096  *                unspecific on entry and the allocated address or NULL on
0097  *                exit. The NULL value means the allocation failed. If a delete
0098  *                or free request the memory address is the block to free. A
0099  *                free request of NULL is silently ignored.
0100  * @param size The size of the allocation if an allocation request and
0101  *             not used if deleting or freeing a previous allocation.
0102  */
0103 typedef void (*rtems_rtl_allocator)(rtems_rtl_alloc_cmd cmd,
0104                                     rtems_rtl_alloc_tag tag,
0105                                     void**              address,
0106                                     size_t              size);
0107
0108 /**
0109  * The allocator data.
0110  */
0111 struct rtems_rtl_alloc_data {
0112   /**< The memory allocator handler. */
0113   rtems_rtl_allocator allocator;
0114   /**< The indirect pointer chains. */
0115   rtems_chain_control indirects[RTEMS_RTL_ALLOC_TAGS];
0116 };
0117
0118 typedef struct rtems_rtl_alloc_data rtems_rtl_alloc_data;
0119
0120 /**
0121  * Initialise the allocate data.
0122  *
0123  * @param data The data to initialise.
0124  */
0125 void rtems_rtl_alloc_initialise (rtems_rtl_alloc_data* data);
0126
0127 /**
0128  * The Runtime Loader allocator new allocates new memory and optionally clear
0129  * the memory if requested.
0130  *
0131  * @param tag The type of allocation request.
0132  * @param size The size of the allocation.
0133  * @param zero If true the memory is cleared.
0134  * @return void* The memory address or NULL is not memory available.
0135  */
0136 void* rtems_rtl_alloc_new (rtems_rtl_alloc_tag tag, size_t size, bool zero);
0137
0138 /**
0139  * The Runtime Loader allocator delete deletes allocated memory.
0140  *
0141  * @param tag The type of allocation request.
0142  * @param address The memory address to delete. A NULL is ignored.
0143  */
0144 void rtems_rtl_alloc_del (rtems_rtl_alloc_tag tag, void* address);
0145
0146 /**
0147  * The Runtime Loader allocator resize resizes allocated memory.
0148  *
0149  * This call resizes a previously allocated block of memory. If the
0150  * provided address cannot be resized it is deleted and a new block is
0151  * allocated and the contents of the existing memory is copied.
0152  *
0153  *
0154  * @param tag The type of allocation request.
0155  * @param address The memory address to resize. A NULL is ignored.
0156  * @param size The size of the allocation.
0157  * @param zero If true the memory is cleared.
0158  * @return void* The memory address or NULL is not memory available.
0159  */
0160 void* rtems_rtl_alloc_resize (rtems_rtl_alloc_tag tag,
0161                               void*               address,
0162                               size_t              size,
0163                               bool                zero);
0164
0165 /**
0166  * The Runtime Loader allocator lock. An allocator that depends on a
0167  * separate allocation process, for example the heap, may need to be
0168  * locked during loading of an object file to make sure the locality
0169  * of the memory. This call be used to lock such an allocator.
0170  *  Allocator calls in this interface are protected by the RTL lock.
0171  */
0172 void rtems_rtl_alloc_lock (void);
0173
0174 /**
0175  * The Runtime Loader allocator unlock. An allocator that depends on a
0176  * separate allocation process, for example the heap, may need to be
0177  * locked during loading of an object file to make sure the locality
0178  * of the memory. This call can be used to unlock such an allocator.
0179  * Allocator calls in this interface are protected by the RTL lock.
0180  */
0181 void rtems_rtl_alloc_unlock (void);
0182
0183 /**
0184  * The Runtime Loader allocator enable write on a bloc of allocated memory.
0185  *
0186  * @param tag The type of allocation request. Must match the address.
0187  * @param address The memory address to write enable. A NULL is ignored.
0188  */
0189 void rtems_rtl_alloc_wr_enable (rtems_rtl_alloc_tag tag, void* address);
0190
0191 /**
0192  * The Runtime Loader allocator disable write on a bloc of allocated memory.
0193  *
0194  * @param tag The type of allocation request. Must match the address.
0195  * @param address The memory address to write disable. A NULL is ignored.
0196  */
0197 void rtems_rtl_alloc_wr_disable (rtems_rtl_alloc_tag tag, void* address);
0198
0199 /**
0200  * Hook the Runtime Loader allocatior. A handler can call the previous handler
0201  * in the chain to use it for specific tags. The default handler uses the
0202  * system heap. Do not unhook your handler if memory it allocates has not been
0203  * returned.
0204  *
0205  * @param handler The handler to use as the allocator.
0206  * @return rtems_rtl_alloc_handler The previous handler.
0207  */
0208 rtems_rtl_allocator rtems_rtl_alloc_hook (rtems_rtl_allocator handler);
0209
0210 /**
0211  * Allocate memory to an indirect handle.
0212  *
0213  * @param tag The type of allocation request.
0214  * @param handle The handle to allocate the memory to.
0215  * @param size The size of the allocation.
0216  */
0217 void rtems_rtl_alloc_indirect_new (rtems_rtl_alloc_tag tag,
0218                                    rtems_rtl_ptr*      handle,
0219                                    size_t              size);
0220
0221 /**
0222  * Free memory from an indirect handle.
0223  *
0224  * @param tag The type of allocation request.
0225  * @param handle The handle to free the memory from.
0226  */
0227 void rtems_rtl_alloc_indirect_del (rtems_rtl_alloc_tag tag,
0228                                    rtems_rtl_ptr*      handle);
0229
0230 /**
0231  * Return the default tag for text sections.
0232  *
0233  * @return The text tag.
0234  */
0235 rtems_rtl_alloc_tag rtems_rtl_alloc_text_tag (void);
0236
0237 /**
0238  * Return the default tag for const sections.
0239  *
0240  * @return The const tag.
0241  */
0242 rtems_rtl_alloc_tag rtems_rtl_alloc_const_tag (void);
0243
0244 /**
0245  * Return the default tag for exception sections.
0246  *
0247  * @return The eh tag.
0248  */
0249 rtems_rtl_alloc_tag rtems_rtl_alloc_eh_tag (void);
0250
0251 /**
0252  * Return the default tag for data sections.
0253  *
0254  * @return The data tag.
0255  */
0256 rtems_rtl_alloc_tag rtems_rtl_alloc_data_tag (void);
0257
0258 /**
0259  * Return the default tag for bss sections.
0260  *
0261  * @return The bss tag.
0262  */
0263 rtems_rtl_alloc_tag rtems_rtl_alloc_bss_tag (void);
0264
0265 /**
0266  * Allocate the memory for a module given the size of the text, const, data and
0267  * bss sections. If any part of the allocation fails the no memory is
0268  * allocated.
0269  *
0270  * @param text_base Pointer to the text base pointer.
0271  * @param text_size The size of the read/exec section.
0272  * @param const_base Pointer to the const base pointer.
0273  * @param const_size The size of the read only section.
0274  * @param eh_base Pointer to the eh base pointer.
0275  * @param eh_size The size of the eh section.
0276  * @param data_base Pointer to the data base pointer.
0277  * @param data_size The size of the read/write secton.
0278  * @param bss_base Pointer to the bss base pointer.
0279  * @param bss_size The size of the read/write.
0280  * @retval true The memory has been allocated.
0281  * @retval false The allocation of memory has failed.
0282  */
0283 bool rtems_rtl_alloc_module_new (void** text_base, size_t text_size,
0284                                  void** const_base, size_t const_size,
0285                                  void** eh_base, size_t eh_size,
0286                                  void** data_base, size_t data_size,
0287                                  void** bss_base, size_t bss_size);
0288
0289 /**
0290  * Resize the allocated memory for a module given the new size of the text,
0291  * const, data and bss sections. If any part of the allocation fails the
0292  * allocated is deleted.
0293  *
0294  * @param text_base Pointer to the text base pointer.
0295  * @param text_size The size of the read/exec section.
0296  * @param const_base Pointer to the const base pointer.
0297  * @param const_size The size of the read only section.
0298  * @param eh_base Pointer to the eh base pointer.
0299  * @param eh_size The size of the eh section.
0300  * @param data_base Pointer to the data base pointer.
0301  * @param data_size The size of the read/write secton.
0302  * @param bss_base Pointer to the bss base pointer.
0303  * @param bss_size The size of the read/write.
0304  * @retval true The memory has been allocated.
0305  * @retval false The allocation of memory has failed.
0306  */
0307 bool rtems_rtl_alloc_module_resize (void** text_base, size_t text_size,
0308                                     void** const_base, size_t const_size,
0309                                     void** eh_base, size_t eh_size,
0310                                     void** data_base, size_t data_size,
0311                                     void** bss_base, size_t bss_size);
0312
0313 /**
0314  * Free the memory allocated to a module.
0315  *
0316  * @param text_base Pointer to the text base pointer.
0317  * @param const_base Pointer to the const base pointer.
0318  * @param eh_base Pointer to the eh base pointer.
0319  * @param data_base Pointer to the data base pointer.
0320  * @param bss_base Pointer to the bss base pointer.
0321  */
0322 void rtems_rtl_alloc_module_del (void** text_base, void** const_base,
0323                                  void** eh_base, void** data_base,
0324                                  void** bss_base);
0325
0326 #ifdef __cplusplus
0327 }
0328 #endif /* __cplusplus */
0329
0330 #endif