rtems/score/protectedheap.h

0001 /* SPDX-License-Identifier: BSD-2-Clause */
0002
0003 /**
0004  * @file
0005  *
0006  * @ingroup RTEMSScoreProtHeap
0007  *
0008  * @brief This header file provides the interfaces of the
0009  *   @ref RTEMSScoreProtHeap.
0010  */
0011
0012 /*
0013  *  COPYRIGHT (c) 1989-2007.
0014  *  On-Line Applications Research Corporation (OAR).
0015  *
0016  * Redistribution and use in source and binary forms, with or without
0017  * modification, are permitted provided that the following conditions
0018  * are met:
0019  * 1. Redistributions of source code must retain the above copyright
0020  *    notice, this list of conditions and the following disclaimer.
0021  * 2. Redistributions in binary form must reproduce the above copyright
0022  *    notice, this list of conditions and the following disclaimer in the
0023  *    documentation and/or other materials provided with the distribution.
0024  *
0025  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
0026  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
0027  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
0028  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
0029  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
0030  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
0031  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
0032  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
0033  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
0034  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
0035  * POSSIBILITY OF SUCH DAMAGE.
0036  */
0037
0038 #ifndef _RTEMS_SCORE_PROTECTED_HEAP_H
0039 #define _RTEMS_SCORE_PROTECTED_HEAP_H
0040
0041 #include <rtems/score/heapimpl.h>
0042 #include <rtems/score/apimutex.h>
0043
0044 #ifdef __cplusplus
0045 extern "C" {
0046 #endif
0047
0048 /**
0049  * @defgroup RTEMSScoreProtHeap Protected Heap Handler
0050  *
0051  * @ingroup RTEMSScoreHeap
0052  *
0053  * @brief This group contains the Protected Heap Handler implementation.
0054  *
0055  * The @ref ScoreAllocatorMutex is used to protect the heap accesses.
0056  *
0057  * @{
0058  */
0059
0060 /**
0061  * @brief Initializes the protected heap.
0062  *
0063  * @param[out] heap The heap to initialize.
0064  * @param area_begin The starting address of the heap area.
0065  * @param area_size The size of the heap area.
0066  * @param page_size The page size for the heap.
0067  */
0068 static inline uintptr_t _Protected_heap_Initialize(
0069   Heap_Control *heap,
0070   void *area_begin,
0071   uintptr_t area_size,
0072   uintptr_t page_size
0073 )
0074 {
0075   return _Heap_Initialize( heap, area_begin, area_size, page_size );
0076 }
0077
0078 /**
0079  * @brief Extends the protected heap.
0080  *
0081  * @param[in, out] heap The heap to extend.
0082  * @param area_begin The starting addres of the area to extend @a heap with.
0083  * @param area_size The size of the heap area.
0084  *
0085  * @retval true The operation succeeded.
0086  * @retval false The operation failed.
0087  */
0088 bool _Protected_heap_Extend(
0089   Heap_Control *heap,
0090   void *area_begin,
0091   uintptr_t area_size
0092 );
0093
0094 /**
0095  * @brief Allocates an aligned memory area with boundary constraint for the protected heap.
0096  *
0097  * A size value of zero will return a unique address which may be freed with
0098  * _Heap_Free().  This method first locks the allocator and after the allocation of the memory
0099  * area, unlocks it again.
0100  *
0101  * @param[in, out] heap The heap to allocate a memory are from.
0102  * @param size The size of the desired memory are in bytes.
0103  * @param alignment The allocated memory area will begin at an address aligned by this value.
0104  * @param boundary The allocated memory area will fulfill a boundary constraint,
0105  *      if this value is not equal to zero.  The boundary value specifies
0106  *      the set of addresses which are aligned by the boundary value.  The
0107  *      interior of the allocated memory area will not contain an element of this
0108  *      set.  The begin or end address of the area may be a member of the set.
0109  *
0110  * @retval pointer The starting address of the allocated memory area.
0111  * @retval NULL No memory is available of the parameters are inconsistent.
0112  */
0113 void *_Protected_heap_Allocate_aligned_with_boundary(
0114   Heap_Control *heap,
0115   uintptr_t size,
0116   uintptr_t alignment,
0117   uintptr_t boundary
0118 );
0119
0120 /**
0121  * @brief Allocates an aligned memory area.
0122  *
0123  * A size value of zero will return a unique address which may be freed with
0124  * _Heap_Free().  This method first locks the allocator and after the allocation of the memory
0125  * area, unlocks it again.
0126  *
0127  * @param[in, out] heap The heap to allocate a memory are from.
0128  * @param size The size of the desired memory are in bytes.
0129  * @param alignment The allocated memory area will begin at an address aligned by this value.
0130  *
0131  * @retval pointer The starting address of the allocated memory area.
0132  * @retval NULL No memory is available of the parameters are inconsistent.
0133  */
0134 static inline void *_Protected_heap_Allocate_aligned(
0135   Heap_Control *heap,
0136   uintptr_t size,
0137   uintptr_t alignment
0138 )
0139 {
0140   return
0141     _Protected_heap_Allocate_aligned_with_boundary( heap, size, alignment, 0 );
0142 }
0143
0144 /**
0145  * @brief Allocates a memory area.
0146  *
0147  * A size value of zero will return a unique address which may be freed with
0148  * _Heap_Free().  This method first locks the allocator and after the allocation of the memory
0149  * area, unlocks it again.
0150  *
0151  * @param[in, out] heap The heap to allocate a memory are from.
0152  * @param size The size of the desired memory are in bytes.
0153  *
0154  * @retval pointer The starting address of the allocated memory area.
0155  * @retval NULL No memory is available of the parameters are inconsistent.
0156  */
0157 static inline void *_Protected_heap_Allocate(
0158   Heap_Control *heap,
0159   uintptr_t size
0160 )
0161 {
0162   return _Protected_heap_Allocate_aligned_with_boundary( heap, size, 0, 0 );
0163 }
0164
0165 /**
0166  * @brief Frees the allocated memory area.
0167  *
0168  * Inappropriate values for @a addr may corrupt the heap.  This method first locks
0169  * the allocator and after the free operation, unlocks it again.
0170  *
0171  * @param[in, out] heap The heap of the allocated memory area.
0172  * @param addr The starting address of the memory area to be freed.
0173  *
0174  * @retval true The allocated memory area was successfully freed.
0175  * @retval false The method failed.
0176  */
0177 bool _Protected_heap_Free( Heap_Control *heap, void *addr );
0178
0179 /**
0180  * @brief Verifies the integrity of the heap.
0181  *
0182  * Walks the heap to verify its integrity.  This method first locks
0183  * the allocator and after the operation, unlocks it again, if the thread dispatch is enabled.
0184  *
0185  * @param heap The heap whose integrity is to be verified.
0186  * @param source If @a dump is @c true, this is used to mark the output lines.
0187  * @param dump Indicates whether diagnostic messages will be printed to standard output.
0188  *
0189  * @retval true No errors occurred, the heap´s integrity is not violated.
0190  * @retval false The heap is corrupt.
0191  */
0192 bool _Protected_heap_Walk( Heap_Control *heap, int source, bool dump );
0193
0194 /**
0195  * @brief Returns information about used and free blocks for the heap.
0196  *
0197  * This method first locks the allocator and after the operation, unlocks it again.
0198  *
0199  * @param heap The heap to get the information from.
0200  * @param[out] info Stores the information of the @a heap after the method call.
0201  */
0202 bool _Protected_heap_Get_information(
0203   Heap_Control *heap,
0204   Heap_Information_block *info
0205 );
0206
0207 /**
0208  * @brief Returns information about free blocks for the heap.
0209  *
0210  * This method first locks the allocator and after the operation, unlocks it again.
0211  *
0212  * @param heap The heap to get the information from.
0213  * @param[out] info Stores the information about free blocks of @a heap after the
0214  *      method call.
0215  */
0216 bool _Protected_heap_Get_free_information(
0217   Heap_Control *heap,
0218   Heap_Information *info
0219 );
0220
0221 /**
0222  * @brief Returns the size of the allocatable area in bytes.
0223  *
0224  * This value is an integral multiple of the page size.
0225  *
0226  * @param heap The heap to get the allocatable area from.
0227  *
0228  * @return The size of the allocatable area in @a heap in bytes.
0229  */
0230 uintptr_t _Protected_heap_Get_size( Heap_Control *heap );
0231
0232 /** @} */
0233
0234 #ifdef __cplusplus
0235 }
0236 #endif
0237
0238 #endif
0239 /* end of include file */