LCOV - code coverage report
Current view: top level - cfe/modules/core_api/fsw/inc - cfe_resourceid.h (source / functions) Hit Total Coverage
Test: coverage_total.info Lines: 2 2 100.0 %
Date: 2023-08-28 16:42:09 Functions: 1 1 100.0 %
Branches: 0 0 -

           Branch data     Line data    Source code
       1                 :            : /************************************************************************
       2                 :            :  * NASA Docket No. GSC-18,719-1, and identified as “core Flight System: Bootes”
       3                 :            :  *
       4                 :            :  * Copyright (c) 2020 United States Government as represented by the
       5                 :            :  * Administrator of the National Aeronautics and Space Administration.
       6                 :            :  * All Rights Reserved.
       7                 :            :  *
       8                 :            :  * Licensed under the Apache License, Version 2.0 (the "License"); you may
       9                 :            :  * not use this file except in compliance with the License. You may obtain
      10                 :            :  * a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
      11                 :            :  *
      12                 :            :  * Unless required by applicable law or agreed to in writing, software
      13                 :            :  * distributed under the License is distributed on an "AS IS" BASIS,
      14                 :            :  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      15                 :            :  * See the License for the specific language governing permissions and
      16                 :            :  * limitations under the License.
      17                 :            :  ************************************************************************/
      18                 :            : 
      19                 :            : /**
      20                 :            :  * @file
      21                 :            :  *
      22                 :            :  * Contains global prototypes and definitions related to resource
      23                 :            :  * management and related CFE resource IDs.
      24                 :            :  *
      25                 :            :  * A CFE ES Resource ID is a common way to identify CFE-managed resources such
      26                 :            :  * as apps, tasks, counters, memory pools, CDS blocks, and other entities.
      27                 :            :  *
      28                 :            :  * Simple operations are provided as inline functions, which
      29                 :            :  * should alleviate the need to do direct manipulation of resource IDs:
      30                 :            :  *
      31                 :            :  *  - Check for undefined ID value
      32                 :            :  *  - Check for equality of two ID values
      33                 :            :  *  - Convert ID to simple integer (typically for printing/logging)
      34                 :            :  *  - Convert simple integer to ID (inverse of above)
      35                 :            :  */
      36                 :            : 
      37                 :            : #ifndef CFE_RESOURCEID_H
      38                 :            : #define CFE_RESOURCEID_H
      39                 :            : 
      40                 :            : /*
      41                 :            :  * The basic resource ID API definitions
      42                 :            :  */
      43                 :            : #include "cfe_resourceid_api_typedefs.h"
      44                 :            : 
      45                 :            : /** \name Resource ID test/conversion macros and inline functions */
      46                 :            : /** \{ */
      47                 :            : 
      48                 :            : /**
      49                 :            :  * \brief Convert a derived (app-specific) ID directly into an "unsigned long"
      50                 :            :  *
      51                 :            :  * This generic routine is implemented as a macro so it is agnostic to the actual argument type,
      52                 :            :  * and it will evaluate correctly so long as the argument type is based on the CFE_RESOURCEID_BASE_TYPE.
      53                 :            :  *
      54                 :            :  * There is no inverse of this macro, as it depends on the actual derived type desired.
      55                 :            :  * Applications needing to recreate an ID from an integer should use CFE_ResourceId_FromInteger()
      56                 :            :  * combined with a cast/conversion to the correct/intended derived type, as needed.
      57                 :            :  *
      58                 :            :  * \note This evaluates as an "unsigned long" such that it can be used in
      59                 :            :  * printf()-style functions with the "%lx" modifier without extra casting,
      60                 :            :  * as this is the most typical use-case for representing an ID as an integer.
      61                 :            :  */
      62                 :            : #define CFE_RESOURCEID_TO_ULONG(id) CFE_ResourceId_ToInteger(CFE_RESOURCEID_UNWRAP(id))
      63                 :            : 
      64                 :            : /**
      65                 :            :  * \brief Determine if a derived (app-specific) ID is defined or not
      66                 :            :  *
      67                 :            :  * This generic routine is implemented as a macro so it is agnostic to the actual argument type,
      68                 :            :  * and it will evaluate correctly so long as the argument type is based on the CFE_RESOURCEID_BASE_TYPE.
      69                 :            :  */
      70                 :            : #define CFE_RESOURCEID_TEST_DEFINED(id) CFE_ResourceId_IsDefined(CFE_RESOURCEID_UNWRAP(id))
      71                 :            : 
      72                 :            : /**
      73                 :            :  * \brief Determine if two derived (app-specific) IDs are equal
      74                 :            :  *
      75                 :            :  * This generic routine is implemented as a macro so it is agnostic to the actual argument type,
      76                 :            :  * and it will evaluate correctly so long as the argument type is based on the CFE_RESOURCEID_BASE_TYPE.
      77                 :            :  */
      78                 :            : #define CFE_RESOURCEID_TEST_EQUAL(id1, id2) CFE_ResourceId_Equal(CFE_RESOURCEID_UNWRAP(id1), CFE_RESOURCEID_UNWRAP(id2))
      79                 :            : 
      80                 :            : /**
      81                 :            :  * @brief Convert a resource ID to an integer.
      82                 :            :  *
      83                 :            :  * This is primarily intended for logging purposes, such was writing
      84                 :            :  * to debug console, event messages, or log files, using printf-like APIs.
      85                 :            :  *
      86                 :            :  * For compatibility with C library APIs, this returns an "unsigned long"
      87                 :            :  * type and should be used with the "%lx" format specifier in a printf
      88                 :            :  * format string.
      89                 :            :  *
      90                 :            :  * @note No assumptions should be made about the actual integer value,
      91                 :            :  * such as its base/range.  It may be printed, but should not be modified
      92                 :            :  * or tested/compared using other arithmetic ops, and should never be used
      93                 :            :  * as the index to an array or table.  See the related function
      94                 :            :  * CFE_ResourceId_ToIndex() for cases where a zero-based array/table index
      95                 :            :  * is needed.
      96                 :            :  *
      97                 :            :  * @sa CFE_ResourceId_FromInteger()
      98                 :            :  *
      99                 :            :  * @param[in]   id    Resource ID to convert
     100                 :            :  * @returns Integer value corresponding to ID
     101                 :            :  */
     102                 :          5 : static inline unsigned long CFE_ResourceId_ToInteger(CFE_ResourceId_t id)
     103                 :            : {
     104                 :          5 :     return (unsigned long)CFE_RESOURCEID_UNWRAP(id);
     105                 :            : }
     106                 :            : 
     107                 :            : /**
     108                 :            :  * @brief Convert an integer to a resource ID.
     109                 :            :  *
     110                 :            :  * This is the inverse of CFE_ResourceId_ToInteger(), and reconstitutes
     111                 :            :  * the original CFE_ResourceId_t value from the integer representation.
     112                 :            :  *
     113                 :            :  * This may be used, for instance, where an ID value is parsed from a text
     114                 :            :  * file or message using C library APIs such as scanf() or strtoul().
     115                 :            :  *
     116                 :            :  * @sa CFE_ResourceId_ToInteger()
     117                 :            :  *
     118                 :            :  * @param[in]   Value    Integer value to convert
     119                 :            :  * @returns ID value corresponding to integer
     120                 :            :  */
     121                 :            : static inline CFE_ResourceId_t CFE_ResourceId_FromInteger(unsigned long Value)
     122                 :            : {
     123                 :            :     return (CFE_ResourceId_t)CFE_RESOURCEID_WRAP(Value);
     124                 :            : }
     125                 :            : 
     126                 :            : /**
     127                 :            :  * @brief Compare two Resource ID values for equality
     128                 :            :  *
     129                 :            :  * @param[in]   id1    Resource ID to check
     130                 :            :  * @param[in]   id2    Resource ID to check
     131                 :            :  * @returns true if id1 and id2 are equal, false otherwise.
     132                 :            :  */
     133                 :            : static inline bool CFE_ResourceId_Equal(CFE_ResourceId_t id1, CFE_ResourceId_t id2)
     134                 :            : {
     135                 :            :     return (CFE_RESOURCEID_UNWRAP(id1) == CFE_RESOURCEID_UNWRAP(id2));
     136                 :            : }
     137                 :            : 
     138                 :            : /**
     139                 :            :  * @brief Check if a resource ID value is defined
     140                 :            :  *
     141                 :            :  * The constant #CFE_RESOURCEID_UNDEFINED represents an undefined ID value,
     142                 :            :  * such that the expression:
     143                 :            :  *
     144                 :            :  *      CFE_ResourceId_IsDefined(CFE_RESOURCEID_UNDEFINED)
     145                 :            :  *
     146                 :            :  * Always returns false.
     147                 :            :  *
     148                 :            :  * @param[in]   id    Resource ID to check
     149                 :            :  * @returns True if the ID may refer to a defined entity, false if invalid/undefined.
     150                 :            :  */
     151                 :            : static inline bool CFE_ResourceId_IsDefined(CFE_ResourceId_t id)
     152                 :            : {
     153                 :            :     return (!CFE_ResourceId_Equal(id, CFE_RESOURCEID_UNDEFINED));
     154                 :            : }
     155                 :            : 
     156                 :            : /** \} */
     157                 :            : 
     158                 :            : /*
     159                 :            :  * Non-inline API functions provided by the Resource ID module
     160                 :            :  */
     161                 :            : 
     162                 :            : /**
     163                 :            :  * @brief Get the Base value (type/category) from a resource ID value
     164                 :            :  *
     165                 :            :  * This masks out the ID serial number to obtain the base value, which is different
     166                 :            :  * for each resource type.
     167                 :            :  *
     168                 :            :  * @note The value is NOT shifted or otherwise adjusted.
     169                 :            :  *
     170                 :            :  * @param[in]   ResourceId   the resource ID to decode
     171                 :            :  * @returns     The base value associated with that ID
     172                 :            :  */
     173                 :            : uint32 CFE_ResourceId_GetBase(CFE_ResourceId_t ResourceId);
     174                 :            : 
     175                 :            : /**
     176                 :            :  * @brief Get the Serial Number (sequential ID) from a resource ID value
     177                 :            :  *
     178                 :            :  * This masks out the ID base value to obtain the serial number, which is different
     179                 :            :  * for each entity created.
     180                 :            :  *
     181                 :            :  * @param[in]   ResourceId   the resource ID to decode
     182                 :            :  * @returns     The serial number associated with that ID
     183                 :            :  */
     184                 :            : uint32 CFE_ResourceId_GetSerial(CFE_ResourceId_t ResourceId);
     185                 :            : 
     186                 :            : /**
     187                 :            :  * @brief Locate the next resource ID which does not map to an in-use table entry
     188                 :            :  *
     189                 :            :  * This begins searching from StartId which should be the most recently issued ID
     190                 :            :  * for the resource category.  This will then search for the next ID which does
     191                 :            :  * _not_ map to a table entry that is in use.  That is, it does not alias any
     192                 :            :  * valid ID when converted to an array index.
     193                 :            :  *
     194                 :            :  * returns an undefined ID value if no open slots are available
     195                 :            :  *
     196                 :            :  * @param[in]   StartId   the last issued ID for the resource category (app, lib, etc).
     197                 :            :  * @param[in]   TableSize the maximum size of the target table
     198                 :            :  * @param[in]   CheckFunc a function to check if the given ID is available
     199                 :            :  * @returns     Next ID value which does not map to a valid entry
     200                 :            :  * @retval      #CFE_RESOURCEID_UNDEFINED if no open slots or bad arguments.
     201                 :            :  *
     202                 :            :  */
     203                 :            : CFE_ResourceId_t CFE_ResourceId_FindNext(CFE_ResourceId_t StartId, uint32 TableSize,
     204                 :            :                                          bool (*CheckFunc)(CFE_ResourceId_t));
     205                 :            : 
     206                 :            : /**
     207                 :            :  * @brief Internal routine to aid in converting an ES resource ID to an array index
     208                 :            : 
     209                 :            :  * @param[in]  Id        The resource ID
     210                 :            :  * @param[in]  BaseValue The respective ID base value corresponding to the ID type
     211                 :            :  * @param[in]  TableSize The actual size of the internal table (MAX index value + 1)
     212                 :            :  * @param[out] Idx       The output index
     213                 :            :  *
     214                 :            :  * @return Execution status, see @ref CFEReturnCodes
     215                 :            :  * @retval #CFE_SUCCESS                     @copybrief CFE_SUCCESS
     216                 :            :  * @retval #CFE_ES_BAD_ARGUMENT             @copybrief CFE_ES_BAD_ARGUMENT
     217                 :            :  * @retval #CFE_ES_ERR_RESOURCEID_NOT_VALID @copybrief CFE_ES_ERR_RESOURCEID_NOT_VALID
     218                 :            :  */
     219                 :            : int32 CFE_ResourceId_ToIndex(CFE_ResourceId_t Id, uint32 BaseValue, uint32 TableSize, uint32 *Idx);
     220                 :            : 
     221                 :            : #endif /* CFE_RESOURCEID_H */

Generated by: LCOV version 1.14