[PATCH] rtems: Generate <rtems/rtems/support.h>
Gedare Bloom
gedare at rtems.org
Wed Apr 21 14:19:14 UTC 2021
On Wed, Apr 21, 2021 at 7:46 AM Sebastian Huber
<sebastian.huber at embedded-brains.de> wrote:
>
> 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(-)
>
> 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 <stdbool.h>
> +#include <stddef.h>
> +#include <stdint.h>
> +#include <rtems/config.h>
> #include <rtems/rtems/types.h>
> #include <rtems/score/heapinfo.h>
> -#include <rtems/config.h>
>
> #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.
I don't understand this @brief comment. Should these support services
be added to some official API group?
Everything else looks good.
> */
> -/**@{**/
> +
> +/* 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 */
> --
> 2.26.2
>
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel
More information about the devel
mailing list