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 */