forked from Imagelibrary/rtems
rtems: Generate <rtems/rtems/support.h>
Change license to BSD-2-Clause according to file histories and documentation re-licensing agreement. Update #3899. Update #3993.
This commit is contained in:
Sebastian Huber
@@ -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)
|
||||
*
|
||||
* 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.
|
||||
* 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:
|
||||
*
|
||||
* 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
|
||||
|
||||
/**
|
||||
* @addtogroup ClassicTasks
|
||||
*/
|
||||
/**@{**/
|
||||
/* Generated from spec:/rtems/support/if/group */
|
||||
|
||||
/**
|
||||
* @brief Returns the number of micro seconds for the milli seconds value @a _ms.
|
||||
*/
|
||||
#define RTEMS_MILLISECONDS_TO_MICROSECONDS(_ms) ((_ms) * 1000UL)
|
||||
|
||||
/**
|
||||
* @brief Returns the number of ticks for the milli seconds value @a _ms.
|
||||
*/
|
||||
#define RTEMS_MILLISECONDS_TO_TICKS(_ms) \
|
||||
(RTEMS_MILLISECONDS_TO_MICROSECONDS(_ms) / \
|
||||
rtems_configuration_get_microseconds_per_tick())
|
||||
|
||||
/**
|
||||
* @brief Returns the number of ticks for the micro seconds value @a _us.
|
||||
*/
|
||||
#define RTEMS_MICROSECONDS_TO_TICKS(_us) \
|
||||
((_us) / rtems_configuration_get_microseconds_per_tick())
|
||||
|
||||
/**
|
||||
* @brief Returns @c true if the name is valid, and @c false otherwise.
|
||||
*/
|
||||
RTEMS_INLINE_ROUTINE bool rtems_is_name_valid (
|
||||
rtems_name name
|
||||
)
|
||||
{
|
||||
return ( name != 0 );
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Breaks the object name into the four component characters @a c1,
|
||||
* @a c2, @a c3, and @a c4.
|
||||
*/
|
||||
RTEMS_INLINE_ROUTINE 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);
|
||||
}
|
||||
|
||||
/** @} */
|
||||
|
||||
/**
|
||||
* @defgroup ClassicRTEMSWorkspace Workspace
|
||||
* @defgroup RTEMSAPIClassicSupport Support Services
|
||||
*
|
||||
* @ingroup RTEMSAPIClassic
|
||||
*
|
||||
* Workspace definitions.
|
||||
* @brief Items of this group should move to other groups.
|
||||
*/
|
||||
/**@{**/
|
||||
|
||||
/* Generated from spec:/rtems/support/if/is-name-valid */
|
||||
|
||||
/**
|
||||
* @brief Gets Workspace Information
|
||||
* @ingroup RTEMSAPIClassicSupport
|
||||
*
|
||||
* Returns information about the heap that is used as the RTEMS Executive
|
||||
* Workspace in @a the_info.
|
||||
* @brief Checks if the object name is valid.
|
||||
*
|
||||
* Returns @c true if successful, and @a false otherwise.
|
||||
* @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
|
||||
*/
|
||||
bool rtems_workspace_get_information(
|
||||
Heap_Information_block *the_info
|
||||
);
|
||||
static inline bool rtems_is_name_valid( rtems_name name )
|
||||
{
|
||||
return name != 0;
|
||||
}
|
||||
|
||||
/* Generated from spec:/rtems/support/if/microseconds-to-ticks */
|
||||
|
||||
/**
|
||||
* @brief Allocates Memory from the Workspace
|
||||
* @ingroup RTEMSAPIClassicSupport
|
||||
*
|
||||
* A number of @a bytes bytes will be allocated from the RTEMS Executive
|
||||
* Workspace and returned in @a pointer.
|
||||
* @brief Gets the number of clock ticks for the microseconds value.
|
||||
*
|
||||
* Returns @c true if successful, and @a false otherwise.
|
||||
* @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
|
||||
*/
|
||||
bool rtems_workspace_allocate(
|
||||
size_t bytes,
|
||||
void **pointer
|
||||
);
|
||||
#define RTEMS_MICROSECONDS_TO_TICKS( _us ) \
|
||||
( ( _us ) / rtems_configuration_get_microseconds_per_tick() )
|
||||
|
||||
/* Generated from spec:/rtems/support/if/milliseconds-to-microseconds */
|
||||
|
||||
/**
|
||||
* @brief Frees Memory Allocated from the Workspace
|
||||
* @ingroup RTEMSAPIClassicSupport
|
||||
*
|
||||
* This frees the memory indicated by @a pointer that was allocated from the
|
||||
* RTEMS Executive Workspace.
|
||||
* @brief Gets the number of microseconds for the milliseconds value.
|
||||
*
|
||||
* Returns @c true if successful, and @a false otherwise.
|
||||
* @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
|
||||
*/
|
||||
bool rtems_workspace_free(
|
||||
void *pointer
|
||||
);
|
||||
#define RTEMS_MILLISECONDS_TO_MICROSECONDS( _ms ) ( ( _ms ) * 1000UL )
|
||||
|
||||
/* Generated from spec:/rtems/support/if/milliseconds-to-ticks */
|
||||
|
||||
/**
|
||||
* @brief Greedy allocate that empties the workspace.
|
||||
* @ingroup RTEMSAPIClassicSupport
|
||||
*
|
||||
* 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.
|
||||
* @brief Gets the number of clock ticks for the milliseconds value.
|
||||
*
|
||||
* @see rtems_workspace_greedy_free().
|
||||
* @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
|
||||
*/
|
||||
#define RTEMS_MILLISECONDS_TO_TICKS( _ms ) \
|
||||
RTEMS_MICROSECONDS_TO_TICKS( RTEMS_MILLISECONDS_TO_MICROSECONDS( _ms ) )
|
||||
|
||||
/* Generated from spec:/rtems/support/if/name-to-characters */
|
||||
|
||||
/**
|
||||
* @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
|
||||
*/
|
||||
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 );
|
||||
}
|
||||
|
||||
/* Generated from spec:/rtems/support/if/workspace-allocate */
|
||||
|
||||
/**
|
||||
* @ingroup RTEMSAPIClassicSupport
|
||||
*
|
||||
* @brief Allocates a memory area from the RTEMS Workspace.
|
||||
*
|
||||
* @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.
|
||||
*
|
||||
* @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
|
||||
*/
|
||||
bool rtems_workspace_allocate( size_t bytes, void **pointer );
|
||||
|
||||
/* Generated from spec:/rtems/support/if/workspace-free */
|
||||
|
||||
/**
|
||||
* @ingroup RTEMSAPIClassicSupport
|
||||
*
|
||||
* @brief Frees the memory area allocated from the RTEMS Workspace.
|
||||
*
|
||||
* @param pointer is the begin address of the memory area to free.
|
||||
*
|
||||
* @return Returns true, if freeing the memory area 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 );
|
||||
|
||||
/* Generated from spec:/rtems/support/if/workspace-get-information */
|
||||
|
||||
/**
|
||||
* @ingroup RTEMSAPIClassicSupport
|
||||
*
|
||||
* @brief Gets information about the RTEMS 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.
|
||||
*
|
||||
* @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_get_information( Heap_Information_block *the_info );
|
||||
|
||||
/* Generated from spec:/rtems/support/if/workspace-greedy-allocate */
|
||||
|
||||
/**
|
||||
* @ingroup RTEMSAPIClassicSupport
|
||||
*
|
||||
* @brief Greedy allocates that empties the RTEMS Workspace.
|
||||
*
|
||||
* @param block_sizes is the array of block sizes.
|
||||
*
|
||||
* @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.
|
||||
*
|
||||
* @see rtems_workspace_greedy_free().
|
||||
* @return The returned pointer value may be used to free the greedy allocation
|
||||
* by calling 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
|
||||
*
|
||||
* The @a opaque argument must be the return value of
|
||||
* rtems_workspace_greedy_allocate() or
|
||||
* rtems_workspace_greedy_allocate_all_except_largest().
|
||||
* @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().
|
||||
*
|
||||
* @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 */
|
||||
|
||||
Reference in New Issue
Block a user