diff options
author | Sebastian Huber <sebastian.huber@embedded-brains.de> | 2020-06-24 08:59:35 +0200 |
---|---|---|
committer | Sebastian Huber <sebastian.huber@embedded-brains.de> | 2020-09-22 10:06:05 +0200 |
commit | 592d9e627b88b60feba0147c1aa3c5a7f2e762fb (patch) | |
tree | 6af07347a3bc07da4ba495b990c663fe1c180417 | |
parent | 9938a7b123dc7125daacb4596623f4ca73edeca8 (diff) |
Generate <rtems/rtems/object.h>
-rw-r--r-- | cpukit/include/rtems/rtems/object.h | 500 |
1 files changed, 219 insertions, 281 deletions
diff --git a/cpukit/include/rtems/rtems/object.h b/cpukit/include/rtems/rtems/object.h index 8e8bfbf293..27cd59edd0 100644 --- a/cpukit/include/rtems/rtems/object.h +++ b/cpukit/include/rtems/rtems/object.h @@ -1,436 +1,374 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + /** * @file * - * @ingroup ClassicClassInfo + * @ingroup RTEMSAPIClassicObject * - * This include file defines Classic API interfaces to Object Services. + * @brief This header file defines the Object Manager API. + */ + +/* + * Copyright (C) 2020 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. */ -/* COPYRIGHT (c) 1989-2013. - * On-Line Applications Research Corporation (OAR). +/* + * This file was automatically generated. Do not edit it manually. + * Please have a look 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/branches/master/eng/req/howto.html + * + * for information how to maintain and re-generate this file. */ #ifndef _RTEMS_RTEMS_OBJECT_H #define _RTEMS_RTEMS_OBJECT_H +#include <stdbool.h> +#include <stddef.h> #include <stdint.h> -#include <rtems/score/object.h> #include <rtems/rtems/status.h> #include <rtems/rtems/types.h> +#include <rtems/score/object.h> #ifdef __cplusplus extern "C" { #endif /** - * @defgroup ClassicClassInfo Object Class Information + * @defgroup RTEMSAPIClassicObject Object Services * - * @ingroup RTEMSAPIClassic + * @ingroup RTEMSAPIClassic * - * This encapsulates functionality related to the Classic API Object - * Class Services. + * @brief RTEMS provides a collection of services to assist in the management + * and usage of the objects created and utilized via other managers. These + * services assist in the manipulation of RTEMS objects independent of the + * API used to create them. */ -/**@{*/ /** - * This structure is used to return information to the application - * about the objects configured for a specific API/Class combination. + * @ingroup RTEMSAPIClassicObject + * + * @brief % */ typedef struct { - /** This field is the minimum valid object Id for this class. */ - rtems_id minimum_id; - /** This field is the maximum valid object Id for this class. */ - rtems_id maximum_id; - /** This field is the number of object instances configured for this class. */ - uint32_t maximum; - /** This field indicates if the class is configured for auto-extend. */ - bool auto_extend; - /** This field is the number of currently unallocated objects. */ - uint32_t unallocated; + /** + * @brief This member is + * + * % + */ + rtems_id minimum_id; + + /** + * @brief This member is + * + * % + */ + rtems_id maximum_id; + + /** + * @brief This member is + * + * % + */ + uint32_t maximum; + + /** + * @brief This member is + * + * % + */ + bool auto_extend; + + /** + * @brief This member is + * + * % + */ + uint32_t unallocated; } rtems_object_api_class_information; /** - * @brief Build Object Id + * @ingroup RTEMSAPIClassicObject * - * This function returns an object id composed of the - * specified @a api, @a class, @a node, - * and @a index. + * @brief % * - * @param[in] _api indicates the api to use for the Id - * @param[in] _class indicates the class to use for the Id - * @param[in] _node indicates the node to use for the Id - * @param[in] _index indicates the index to use for the Id + * @param api % + */ +int rtems_object_api_maximum_class( int api ); + +/** + * @ingroup RTEMSAPIClassicObject * - * @retval This method returns an object Id built from the - * specified values. + * @brief % * - * @note A body is also provided. + * @param api % + */ +int rtems_object_api_minimum_class( int api ); + +/** + * @ingroup RTEMSAPIClassicObject + * + * @brief % + * + * @param _api % + * + * @param _class % + * + * @param _node % + * + * @param _index % */ #define rtems_build_id( _api, _class, _node, _index ) \ _Objects_Build_id( _api, _class, _node, _index ) /** - * @brief Build Thirty-Two Bit Object Name + * @ingroup RTEMSAPIClassicObject * - * RTEMS Object Helper -- Build an Object Id + * @brief % * - * This function returns an object name composed of the four characters - * C1, C2, C3, and C4. + * @param _C1 % * - * @param[in] _C1 is the first character of the name - * @param[in] _C2 is the second character of the name - * @param[in] _C3 is the third character of the name - * @param[in] _C4 is the fourth character of the name + * @param _C2 % * - * @note This must be implemented as a macro for use in - * Configuration Tables. A body is also provided. + * @param _C3 % * + * @param _C4 % */ #define rtems_build_name( _C1, _C2, _C3, _C4 ) \ _Objects_Build_name( _C1, _C2, _C3, _C4 ) /** - * @brief Obtain Name of Object + * @ingroup RTEMSAPIClassicObject * - * This directive returns the name associated with the specified - * object ID. + * @brief % * - * @param[in] id is the Id of the object to obtain the name of. - * @param[out] name will be set to the name of the object + * @param the_api % * - * @note The object must be have a name of the 32-bit form. - * - * @retval @a *name will contain user defined object name - * @retval @a RTEMS_SUCCESSFUL - if successful - * @retval error code - if unsuccessful + * @param the_class % */ -rtems_status_code rtems_object_get_classic_name( - rtems_id id, - rtems_name *name -); +const char *rtems_object_get_api_class_name( int the_api, int the_class ); /** - * @brief Obtain Object Name as String + * @ingroup RTEMSAPIClassicObject * - * This directive returns the name associated with the specified - * object ID. + * @brief % * - * @param[in] id is the Id of the object to obtain the name of - * @param[in] length is the length of the output name buffer - * @param[out] name will be set to the name of the object - * - * @retval @a *name will contain user defined object name - * @retval @a name - if successful - * @retval @a NULL - if unsuccessful + * @param api % */ -char *rtems_object_get_name( - rtems_id id, - size_t length, - char *name -); +const char *rtems_object_get_api_name( int api ); /** - * @brief Set Name of Object + * @ingroup RTEMSAPIClassicObject * - * This method allows the caller to set the name of an - * object. This can be used to set the name of objects - * which do not have a naming scheme per their API. + * @brief % * - * RTEMS Object Helper -- Set Name of Object as String + * @param the_api % * - * @param[in] id is the Id of the object to obtain the name of - * @param[out] name will be set to the name of the object + * @param the_class % * - * @retval @a *name will contain user defined object name - * @retval @a RTEMS_SUCCESSFUL - if successful - * @retval error code - if unsuccessful + * @param info % */ -rtems_status_code rtems_object_set_name( - rtems_id id, - const char *name +rtems_status_code rtems_object_get_class_information( + int the_api, + int the_class, + rtems_object_api_class_information *info ); /** - * @brief Get API Portion of Object Id - * - * RTEMS Object Helper -- Extract API From Id - * - * This function returns the API portion of the Id. + * @ingroup RTEMSAPIClassicObject * - * @param[in] _id is the Id of the object to obtain the API from + * @brief % * - * @retval This method returns the API portion of the provided - * @a _id. + * @param id % * - * @note This method does NOT validate the @a _id provided. - * - * @note A body is also provided. + * @param name % */ -#define rtems_object_id_get_api( _id ) \ - _Objects_Get_API( _id ) +rtems_status_code rtems_object_get_classic_name( + rtems_id id, + rtems_name *name +); /** - * @brief Get Class Portion of Object Id - * - * This function returns the class portion of the @a _id ID. - * - * @param[in] _id is the Id of the object to obtain the class from + * @ingroup RTEMSAPIClassicObject * - * @retval This method returns the class portion of the provided - * @a _id. - * - * @note This method does NOT validate the @a _id provided. - * - * @note A body is also provided. + * @brief % */ -#define rtems_object_id_get_class( _id ) \ - _Objects_Get_class( _id ) +static inline uint16_t rtems_object_get_local_node( void ) +{ + return _Objects_Local_node; +} /** - * @brief Get Node Portion of Object Id - * - * This function returns the node portion of the ID. + * @ingroup RTEMSAPIClassicObject * - * @param[in] _id is the Id of the object to obtain the node from + * @brief % * - * @retval This method returns the node portion of the provided - * @a _id. + * @param id % * - * @note This method does NOT validate the @a _id provided. + * @param length % * - * @note A body is also provided. + * @param name % */ -#define rtems_object_id_get_node( _id ) \ - _Objects_Get_node( _id ) +char *rtems_object_get_name( rtems_id id, size_t length, char *name ); /** - * @brief Get Index Portion of Object Id + * @ingroup RTEMSAPIClassicObject * - * This function returns the index portion of the ID. - * - * @param[in] _id is the Id of the object to obtain the index from - * - * @retval This method returns the index portion of the provided - * @a _id. - * - * @note This method does NOT validate the @a _id provided. - * - * @note A body is also provided. + * @brief % */ -#define rtems_object_id_get_index( _id ) \ - _Objects_Get_index( _id ) +#define rtems_object_id_api_maximum() OBJECTS_APIS_LAST /** - * @brief Get Lowest Valid API Index - * - * This method returns the lowest valid value for the API - * portion of an RTEMS object Id. + * @ingroup RTEMSAPIClassicObject * - * @retval This method returns the least valid value for - * the API portion of an RTEMS object Id. + * @brief % * - * @note A body is also provided. + * @param api % */ -#define rtems_object_id_api_minimum() \ - OBJECTS_INTERNAL_API +int rtems_object_id_api_maximum_class( int api ); /** - * @brief Get Highest Valid API Index + * @ingroup RTEMSAPIClassicObject * - * This method returns the highest valid value for the API - * portion of an RTEMS object Id. - * - * @retval This method returns the greatest valid value for - * the API portion of an RTEMS object Id. - * - * @note A body is also provided. + * @brief % */ -#define rtems_object_id_api_maximum() \ - OBJECTS_APIS_LAST +#define rtems_object_id_api_minimum() OBJECTS_INTERNAL_API /** - * @brief Get Lowest Valid Class Value - * - * This method returns the lowest valid value Class for the - * specified @a api. Each API supports a different number - * of object classes. + * @ingroup RTEMSAPIClassicObject * - * @param[in] api is the API to obtain the minimum class of - * - * @retval This method returns the least valid value for - * class number for the specified @a api. - * RTEMS Object Helper -- Get Least Valid Class for an API + * @brief % */ -int rtems_object_api_minimum_class( - int api -); +#define RTEMS_OBJECT_ID_FINAL OBJECTS_ID_FINAL /** - * @brief Get Highest Valid Class Value + * @ingroup RTEMSAPIClassicObject * - * This method returns the highest valid value Class for the - * specified @a api. Each API supports a different number - * of object classes. + * @brief % + */ +#define RTEMS_OBJECT_ID_FINAL_INDEX OBJECTS_ID_FINAL_INDEX + +/** + * @ingroup RTEMSAPIClassicObject * - * @param[in] api is the API to obtain the maximum class of + * @brief % * - * @retval This method returns the greatet valid value for - * class number for the specified @a api. + * @param _id % */ -int rtems_object_api_maximum_class( - int api -); - +#define rtems_object_id_get_api( _id ) _Objects_Get_API( _id ) /** - * @brief Get Highest Valid Class Value - * - * This method returns the lowest valid value Class for the - * specified @a api. Each API supports a different number - * of object classes. + * @ingroup RTEMSAPIClassicObject * - * @param[in] api is the API to obtain the maximum class of + * @brief % * - * @retval This method returns the least valid value for - * class number for the specified @a api. + * @param _id % */ -int rtems_object_id_api_maximum_class( - int api -); +#define rtems_object_id_get_class( _id ) _Objects_Get_class( _id ) /** - * @brief Get API Name - * - * This method returns a string containing the name of the - * specified @a api. + * @ingroup RTEMSAPIClassicObject * - * @param[in] api is the API to obtain the name of + * @brief % * - * @retval If successful, this method returns the name of - * the specified @a api. Otherwise, it returns - * the string "BAD API" + * @param _id % */ -const char *rtems_object_get_api_name( - int api -); +#define rtems_object_id_get_index( _id ) _Objects_Get_index( _id ) /** - * @brief Get Class Name + * @ingroup RTEMSAPIClassicObject * - * This method returns a string containing the name of the - * @a class from the specified @a api. + * @brief % * - * @param[in] the_api is the API for the class - * @param[in] the_class is the class to obtain the name of - * - * @retval If successful, this method returns the name of - * the specified @a class. Otherwise, it returns - * the string "BAD CLASS" + * @param _id % */ -const char *rtems_object_get_api_class_name( - int the_api, - int the_class -); +#define rtems_object_id_get_node( _id ) _Objects_Get_node( _id ) /** - * @brief Get Class Information + * @ingroup RTEMSAPIClassicObject * - * This method returns a string containing the name of the - * @a the_class from the specified @a api. + * @brief % * - * @param[in] the_api is the API for the class - * @param[in] the_class is the class to obtain information about - * @param[in] info points to the information structure to fill in + * @param _api % * - * @retval If successful, this method returns the name of - * RTEMS_SUCCESSFUL with @a *info filled in. Otherwise, - * a status is returned to indicate the error. + * @param _class % * + * @param _node % */ -rtems_status_code rtems_object_get_class_information( - int the_api, - int the_class, - rtems_object_api_class_information *info -); +#define RTEMS_OBJECT_ID_INITIAL( _api, _class, _node ) \ + OBJECTS_ID_INITIAL( _api, _class, _node ) /** - * @brief Get the local MPCI node number. + * @ingroup RTEMSAPIClassicObject * - * @return The local MPCI node number. - */ -RTEMS_INLINE_ROUTINE uint16_t rtems_object_get_local_node( void ) -{ - return _Objects_Local_node; -} - -/********************************************************************** - * CONSTANTS WHICH MAY BE USED IN OBJECT NAME TO ID SEARCHES - **********************************************************************/ - -/** - * @brief Indicates that a search is across all nodes. - */ -#define RTEMS_SEARCH_ALL_NODES OBJECTS_SEARCH_ALL_NODES - -/** - * @brief Indicates that a search is across all nodes except the one the call - * is made from. - */ -#define RTEMS_SEARCH_OTHER_NODES OBJECTS_SEARCH_OTHER_NODES - -/** - * @brief Indicates that the search is to be restricted to the local node. + * @brief % */ -#define RTEMS_SEARCH_LOCAL_NODE OBJECTS_SEARCH_LOCAL_NODE +#define RTEMS_OBJECT_ID_INITIAL_INDEX OBJECTS_ID_INITIAL_INDEX /** - * @brief Indicates that the caller wants to obtain the name of the currently - * executing thread. + * @ingroup RTEMSAPIClassicObject * - * This constant is only meaningful when obtaining the name of a task. + * @brief % */ -#define RTEMS_WHO_AM_I OBJECTS_WHO_AM_I - -/********************************************************************** - * Parameters and return Id's for _Objects_Get_next - **********************************************************************/ +#define RTEMS_SEARCH_ALL_NODES OBJECTS_SEARCH_ALL_NODES /** - * @brief Lowest valid index value for the index portion of an object - * identifier. + * @ingroup RTEMSAPIClassicObject + * + * @brief % */ -#define RTEMS_OBJECT_ID_INITIAL_INDEX OBJECTS_ID_INITIAL_INDEX +#define RTEMS_SEARCH_LOCAL_NODE OBJECTS_SEARCH_LOCAL_NODE /** - * @brief Maximum valid index value for the index portion of an object - * identifier. + * @ingroup RTEMSAPIClassicObject + * + * @brief % */ -#define RTEMS_OBJECT_ID_FINAL_INDEX OBJECTS_ID_FINAL_INDEX +#define RTEMS_SEARCH_OTHER_NODES OBJECTS_SEARCH_OTHER_NODES /** - * @brief Returns the identifier of the object with the lowest valid index - * value. + * @ingroup RTEMSAPIClassicObject * - * The object is specified by the API @a _api, the object class @a _class and - * the node @a _node where the object resides. + * @brief % + * + * @param id % + * + * @param name % */ -#define RTEMS_OBJECT_ID_INITIAL(_api, _class, _node) \ - OBJECTS_ID_INITIAL(_api, _class, _node) +rtems_status_code rtems_object_set_name( rtems_id id, const char *name ); /** - * @brief Maximum valid object identifier. + * @ingroup RTEMSAPIClassicObject + * + * @brief % */ -#define RTEMS_OBJECT_ID_FINAL OBJECTS_ID_FINAL +#define RTEMS_WHO_AM_I OBJECTS_WHO_AM_I #ifdef __cplusplus } #endif -/**@}*/ - -#endif -/* end of include file */ +#endif /* _RTEMS_RTEMS_OBJECT_H */ |