rtems/score/objectmp.h

0001 /* SPDX-License-Identifier: BSD-2-Clause */
0002
0003 /**
0004  * @file
0005  *
0006  * @ingroup RTEMSScoreObjectMP
0007  *
0008  * @brief This header file provides the interfaces of the
0009  *   @ref RTEMSScoreObjectMP.
0010  */
0011
0012 /*
0013  *  COPYRIGHT (c) 1989-2009.
0014  *  On-Line Applications Research Corporation (OAR).
0015  *
0016  * Redistribution and use in source and binary forms, with or without
0017  * modification, are permitted provided that the following conditions
0018  * are met:
0019  * 1. Redistributions of source code must retain the above copyright
0020  *    notice, this list of conditions and the following disclaimer.
0021  * 2. Redistributions in binary form must reproduce the above copyright
0022  *    notice, this list of conditions and the following disclaimer in the
0023  *    documentation and/or other materials provided with the distribution.
0024  *
0025  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
0026  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
0027  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
0028  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
0029  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
0030  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
0031  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
0032  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
0033  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
0034  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
0035  * POSSIBILITY OF SUCH DAMAGE.
0036  */
0037
0038 #ifndef _RTEMS_SCORE_OBJECTMP_H
0039 #define _RTEMS_SCORE_OBJECTMP_H
0040
0041 #ifndef _RTEMS_SCORE_OBJECTIMPL_H
0042 # error "Never use <rtems/rtems/objectmp.h> directly; include <rtems/rtems/objectimpl.h> instead."
0043 #endif
0044
0045 #include <rtems/score/chainimpl.h>
0046
0047 #ifdef __cplusplus
0048 extern "C" {
0049 #endif
0050
0051 /**
0052  * @defgroup RTEMSScoreObjectMP Object Handler Multiprocessing (MP) Support
0053  *
0054  * @ingroup RTEMSScoreObject
0055  *
0056  * @brief This group contains the implementation to support the Object Handler
0057  *   in multiprocessing (MP) configurations.
0058  *
0059  * This handler encapsulates functionality which is used to manage
0060  * objects which have been declared to be globally visible.  This handler
0061  * knows objects from all of the nodes in the system.
0062  *
0063  * @{
0064  */
0065
0066 /**
0067  * @brief Intializes the inactive global object chain
0068  * based on the maximum number of global objects configured.
0069  *
0070  * This routine intializes the inactive global object chain
0071  * based on the maximum number of global objects configured.
0072  */
0073 void _Objects_MP_Handler_initialization(void);
0074
0075 /**
0076  * @brief Intializes the global object node number
0077  * used in the ID field of all objects.
0078  *
0079  * This routine intializes the global object node number
0080  * used in the ID field of all objects.
0081  */
0082 void _Objects_MP_Handler_early_initialization(void);
0083
0084 /**
0085  * @brief Place the specified global object in the
0086  * specified information table.
0087  *
0088  * This routine place the specified global object in the
0089  * specified information table.
0090  *
0091  * @param[in, out] information Points to the object information table for this
0092  *            object class.
0093  * @param[in, out] the_global_object Points to the object being opened.
0094  * @param the_name The name of the object being opened.
0095  * @param the_id The Id of the object being opened.
0096  *
0097  * @todo This method only works for object types with 4 byte object names.
0098  *       It does not support variable length object names.
0099  */
0100 void _Objects_MP_Open (
0101   Objects_Information *information,
0102   Objects_MP_Control  *the_global_object,
0103   uint32_t             the_name,
0104   Objects_Id           the_id
0105 );
0106
0107 /**
0108  * @brief  Allocates a global object control block
0109  * and places it in the specified information table.
0110  *
0111  * This routine allocates a global object control block
0112  * and places it in the specified information table.  If the
0113  * allocation fails, then is_fatal_error determines the
0114  * error processing actions taken.
0115  *
0116  * @param[in, out] information Points to the object information table for this
0117  *            object class.
0118  * @param the_name The name of the object being opened.
0119  * @param the_id The Id of the object being opened.
0120  * @param is_fatal_error Indicates whether not being able to allocate the
0121  *            object is considered a fatal error.
0122  *
0123  * @retval true The operation succeeded.
0124  * @retval false The allocation failed, but @a is_fatal_error was set to false.
0125  *
0126  * @todo This method only works for object types with 4 byte object names.
0127  *       It does not support variable length object names.
0128  */
0129 bool _Objects_MP_Allocate_and_open (
0130   Objects_Information *information,
0131   uint32_t             the_name,
0132   Objects_Id           the_id,
0133   bool                 is_fatal_error
0134 );
0135
0136 /**
0137  * @brief Removes a global object from the specified information table.
0138  *
0139  * This routine removes a global object from the specified
0140  * information table and deallocates the global object control block.
0141  *
0142  * @param[in, out] information Points to the object information table for this
0143  *            object class.
0144  * @param the_id The id of the global object to remove.
0145  */
0146 void _Objects_MP_Close (
0147   Objects_Information *information,
0148   Objects_Id           the_id
0149 );
0150
0151 /**
0152  * @brief Looks for the object with the_name in the global
0153  * object tables indicated by information.
0154  *
0155  * This routine looks for the object with the_name in the global
0156  * object tables indicated by information.  It returns the ID of the
0157  * object with that name if one is found.
0158  *
0159  * @param information Points to the object information table for this
0160  *            object class.
0161  * @param the_name The name of the object being searched for.
0162  * @param nodes_to_search Indicates the set of nodes to search.
0163  * @param[out] the_id will contain the Id of the object if found.
0164  *
0165  * @retval STATUS_SUCCESSFUL The lookup was successful.
0166  * @retval STATUS_INVALID_NODE The number of nodes is bigger than the
0167  *      objects maximum nodes value.
0168  * @retval STATUS_INVALID_NAME There is no global object with this name.
0169  */
0170 Status_Control _Objects_MP_Global_name_search (
0171   const Objects_Information *information,
0172   Objects_Name               the_name,
0173   uint32_t                   nodes_to_search,
0174   Objects_Id                *the_id
0175 );
0176
0177 /**
0178  * @brief Checks if the object identifier is in the global object
0179  * identifier cache of the specified object information.
0180  *
0181  * @param id The object identifier.
0182  * @param information The object information.
0183  *
0184  * @retval true A remote objects with this object identifier exists in the
0185  * global object identifier cache of the specified information.
0186  * @retval false A remote objects with this object identifier does not exist in the
0187  * global object identifier cache of the specified information.
0188  */
0189 bool _Objects_MP_Is_remote(
0190   Objects_Id                 id,
0191   const Objects_Information *information
0192 );
0193
0194 /**
0195  *  This is the maximum number of global objects configured.
0196  */
0197 extern uint32_t _Objects_MP_Maximum_global_objects;
0198
0199 /**
0200  * @brief This function allocates a Global Object control block.
0201  */
0202 Objects_MP_Control *_Objects_MP_Allocate_global_object( void );
0203
0204 /**
0205  * @brief This routine deallocates a Global Object control block.
0206  *
0207  * @param[out] the_object The object to deallocate.
0208  */
0209 void _Objects_MP_Free_global_object( Objects_MP_Control *the_object );
0210
0211 /** @} */
0212
0213 #ifdef __cplusplus
0214 }
0215 #endif
0216
0217 #endif
0218 /* end of include file */