diff --git a/.gitignore b/.gitignore index 637b047dc..2e7fd18f3 100644 --- a/.gitignore +++ b/.gitignore @@ -35,3 +35,15 @@ !modules/es/fsw/** !modules/es/CMakeLists.txt + + +# ResourceID + +!modules/core_api/fsw/inc/cfe_resourceid* + +!modules/core_private/fsw/inc/cfe_core_resourceid_basevalues.h + +!modules/resourceid/fsw/src/* +!modules/resourceid/option_inc/* +!modules/resourceid/CMakeLists.txt +!modules/resourceid/mission_build.cmake diff --git a/modules/core_api/fsw/inc/cfe_resourceid.h b/modules/core_api/fsw/inc/cfe_resourceid.h new file mode 100644 index 000000000..428db8b68 --- /dev/null +++ b/modules/core_api/fsw/inc/cfe_resourceid.h @@ -0,0 +1,219 @@ +/* +** GSC-18128-1, "Core Flight Executive Version 6.7" +** +** Copyright (c) 2006-2019 United States Government as represented by +** the Administrator of the National Aeronautics and Space Administration. +** All Rights Reserved. +** +** Licensed under the Apache License, Version 2.0 (the "License"); +** you may not use this file except in compliance with the License. +** You may obtain a copy of the License at +** +** http://www.apache.org/licenses/LICENSE-2.0 +** +** Unless required by applicable law or agreed to in writing, software +** distributed under the License is distributed on an "AS IS" BASIS, +** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +** See the License for the specific language governing permissions and +** limitations under the License. +*/ + +/** + * @file + * + * Contains global prototypes and definitions related to resource + * management and related CFE resource IDs. + * + * A CFE ES Resource ID is a common way to identify CFE-managed resources such + * as apps, tasks, counters, memory pools, CDS blocks, and other entities. + * + * Simple operations are provided as inline functions, which + * should alleviate the need to do direct manipulation of resource IDs: + * + * - Check for undefined ID value + * - Check for equality of two ID values + * - Convert ID to simple integer (typically for printing/logging) + * - Convert simple integer to ID (inverse of above) + */ + +#ifndef CFE_RESOURCEID_H +#define CFE_RESOURCEID_H + +/* + * The basic resource ID API definitions + */ +#include "cfe_resourceid_api_typedefs.h" + +/** \name Resource ID test/conversion macros and inline functions */ +/** \{ */ + +/** + * \brief Convert a derived (app-specific) ID directly into an "unsigned long" + * + * This generic routine is implemented as a macro so it is agnostic to the actual argument type, + * and it will evaluate correctly so long as the argument type is based on the CFE_RESOURCEID_BASE_TYPE. + * + * There is no inverse of this macro, as it depends on the actual derived type desired. + * Applications needing to recreate an ID from an integer should use CFE_ResourceId_FromInteger() + * combined with a cast/conversion to the correct/intended derived type, as needed. + * + * \note This evaluates as an "unsigned long" such that it can be used in + * printf()-style functions with the "%lx" modifier without extra casting, + * as this is the most typical use-case for representing an ID as an integer. + */ +#define CFE_RESOURCEID_TO_ULONG(id) CFE_ResourceId_ToInteger(CFE_RESOURCEID_UNWRAP(id)) + +/** + * \brief Determine if a derived (app-specific) ID is defined or not + * + * This generic routine is implemented as a macro so it is agnostic to the actual argument type, + * and it will evaluate correctly so long as the argument type is based on the CFE_RESOURCEID_BASE_TYPE. + */ +#define CFE_RESOURCEID_TEST_DEFINED(id) CFE_ResourceId_IsDefined(CFE_RESOURCEID_UNWRAP(id)) + +/** + * \brief Determine if two derived (app-specific) IDs are equal + * + * This generic routine is implemented as a macro so it is agnostic to the actual argument type, + * and it will evaluate correctly so long as the argument type is based on the CFE_RESOURCEID_BASE_TYPE. + */ +#define CFE_RESOURCEID_TEST_EQUAL(id1, id2) CFE_ResourceId_Equal(CFE_RESOURCEID_UNWRAP(id1), CFE_RESOURCEID_UNWRAP(id2)) + +/** + * @brief Convert a resource ID to an integer. + * + * This is primarily intended for logging purposes, such was writing + * to debug console, event messages, or log files, using printf-like APIs. + * + * For compatibility with C library APIs, this returns an "unsigned long" + * type and should be used with the "%lx" format specifier in a printf + * format string. + * + * @note No assumptions should be made about the actual integer value, + * such as its base/range. It may be printed, but should not be modified + * or tested/compared using other arithmetic ops, and should never be used + * as the index to an array or table. See the related function + * CFE_ResourceId_ToIndex() for cases where a zero-based array/table index + * is needed. + * + * @sa CFE_ResourceId_FromInteger() + * + * @param[in] id Resource ID to convert + * @returns Integer value corresponding to ID + */ +static inline unsigned long CFE_ResourceId_ToInteger(CFE_ResourceId_t id) +{ + return ((unsigned long)CFE_RESOURCEID_UNWRAP(id)); +} + +/** + * @brief Convert an integer to a resource ID. + * + * This is the inverse of CFE_ResourceId_ToInteger(), and reconstitutes + * the original CFE_ResourceId_t value from the integer representation. + * + * This may be used, for instance, where an ID value is parsed from a text + * file or message using C library APIs such as scanf() or strtoul(). + * + * @sa CFE_ResourceId_ToInteger() + * + * @param[in] Value Integer value to convert + * @returns ID value corresponding to integer + */ +static inline CFE_ResourceId_t CFE_ResourceId_FromInteger(unsigned long Value) +{ + return ((CFE_ResourceId_t)CFE_RESOURCEID_WRAP(Value)); +} + +/** + * @brief Compare two Resource ID values for equality + * + * @param[in] id1 Resource ID to check + * @param[in] id2 Resource ID to check + * @returns true if id1 and id2 are equal, false otherwise. + */ +static inline bool CFE_ResourceId_Equal(CFE_ResourceId_t id1, CFE_ResourceId_t id2) +{ + return (CFE_RESOURCEID_UNWRAP(id1) == CFE_RESOURCEID_UNWRAP(id2)); +} + +/** + * @brief Check if a resource ID value is defined + * + * The constant #CFE_RESOURCEID_UNDEFINED represents an undefined ID value, + * such that the expression: + * + * CFE_ResourceId_IsDefined(CFE_RESOURCEID_UNDEFINED) + * + * Always returns false. + * + * @param[in] id Resource ID to check + * @returns True if the ID may refer to a defined entity, false if invalid/undefined. + */ +static inline bool CFE_ResourceId_IsDefined(CFE_ResourceId_t id) +{ + return (CFE_RESOURCEID_UNWRAP(id) != 0); +} + +/** \} */ + +/* + * Non-inline API functions provided by the Resource ID module + */ + +/** + * @brief Get the Base value (type/category) from a resource ID value + * + * This masks out the ID serial number to obtain the base value, which is different + * for each resource type. + * + * @note The value is NOT shifted or otherwise adjusted. + * + * @param[in] ResourceId the resource ID to decode + * @returns The base value associated with that ID + */ +extern uint32 CFE_ResourceId_GetBase(CFE_ResourceId_t ResourceId); + +/** + * @brief Get the Serial Number (sequential ID) from a resource ID value + * + * This masks out the ID base value to obtain the serial number, which is different + * for each entity created. + * + * @param[in] ResourceId the resource ID to decode + * @returns The serial number associated with that ID + */ +extern uint32 CFE_ResourceId_GetSerial(CFE_ResourceId_t ResourceId); + +/** + * @brief Locate the next resource ID which does not map to an in-use table entry + * + * This begins searching from StartId which should be the most recently issued ID + * for the resource category. This will then search for the next ID which does + * _not_ map to a table entry that is in use. That is, it does not alias any + * valid ID when converted to an array index. + * + * returns an undefined ID value if no open slots are available + * + * @param[in] StartId the last issued ID for the resource category (app, lib, etc). + * @param[in] TableSize the maximum size of the target table + * @param[in] CheckFunc a function to check if the given ID is available + * @returns Next ID value which does not map to a valid entry + * @retval #CFE_RESOURCEID_UNDEFINED if no open slots. + * + */ +extern CFE_ResourceId_t CFE_ResourceId_FindNext(CFE_ResourceId_t StartId, uint32 TableSize, + bool (*CheckFunc)(CFE_ResourceId_t)); + +/** + * @brief Internal routine to aid in converting an ES resource ID to an array index + + * @param[in] Id The resource ID + * @param[in] BaseValue The respective ID base value corresponding to the ID type + * @param[in] TableSize The actual size of the internal table (MAX index value + 1) + * @param[out] Idx The output index + * @returns Status code, CFE_SUCCESS if successful. + */ +extern int32 CFE_ResourceId_ToIndex(CFE_ResourceId_t Id, uint32 BaseValue, uint32 TableSize, uint32 *Idx); + +#endif /* CFE_RESOURCEID_H */ diff --git a/modules/core_api/fsw/inc/cfe_resourceid_api_typedefs.h b/modules/core_api/fsw/inc/cfe_resourceid_api_typedefs.h new file mode 100644 index 000000000..2afdf8dd2 --- /dev/null +++ b/modules/core_api/fsw/inc/cfe_resourceid_api_typedefs.h @@ -0,0 +1,80 @@ +/* +** GSC-18128-1, "Core Flight Executive Version 6.7" +** +** Copyright (c) 2006-2019 United States Government as represented by +** the Administrator of the National Aeronautics and Space Administration. +** All Rights Reserved. +** +** Licensed under the Apache License, Version 2.0 (the "License"); +** you may not use this file except in compliance with the License. +** You may obtain a copy of the License at +** +** http://www.apache.org/licenses/LICENSE-2.0 +** +** Unless required by applicable law or agreed to in writing, software +** distributed under the License is distributed on an "AS IS" BASIS, +** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +** See the License for the specific language governing permissions and +** limitations under the License. +*/ + +/** + * @file + * + * Contains global prototypes and definitions related to resource + * management and related CFE resource IDs. + * + * A CFE ES Resource ID is a common way to identify CFE-managed resources such + * as apps, tasks, counters, memory pools, CDS blocks, and other entities. + * + * Simple operations are provided as inline functions, which + * should alleviate the need to do direct manipulation of resource IDs: + * + * - Check for undefined ID value + * - Check for equality of two ID values + * - Convert ID to simple integer (typically for printing/logging) + * - Convert simple integer to ID (inverse of above) + */ + +#ifndef CFE_RESOURCEID_API_TYPEDEFS_H +#define CFE_RESOURCEID_API_TYPEDEFS_H + +/* + * The basic resource ID typedef + * + * This is provided via the external resourceid library + * and may be customized by the user/mission preferences. + */ +#include "cfe_resourceid_typedef.h" + +/* +** Defines +*/ + +/** \name Resource ID predefined values */ +/** \{ */ + +/** + * @brief A resource ID value that represents an undefined/unused resource + * + * This constant may be used to initialize local variables of the + * CFE_ResourceId_t type to a safe value that will not alias a valid ID. + * + * By design, this value is also the result of zeroing a CFE_ResourceId_t + * type via standard functions like memset(), such that objects initialized + * using this method will also be set to safe values. + */ +#define CFE_RESOURCEID_UNDEFINED ((CFE_ResourceId_t)CFE_RESOURCEID_WRAP(0)) + +/** + * @brief A resource ID value that represents a reserved entry + * + * This is not a valid value for any resource type, but is used to mark + * table entries that are not available for use. For instance, this may + * be used while setting up an entry initially. + */ +#define CFE_RESOURCEID_RESERVED ((CFE_ResourceId_t)CFE_RESOURCEID_WRAP(0xFFFFFFFF)) + +/** \} */ + +#endif /* CFE_RESOURCEID_API_TYPEDEFS_H */ diff --git a/modules/core_private/fsw/inc/cfe_core_resourceid_basevalues.h b/modules/core_private/fsw/inc/cfe_core_resourceid_basevalues.h new file mode 100644 index 000000000..a1289b5e0 --- /dev/null +++ b/modules/core_private/fsw/inc/cfe_core_resourceid_basevalues.h @@ -0,0 +1,95 @@ +/* +** GSC-18128-1, "Core Flight Executive Version 6.7" +** +** Copyright (c) 2006-2019 United States Government as represented by +** the Administrator of the National Aeronautics and Space Administration. +** All Rights Reserved. +** +** Licensed under the Apache License, Version 2.0 (the "License"); +** you may not use this file except in compliance with the License. +** You may obtain a copy of the License at +** +** http://www.apache.org/licenses/LICENSE-2.0 +** +** Unless required by applicable law or agreed to in writing, software +** distributed under the License is distributed on an "AS IS" BASIS, +** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +** See the License for the specific language governing permissions and +** limitations under the License. +*/ + +/** + * @file + * + * Contains CFE internal prototypes and definitions related to resource + * management and related CFE resource IDs. + * + * A CFE ES Resource ID is a common way to identify CFE-managed resources such + * as apps, tasks, counters, memory pools, CDS blocks, and other entities. + */ + +#ifndef CFE_CORE_RESOURCEID_BASEVALUES_H +#define CFE_CORE_RESOURCEID_BASEVALUES_H + +/* +** Include Files +*/ +#include "cfe_resourceid_basevalue.h" + +/** @defgroup CFEESResourceIDBase cFE Resource ID base values + * @{ + */ + +/* + * Assign unique offsets per resource types used in CFE core apps. + * + * Applications should not use these values directly, but rather + * in conjuction with the CFE_RESOURCEID_MAKE_BASE macro provided + * by the Resource ID module. (see below) + */ +enum +{ + /* + * Note for Task ID base value -- + * This currently shares the same offset as OSAL tasks, such that + * when "simple" (non-enforcing/backward-compatible) IDs are selected, + * the CFE task IDs and the OSAL task IDs end up as the same value. + * + * The "CFE_RESOURCEID_MARK" bit still differentiates the value when + * in strict mode, so there is no overlap in that case. + */ + CFE_RESOURCEID_ES_TASKID_BASE_OFFSET = OS_OBJECT_TYPE_OS_TASK, + + /* Other ES managed resources */ + CFE_RESOURCEID_ES_APPID_BASE_OFFSET = OS_OBJECT_TYPE_USER + 1, + CFE_RESOURCEID_ES_LIBID_BASE_OFFSET = OS_OBJECT_TYPE_USER + 2, + CFE_RESOURCEID_ES_COUNTID_BASE_OFFSET = OS_OBJECT_TYPE_USER + 3, + CFE_RESOURCEID_ES_POOLID_BASE_OFFSET = OS_OBJECT_TYPE_USER + 4, + CFE_RESOURCEID_ES_CDSBLOCKID_BASE_OFFSET = OS_OBJECT_TYPE_USER + 5, + + /* SB managed resources */ + CFE_RESOURCEID_SB_PIPEID_RESOURCE_BASE_OFFSET = OS_OBJECT_TYPE_USER + 6 +}; + +/* + * Assign actual base values from the offsets above + * + * Using "enum" ensures these are resolved as integers now, as opposed at to the point of use like macros. + */ +enum +{ + /* ES managed resources */ + CFE_ES_TASKID_BASE = CFE_RESOURCEID_MAKE_BASE(CFE_RESOURCEID_ES_TASKID_BASE_OFFSET), + CFE_ES_APPID_BASE = CFE_RESOURCEID_MAKE_BASE(CFE_RESOURCEID_ES_APPID_BASE_OFFSET), + CFE_ES_LIBID_BASE = CFE_RESOURCEID_MAKE_BASE(CFE_RESOURCEID_ES_LIBID_BASE_OFFSET), + CFE_ES_COUNTID_BASE = CFE_RESOURCEID_MAKE_BASE(CFE_RESOURCEID_ES_COUNTID_BASE_OFFSET), + CFE_ES_POOLID_BASE = CFE_RESOURCEID_MAKE_BASE(CFE_RESOURCEID_ES_POOLID_BASE_OFFSET), + CFE_ES_CDSBLOCKID_BASE = CFE_RESOURCEID_MAKE_BASE(CFE_RESOURCEID_ES_CDSBLOCKID_BASE_OFFSET), + + /* SB managed resources */ + CFE_SB_PIPEID_BASE = CFE_RESOURCEID_MAKE_BASE(CFE_RESOURCEID_SB_PIPEID_RESOURCE_BASE_OFFSET) +}; + +/** @} */ + +#endif /* CFE_CORE_RESOURCEID_BASEVALUES_H */ diff --git a/modules/resourceid/CMakeLists.txt b/modules/resourceid/CMakeLists.txt new file mode 100644 index 000000000..34e568bb8 --- /dev/null +++ b/modules/resourceid/CMakeLists.txt @@ -0,0 +1,20 @@ +################################################################## +# +# cFE resource ID module CMake build recipe +# +################################################################## + +project(CFE_RESOURCEID C) + +# Module library +set(resourceid_SOURCES + ${CMAKE_CURRENT_SOURCE_DIR}/fsw/src/cfe_resourceid_api.c +) +add_library(resourceid STATIC ${resourceid_SOURCES}) + +target_link_libraries(resourceid PRIVATE core_private) + +# Add unit test coverage subdirectory +if(ENABLE_UNIT_TESTS) + add_subdirectory(ut-coverage) +endif(ENABLE_UNIT_TESTS) diff --git a/modules/resourceid/fsw/src/cfe_resourceid_api.c b/modules/resourceid/fsw/src/cfe_resourceid_api.c new file mode 100644 index 000000000..b05e4ab70 --- /dev/null +++ b/modules/resourceid/fsw/src/cfe_resourceid_api.c @@ -0,0 +1,133 @@ +/* +** GSC-18128-1, "Core Flight Executive Version 6.7" +** +** Copyright (c) 2006-2019 United States Government as represented by +** the Administrator of the National Aeronautics and Space Administration. +** All Rights Reserved. +** +** Licensed under the Apache License, Version 2.0 (the "License"); +** you may not use this file except in compliance with the License. +** You may obtain a copy of the License at +** +** http://www.apache.org/licenses/LICENSE-2.0 +** +** Unless required by applicable law or agreed to in writing, software +** distributed under the License is distributed on an "AS IS" BASIS, +** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +** See the License for the specific language governing permissions and +** limitations under the License. +*/ + +/* +** File: +** cfe_resource_api.c +** +** Purpose: +** Function definitions related to CFE resource management +** +** References: +** Flight Software Branch C Coding Standard Version 1.0a +** cFE Flight Software Application Developers Guide +*/ + +/* +** Includes +*/ +#include +#include +#include + +#include "cfe.h" +#include "cfe_resourceid.h" +#include "cfe_resourceid_basevalue.h" + +/*********************************************************************/ +/* + * CFE_ResourceId_GetBase + * + * For complete API information, see prototype in header + */ +uint32 CFE_ResourceId_GetBase(CFE_ResourceId_t ResourceId) +{ + return (CFE_ResourceId_ToInteger(ResourceId) & ~((uint32)CFE_RESOURCEID_MAX)); +} + +/*********************************************************************/ +/* + * CFE_ResourceId_GetSerial + * + * For complete API information, see prototype in header + */ +uint32 CFE_ResourceId_GetSerial(CFE_ResourceId_t ResourceId) +{ + return (CFE_ResourceId_ToInteger(ResourceId) & ((uint32)CFE_RESOURCEID_MAX)); +} + +/*********************************************************************/ +/* + * CFE_ResourceId_ToIndex + * + * For complete API information, see prototype in header + */ +int32 CFE_ResourceId_ToIndex(CFE_ResourceId_t Id, uint32 BaseValue, uint32 TableSize, uint32 *Idx) +{ + uint32 Serial; + + if (Idx == NULL) + { + return CFE_ES_BAD_ARGUMENT; + } + + Serial = CFE_ResourceId_ToInteger(Id) - BaseValue; + + if (Serial > CFE_RESOURCEID_MAX || TableSize == 0) + { + return CFE_ES_ERR_RESOURCEID_NOT_VALID; + } + + *Idx = Serial % TableSize; + return CFE_SUCCESS; +} + +/*********************************************************************/ +/* + * CFE_ResourceId_FindNext + * + * For complete API information, see prototype in header + */ +CFE_ResourceId_t CFE_ResourceId_FindNext(CFE_ResourceId_t StartId, uint32 TableSize, + bool (*CheckFunc)(CFE_ResourceId_t)) +{ + uint32 Serial; + uint32 Count; + uint32 ResourceType; + CFE_ResourceId_t CheckId; + bool IsTaken; + + ResourceType = CFE_ResourceId_GetBase(StartId); + Serial = CFE_ResourceId_GetSerial(StartId); + + Count = TableSize; + IsTaken = true; + + do + { + if (Count == 0) + { + CheckId = CFE_RESOURCEID_UNDEFINED; + break; + } + + --Count; + ++Serial; + if (Serial >= CFE_RESOURCEID_MAX) + { + Serial %= TableSize; + } + + CheckId = CFE_ResourceId_FromInteger(ResourceType + Serial); + IsTaken = CheckFunc(CheckId); + } while (IsTaken); + + return CheckId; +} diff --git a/modules/resourceid/mission_build.cmake b/modules/resourceid/mission_build.cmake new file mode 100644 index 000000000..9319c48d6 --- /dev/null +++ b/modules/resourceid/mission_build.cmake @@ -0,0 +1,32 @@ +########################################################### +# +# Resource ID mission build setup +# +# This file is evaluated as part of the "prepare" stage +# and can be used to set up prerequisites for the build, +# such as generating header files +# +########################################################### + +# Check if strict/enforcing typedef should be used +if (MISSION_RESOURCEID_MODE STREQUAL "STRICT") + set(RESOURCEID_HDR_FILE "cfe_resourceid_strict.h") +else () + set(RESOURCEID_HDR_FILE "cfe_resourceid_simple.h") +endif () + +# Generate the header definition files, use local default for this module) +generate_config_includefile( + FILE_NAME "cfe_resourceid_typedef.h" + FALLBACK_FILE "${CMAKE_CURRENT_LIST_DIR}/option_inc/${RESOURCEID_HDR_FILE}" +) + +# Resource ID base value header +# Currently the "osal compatible" version is the only provided implementation, +# but missions can provide their own if desired to override this. +generate_config_includefile( + FILE_NAME "cfe_resourceid_basevalue.h" + FALLBACK_FILE "${CMAKE_CURRENT_LIST_DIR}/option_inc/cfe_resourceid_osal_compatible.h" +) + +include_directories(${CMAKE_CURRENT_LIST_DIR}/inc) diff --git a/modules/resourceid/option_inc/cfe_resourceid_osal_compatible.h b/modules/resourceid/option_inc/cfe_resourceid_osal_compatible.h new file mode 100644 index 000000000..93bbaffa7 --- /dev/null +++ b/modules/resourceid/option_inc/cfe_resourceid_osal_compatible.h @@ -0,0 +1,77 @@ +/* +** GSC-18128-1, "Core Flight Executive Version 6.7" +** +** Copyright (c) 2006-2019 United States Government as represented by +** the Administrator of the National Aeronautics and Space Administration. +** All Rights Reserved. +** +** Licensed under the Apache License, Version 2.0 (the "License"); +** you may not use this file except in compliance with the License. +** You may obtain a copy of the License at +** +** http://www.apache.org/licenses/LICENSE-2.0 +** +** Unless required by applicable law or agreed to in writing, software +** distributed under the License is distributed on an "AS IS" BASIS, +** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +** See the License for the specific language governing permissions and +** limitations under the License. +*/ + +/** + * @file + * + * An implementation of CFE resource ID base values/limits that will be + * compatible with OSAL IDs. This is intended as a transitional tool to + * provide runtime value uniqueness, particularly when the "simple" (compatible) + * resource ID implementation is used. In this mode, compiler type checking + * is disabled, and so OSAL IDs can be silently interchanged with CFE IDs. + * + * However, by ensuring uniqueness in the runtime values, any ID handling + * errors may at least be detectable at runtime. + * + * This still works fine with the "strict" resource ID option, but is less + * important as the compiler type checking should prevent this type of error + * before the code even runs. + * + * The downside to this implementation is that it has a dependency on the + * OSAL ID structure. + */ + +#ifndef CFE_RESOURCEID_OSAL_COMPATIBLE_H +#define CFE_RESOURCEID_OSAL_COMPATIBLE_H + +/* +** Include Files +*/ +#include "cfe_resourceid_typedef.h" + +/* + * In this configuration, CFE resource IDs are tailored to not + * conflict/overlap with OSAL IDs, and are structured in a similar manner. + */ +#include "osapi-idmap.h" + +/* + * Limits/definitions related to CFE_ResourceId_t values. + * + * Defining based on OSAL ID values makes this object a superset of + * the OSAL ID type, such that OSAL IDs can be represented as resource IDs + * and not conflict with/alias each other. + * + * NOTE: This reflects a bit if "inside knowledge" about how OSAL IDs are + * constructed. The overlap between OSAL IDs and ES IDs may not always be + * consistent, and they can diverge in a future version. + */ +#define CFE_RESOURCEID_SHIFT OS_OBJECT_TYPE_SHIFT +#define CFE_RESOURCEID_MAX OS_OBJECT_INDEX_MASK + +/** + * @brief A macro to generate a CFE resource ID base value from an offset + * + * Each CFE ID range is effectively an extension of OSAL ID ranges by + * starting at OS_OBJECT_TYPE_USER. + */ +#define CFE_RESOURCEID_MAKE_BASE(offset) (CFE_RESOURCEID_MARK | ((offset) << CFE_RESOURCEID_SHIFT)) + +#endif /* CFE_RESOURCEID_OSAL_COMPATIBLE_H */ diff --git a/modules/resourceid/option_inc/cfe_resourceid_simple.h b/modules/resourceid/option_inc/cfe_resourceid_simple.h new file mode 100644 index 000000000..fe6348d3a --- /dev/null +++ b/modules/resourceid/option_inc/cfe_resourceid_simple.h @@ -0,0 +1,67 @@ +/* +** GSC-18128-1, "Core Flight Executive Version 6.7" +** +** Copyright (c) 2006-2019 United States Government as represented by +** the Administrator of the National Aeronautics and Space Administration. +** All Rights Reserved. +** +** Licensed under the Apache License, Version 2.0 (the "License"); +** you may not use this file except in compliance with the License. +** You may obtain a copy of the License at +** +** http://www.apache.org/licenses/LICENSE-2.0 +** +** Unless required by applicable law or agreed to in writing, software +** distributed under the License is distributed on an "AS IS" BASIS, +** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +** See the License for the specific language governing permissions and +** limitations under the License. +*/ + +/** + * @file + * + * Declarations and prototypes for simple (uint32 compatible) resource ID implementation + */ + +#ifndef CFE_RESOURCEID_SIMPLE_H +#define CFE_RESOURCEID_SIMPLE_H + +#include "common_types.h" + +/** + * @brief A type that provides a common, abstract identifier for + * all ES managed resources (e.g. apps, tasks, counters, etc). + * + * Fundamentally an unsigned integer but users should treat it as + * opaque, and only go through the ES API for introspection. + */ +typedef uint32 CFE_ResourceId_t; + +/** + * @brief A macro providing a type for app-specific IDs + * + * Local ID types are just direct typedefs to CFE_ResourceId_t in this mode, + * this means all ID values can be interchanged. + */ +#define CFE_RESOURCEID_BASE_TYPE CFE_ResourceId_t + +/** + * @brief A fixed bit that will be set in all CFE resource ID values + * + * In simple mode this is zero/disabled so that OSAL IDs and CFE IDs will + * have the same underlying values. This replicates historical behavior where + * CFE Task IDs and OSAL task IDs are same thing and are interchangable. + */ +#define CFE_RESOURCEID_MARK 0 + +/* + * Wrap/Unwrap macros. + * + * In simple mode theese are a pass through/no-op as values are not + * wrapped/protected. + */ +#define CFE_RESOURCEID_WRAP(x) x +#define CFE_RESOURCEID_UNWRAP(x) x + +#endif /* CFE_RESOURCEID_SIMPLE_H */ diff --git a/modules/resourceid/option_inc/cfe_resourceid_strict.h b/modules/resourceid/option_inc/cfe_resourceid_strict.h new file mode 100644 index 000000000..f71c30727 --- /dev/null +++ b/modules/resourceid/option_inc/cfe_resourceid_strict.h @@ -0,0 +1,93 @@ +/* +** GSC-18128-1, "Core Flight Executive Version 6.7" +** +** Copyright (c) 2006-2019 United States Government as represented by +** the Administrator of the National Aeronautics and Space Administration. +** All Rights Reserved. +** +** Licensed under the Apache License, Version 2.0 (the "License"); +** you may not use this file except in compliance with the License. +** You may obtain a copy of the License at +** +** http://www.apache.org/licenses/LICENSE-2.0 +** +** Unless required by applicable law or agreed to in writing, software +** distributed under the License is distributed on an "AS IS" BASIS, +** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +** See the License for the specific language governing permissions and +** limitations under the License. +*/ + +/** + * @file + * + * Declarations and prototypes for strict (type-safe) resource ID implementation + */ + +#ifndef CFE_RESOURCEID_STRICT_H +#define CFE_RESOURCEID_STRICT_H + +#include "common_types.h" + +/* + * Inform other code that the "strict mode" is enabled for resource IDs + * + * This in turn allows ES to adjust other macros/conversions as necessary + * to work with the strict type checking. + */ +#define CFE_RESOURCEID_STRICT_MODE + +/** + * @brief A type that provides a common, abstract identifier for + * all CFE managed resources (e.g. apps, tasks, counters, etc). + * + * Fundamentally an unsigned integer but users should treat it as + * opaque, and only go through the ES API for introspection. + * + */ +typedef struct +{ + uint32 id; +} CFE_ResourceId_t; + +/** + * @brief A macro to generate a basetype for app-specific IDs + * + * Resource IDs may be "wrapped" a second time to make a unique + * typedef for application-specific ID values. + * + * Defining this base type as a macro rather than a typedef is intentional + * such that every time this is used it makes an equivalent but different + * type. That is, it is a different type per the compiler type checking + * but has the same content/structure. + */ +#define CFE_RESOURCEID_BASE_TYPE \ + struct \ + { \ + CFE_ResourceId_t id; \ + } + +/** + * @brief A fixed bit that should be set in all CFE resource ID values + * + * In strict mode this is nonzero so that OSAL IDs and CFE IDs will have + * different values. This means that CFE Task IDs will not be interchangable + * with OSAL task IDs, either in value or type. + */ +#define CFE_RESOURCEID_MARK 0x02000000 + +/* + * Wrap/Unwrap macros. + * + * These are helpers for transparently accessing through wrapper types. + * + * These are not type-safe - Whenever possible applications should use + * the type-safe inline functions provided in cfe_resourceid.h instead. + */ +#define CFE_RESOURCEID_WRAP(x) \ + { \ + x \ + } +#define CFE_RESOURCEID_UNWRAP(x) (x).id + +#endif /* CFE_RESOURCEID_STRICT_H */