include/rtems/libcsupport.h

0001 /* SPDX-License-Identifier: BSD-2-Clause */
0002
0003 /**
0004  * @file
0005  *
0006  * @ingroup libcsupport
0007  *
0008  * @brief Standard C Library Support
0009  *
0010  * This include file contains the information regarding the
0011  * RTEMS specific support for the standard C library.
0012  */
0013
0014 /*
0015  *  COPYRIGHT (c) 1989-2011.
0016  *  On-Line Applications Research Corporation (OAR).
0017  *
0018  * Redistribution and use in source and binary forms, with or without
0019  * modification, are permitted provided that the following conditions
0020  * are met:
0021  * 1. Redistributions of source code must retain the above copyright
0022  *    notice, this list of conditions and the following disclaimer.
0023  * 2. Redistributions in binary form must reproduce the above copyright
0024  *    notice, this list of conditions and the following disclaimer in the
0025  *    documentation and/or other materials provided with the distribution.
0026  *
0027  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
0028  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
0029  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
0030  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
0031  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
0032  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
0033  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
0034  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
0035  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
0036  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
0037  * POSSIBILITY OF SUCH DAMAGE.
0038  */
0039
0040 #ifndef _RTEMS_RTEMS_LIBCSUPPORT_H
0041 #define _RTEMS_RTEMS_LIBCSUPPORT_H
0042
0043 #include <sys/types.h>
0044 #include <stdint.h>
0045
0046 #include <rtems/score/heap.h>
0047 #include <rtems/rtems/tasks.h>
0048
0049 #ifdef __cplusplus
0050 extern "C" {
0051 #endif
0052
0053 /**
0054  * @defgroup libcsupport Standard C Library Support
0055  *
0056  * @ingroup RTEMSImpl
0057  *
0058  * @brief RTEMS Specific Support for the Standard C Library
0059  *
0060  * @{
0061  */
0062
0063 extern void malloc_dump(void);
0064
0065 /**
0066  * @brief Malloc walk.
0067  */
0068 extern bool malloc_walk(int source, bool printf_enabled);
0069
0070 /**
0071  * @brief Set malloc heap pointer.
0072  *
0073  * This routine is primarily used for debugging.
0074  */
0075 void malloc_set_heap_pointer(Heap_Control *new_heap);
0076
0077 /**
0078  * @brief Get malloc heap pointer.
0079  *
0080  * This routine is primarily used for debugging.
0081  */
0082 Heap_Control *malloc_get_heap_pointer( void );
0083
0084 /**
0085  * @brief Get free malloc information.
0086  *
0087  * Find amount of free heap remaining
0088  */
0089 extern size_t malloc_free_space(void);
0090
0091 /**
0092  * @brief Get malloc status information.
0093  *
0094  * Find amount of free heap remaining.
0095  */
0096 extern int malloc_info(Heap_Information_block *the_info);
0097
0098 /*
0099  *  Prototypes required to install newlib reentrancy user extension
0100  */
0101
0102 #ifdef _REENT_THREAD_LOCAL
0103 #define _NEWLIB_CREATE_HOOK NULL
0104 #else
0105 bool newlib_create_hook(
0106   rtems_tcb *current_task,
0107   rtems_tcb *creating_task
0108 );
0109 #define _NEWLIB_CREATE_HOOK newlib_create_hook
0110 #endif
0111
0112 void newlib_terminate_hook(
0113   rtems_tcb *current_task
0114 );
0115
0116 #define RTEMS_NEWLIB_EXTENSION \
0117   { \
0118     _NEWLIB_CREATE_HOOK,  /* thread_create    */ \
0119     NULL,                 /* thread_start     */ \
0120     NULL,                 /* thread_restart   */ \
0121     NULL,                 /* thread_delete    */ \
0122     NULL,                 /* thread_switch    */ \
0123     NULL,                 /* thread_begin     */ \
0124     NULL,                 /* thread_exitted   */ \
0125     NULL,                 /* fatal            */ \
0126     newlib_terminate_hook /* thread_terminate */ \
0127   }
0128
0129 typedef struct {
0130   uint32_t active_barriers;
0131   uint32_t active_extensions;
0132   uint32_t active_message_queues;
0133   uint32_t active_partitions;
0134   uint32_t active_periods;
0135   uint32_t active_ports;
0136   uint32_t active_regions;
0137   uint32_t active_semaphores;
0138   uint32_t active_tasks;
0139   uint32_t active_timers;
0140 } rtems_resource_rtems_api;
0141
0142 typedef struct {
0143   uint32_t active_message_queues;
0144   uint32_t active_semaphores;
0145   uint32_t active_threads;
0146   uint32_t active_timers;
0147 } rtems_resource_posix_api;
0148
0149 typedef struct {
0150   Heap_Information_block workspace_info;
0151   Heap_Information_block heap_info;
0152   uint32_t active_posix_key_value_pairs;
0153   uint32_t active_posix_keys;
0154   rtems_resource_rtems_api rtems_api;
0155   rtems_resource_posix_api posix_api;
0156   int open_files;
0157 } rtems_resource_snapshot;
0158
0159 /**
0160  * @brief Tasks a snapshot of the resource usage of the system.
0161  *
0162  * @param[out] snapshot The snapshot of used resources.
0163  *
0164  * @see rtems_resource_snapshot_equal() and rtems_resource_snapshot_check().
0165  *
0166  * @code
0167  * #include <assert.h>
0168  *
0169  * #include <rtems/libcsupport.h>
0170  *
0171  * void example(void)
0172  * {
0173  *   rtems_resource_snapshot before;
0174  *
0175  *   test_setup();
0176  *   rtems_resource_snapshot_take(&before);
0177  *   test();
0178  *   assert(rtems_resource_snapshot_check(&before));
0179  *   test_cleanup();
0180  * }
0181  * @endcode
0182  */
0183 void rtems_resource_snapshot_take(rtems_resource_snapshot *snapshot);
0184
0185 /**
0186  * @brief Compares two resource snapshots for equality.
0187  *
0188  * @param[in] a One resource snapshot.
0189  * @param[in] b Another resource snapshot.
0190  *
0191  * @retval true The resource snapshots are equal.
0192  * @retval false Otherwise.
0193  *
0194  * @see rtems_resource_snapshot_take().
0195  */
0196 bool rtems_resource_snapshot_equal(
0197   const rtems_resource_snapshot *a,
0198   const rtems_resource_snapshot *b
0199 );
0200
0201 /**
0202  * @brief Takes a new resource snapshot and checks that it is equal to the
0203  * given resource snapshot.
0204  *
0205  * @param[in] snapshot The resource snapshot used for comparison with the new
0206  * resource snapshot.
0207  *
0208  * @retval true The resource snapshots are equal.
0209  * @retval false Otherwise.
0210  *
0211  * @see rtems_resource_snapshot_take().
0212  */
0213 bool rtems_resource_snapshot_check(const rtems_resource_snapshot *snapshot);
0214
0215 /** @} */
0216
0217 #ifdef __cplusplus
0218 }
0219 #endif
0220
0221 #endif
0222 /* end of include file */