From b229b4c2d63198c47c1eb0ab0aade0eef9cfceaf Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Wed, 24 Jun 2020 08:09:03 +0200 Subject: rtems: Generate Change license to BSD-2-Clause according to file histories and documentation re-licensing agreement. Update #3899. Update #3993. --- cpukit/include/rtems/rtems/support.h | 404 +++++++++++++++++++++++++++-------- 1 file changed, 320 insertions(+), 84 deletions(-) (limited to 'cpukit/include') diff --git a/cpukit/include/rtems/rtems/support.h b/cpukit/include/rtems/rtems/support.h index 92dd49076f..829548aae2 100644 --- a/cpukit/include/rtems/rtems/support.h +++ b/cpukit/include/rtems/rtems/support.h @@ -1,168 +1,404 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + /** * @file * - * @ingroup ClassicRTEMSWorkspace + * @brief This header file defines support services of the API. */ -/* COPYRIGHT (c) 1989-2008. - * On-Line Applications Research Corporation (OAR). +/* + * Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + * + * 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. + */ + +/* + * This file is part of the RTEMS quality process and was automatically + * generated. If you find something that needs to be fixed or + * worded better please post a report or patch to an RTEMS mailing list + * or raise a bug report: + * + * https://www.rtems.org/bugs.html + * + * For information on updating and regenerating please refer to the How-To + * section in the Software Requirements Engineering chapter of the + * RTEMS Software Engineering manual. The manual is provided as a part of + * a release. For development sources please refer to the online + * documentation at: * - * The license and distribution terms for this file may be - * found in the file LICENSE in this distribution or at - * http://www.rtems.org/license/LICENSE. + * https://docs.rtems.org */ +/* Generated from spec:/rtems/support/if/header */ + #ifndef _RTEMS_RTEMS_SUPPORT_H #define _RTEMS_RTEMS_SUPPORT_H +#include +#include +#include +#include #include #include -#include #ifdef __cplusplus extern "C" { #endif +/* Generated from spec:/rtems/support/if/group */ + /** - * @addtogroup ClassicTasks + * @defgroup RTEMSAPIClassicSupport Support Services + * + * @ingroup RTEMSAPIClassic + * + * @brief Items of this group should move to other groups. */ -/**@{**/ + +/* Generated from spec:/rtems/support/if/is-name-valid */ /** - * @brief Returns the number of micro seconds for the milli seconds value @a _ms. + * @ingroup RTEMSAPIClassicSupport + * + * @brief Checks if the object name is valid. + * + * @param name is the object name to check. + * + * @return Returns true, if the object name is valid, otherwise false. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within any runtime context. + * + * * The directive will not cause the calling task to be preempted. + * @endparblock */ -#define RTEMS_MILLISECONDS_TO_MICROSECONDS(_ms) ((_ms) * 1000UL) +static inline bool rtems_is_name_valid( rtems_name name ) +{ + return name != 0; +} + +/* Generated from spec:/rtems/support/if/microseconds-to-ticks */ /** - * @brief Returns the number of ticks for the milli seconds value @a _ms. + * @ingroup RTEMSAPIClassicSupport + * + * @brief Gets the number of clock ticks for the microseconds value. + * + * @param _us is the microseconds value to convert to clock ticks. + * + * @return Returns the number of clock ticks for the specified microseconds + * value. + * + * @par Notes + * The number of clock ticks per second is defined by the + * #CONFIGURE_MICROSECONDS_PER_TICK application configuration option. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within any runtime context. + * + * * The directive will not cause the calling task to be preempted. + * @endparblock */ -#define RTEMS_MILLISECONDS_TO_TICKS(_ms) \ - (RTEMS_MILLISECONDS_TO_MICROSECONDS(_ms) / \ - rtems_configuration_get_microseconds_per_tick()) +#define RTEMS_MICROSECONDS_TO_TICKS( _us ) \ + ( ( _us ) / rtems_configuration_get_microseconds_per_tick() ) + +/* Generated from spec:/rtems/support/if/milliseconds-to-microseconds */ /** - * @brief Returns the number of ticks for the micro seconds value @a _us. + * @ingroup RTEMSAPIClassicSupport + * + * @brief Gets the number of microseconds for the milliseconds value. + * + * @param _ms is the milliseconds value to convert to microseconds. + * + * @return Returns the number of microseconds for the milliseconds value. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive is implemented by a macro and may be called from within + * C/C++ constant expressions. In addition, a function implementation of the + * directive exists for bindings to other programming languages. + * + * * The directive will not cause the calling task to be preempted. + * @endparblock */ -#define RTEMS_MICROSECONDS_TO_TICKS(_us) \ - ((_us) / rtems_configuration_get_microseconds_per_tick()) +#define RTEMS_MILLISECONDS_TO_MICROSECONDS( _ms ) ( ( _ms ) * 1000UL ) + +/* Generated from spec:/rtems/support/if/milliseconds-to-ticks */ /** - * @brief Returns @c true if the name is valid, and @c false otherwise. + * @ingroup RTEMSAPIClassicSupport + * + * @brief Gets the number of clock ticks for the milliseconds value. + * + * @param _ms is the milliseconds value to convert to clock ticks. + * + * @return Returns the number of clock ticks for the milliseconds value. + * + * @par Notes + * The number of clock ticks per second is defined by the + * #CONFIGURE_MICROSECONDS_PER_TICK application configuration option. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within any runtime context. + * + * * The directive will not cause the calling task to be preempted. + * @endparblock */ -RTEMS_INLINE_ROUTINE bool rtems_is_name_valid ( - rtems_name name -) -{ - return ( name != 0 ); -} +#define RTEMS_MILLISECONDS_TO_TICKS( _ms ) \ + RTEMS_MICROSECONDS_TO_TICKS( RTEMS_MILLISECONDS_TO_MICROSECONDS( _ms ) ) + +/* Generated from spec:/rtems/support/if/name-to-characters */ /** - * @brief Breaks the object name into the four component characters @a c1, - * @a c2, @a c3, and @a c4. + * @ingroup RTEMSAPIClassicSupport + * + * @brief Breaks the object name into the four component characters. + * + * @param name is the object name to break into four component characters. + * + * @param[out] c1 is the first character of the object name. + * + * @param[out] c2 is the second character of the object name. + * + * @param[out] c3 is the third character of the object name. + * + * @param[out] c4 is the fourth character of the object name. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within any runtime context. + * + * * The directive will not cause the calling task to be preempted. + * @endparblock */ -RTEMS_INLINE_ROUTINE void rtems_name_to_characters( - rtems_name name, - char *c1, - char *c2, - char *c3, - char *c4 +static inline void rtems_name_to_characters( + rtems_name name, + char *c1, + char *c2, + char *c3, + char *c4 ) { - *c1 = (char) ((name >> 24) & 0xff); - *c2 = (char) ((name >> 16) & 0xff); - *c3 = (char) ((name >> 8) & 0xff); - *c4 = (char) ( name & 0xff); + *c1 = (char) ( ( ( name ) >> 24 ) & 0xff ); + *c2 = (char) ( ( ( name ) >> 16 ) & 0xff ); + *c3 = (char) ( ( ( name ) >> 8 ) & 0xff ); + *c4 = (char) ( ( name ) & 0xff ); } -/** @} */ +/* Generated from spec:/rtems/support/if/workspace-allocate */ /** - * @defgroup ClassicRTEMSWorkspace Workspace + * @ingroup RTEMSAPIClassicSupport * - * @ingroup RTEMSAPIClassic + * @brief Allocates a memory area from the RTEMS Workspace. * - * Workspace definitions. - */ -/**@{**/ - -/** - * @brief Gets Workspace Information + * @param bytes is the number of bytes to allocated. + * + * @param[out] pointer is the pointer to a pointer variable. When the + * directive call is successful, the begin address of the allocated memory + * area will be stored in this variable. + * + * @return Returns true, if the allocation was successful, otherwise false. * - * Returns information about the heap that is used as the RTEMS Executive - * Workspace in @a the_info. + * @par Notes + * This directive is intended to be used by tests of the RTEMS test suites. * - * Returns @c true if successful, and @a false otherwise. + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within device driver initialization + * context. + * + * * The directive may be called from within task context. + * + * * The directive may obtain and release the object allocator mutex. This may + * cause the calling task to be preempted. + * @endparblock */ -bool rtems_workspace_get_information( - Heap_Information_block *the_info -); +bool rtems_workspace_allocate( size_t bytes, void **pointer ); + +/* Generated from spec:/rtems/support/if/workspace-free */ /** - * @brief Allocates Memory from the Workspace + * @ingroup RTEMSAPIClassicSupport + * + * @brief Frees the memory area allocated from the RTEMS Workspace. + * + * @param pointer is the begin address of the memory area to free. * - * A number of @a bytes bytes will be allocated from the RTEMS Executive - * Workspace and returned in @a pointer. + * @return Returns true, if freeing the memory area was successful, otherwise + * false. * - * Returns @c true if successful, and @a false otherwise. + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within device driver initialization + * context. + * + * * The directive may be called from within task context. + * + * * The directive may obtain and release the object allocator mutex. This may + * cause the calling task to be preempted. + * @endparblock */ -bool rtems_workspace_allocate( - size_t bytes, - void **pointer -); +bool rtems_workspace_free( void *pointer ); + +/* Generated from spec:/rtems/support/if/workspace-get-information */ /** - * @brief Frees Memory Allocated from the Workspace + * @ingroup RTEMSAPIClassicSupport + * + * @brief Gets information about the RTEMS Workspace. * - * This frees the memory indicated by @a pointer that was allocated from the - * RTEMS Executive Workspace. + * @param the_info is the pointer to a heap information variable. When the + * directive call is successful, the heap information will be stored in this + * variable. * - * Returns @c true if successful, and @a false otherwise. + * @return Returns true, if getting the information was successful, otherwise + * false. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within device driver initialization + * context. + * + * * The directive may be called from within task context. + * + * * The directive may obtain and release the object allocator mutex. This may + * cause the calling task to be preempted. + * @endparblock */ -bool rtems_workspace_free( - void *pointer -); +bool rtems_workspace_get_information( Heap_Information_block *the_info ); + +/* Generated from spec:/rtems/support/if/workspace-greedy-allocate */ /** - * @brief Greedy allocate that empties the workspace. + * @ingroup RTEMSAPIClassicSupport + * + * @brief Greedy allocates that empties the RTEMS Workspace. * - * Afterwards the heap has at most @a block_count allocatable blocks of sizes - * specified by @a block_sizes. The @a block_sizes must point to an array with - * @a block_count members. All other blocks are used. + * @param block_sizes is the array of block sizes. * - * @see rtems_workspace_greedy_free(). + * @param block_count is the block count. + * + * Afterwards the heap has at most ``block_count`` allocatable blocks of sizes + * specified by ``block_sizes``. The ``block_sizes`` must point to an array + * with ``block_count`` members. All other blocks are used. + * + * @return The returned pointer value may be used to free the greedy allocation + * by calling rtems_workspace_greedy_free(). */ void *rtems_workspace_greedy_allocate( const uintptr_t *block_sizes, - size_t block_count + size_t block_count ); +/* Generated from spec:/rtems/support/if/workspace-greedy-allocate-all-except-largest */ + /** - * @brief Greedy allocate all blocks except the largest free block. + * @ingroup RTEMSAPIClassicSupport + * + * @brief Greedy allocates all blocks of the RTEMS Workspace except the largest + * free block. + * + * @param allocatable_size is the remaining allocatable size. * * Afterwards the heap has at most one allocatable block. This block is the * largest free block if it exists. The allocatable size of this block is - * stored in @a allocatable_size. All other blocks are used. + * stored in ``allocatable_size``. All other blocks are used. + * + * @return The returned pointer value may be used to free the greedy allocation + * by calling rtems_workspace_greedy_free(). * - * @see rtems_workspace_greedy_free(). + * @par Notes + * This directive is intended to be used by tests of the RTEMS test suites. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within device driver initialization + * context. + * + * * The directive may be called from within task context. + * + * * The directive may obtain and release the object allocator mutex. This may + * cause the calling task to be preempted. + * @endparblock */ void *rtems_workspace_greedy_allocate_all_except_largest( uintptr_t *allocatable_size ); +/* Generated from spec:/rtems/support/if/workspace-greedy-free */ + /** - * @brief Frees space of a greedy allocation. + * @ingroup RTEMSAPIClassicSupport + * + * @brief Frees space of a greedy allocation to the RTEMS Workspace. + * + * @param opaque is the pointer value returned by + * rtems_workspace_greedy_allocate() or + * rtems_workspace_greedy_allocate_all_except_largest(). * - * The @a opaque argument must be the return value of - * rtems_workspace_greedy_allocate() or - * rtems_workspace_greedy_allocate_all_except_largest(). + * @par Notes + * This directive is intended to be used by tests of the RTEMS test suites. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within device driver initialization + * context. + * + * * The directive may be called from within task context. + * + * * The directive may obtain and release the object allocator mutex. This may + * cause the calling task to be preempted. + * @endparblock */ void rtems_workspace_greedy_free( void *opaque ); -/** @} */ - #ifdef __cplusplus } #endif -#endif -/* end of include file */ +#endif /* _RTEMS_RTEMS_SUPPORT_H */ -- cgit v1.2.3