Release v4.0.0 #4006
thomas-bc
announced in
Announcements
Release v4.0.0
#4006
Replies: 0 comments
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Uh oh!
There was an error while loading. Please reload this page.
-
Summary
We are excited to release F Prime v4.0! This release is a major upgrade from the latest v3 series and includes numerous improvements, new features, and breaking changes that enhance the framework's capabilities and maintainability.
This release comes with the following amazing features:
Svc/FpySequencer)Svc.SubtopologiesGdsStandardApp,DataHandlerPlugin)Release v4.0 is a significant upgrade and comes with multiple breaking changes that were introduced in order to consolidate design patterns and bring them in line with our coding standards. Below is a list of breaking changes as well as instructions on how to upgrade a v3.6.x project to v4.
Table of Contents
These changes are broken down into the following categories:
NATIVE_INT_TYPEandNATIVE_UINT_TYPEFwIndexType Removal 🚨PRIVATE,PROTECTED, andSTATIC🚨Tip
Some changes are required and others are optional. The 🚨 symbol designates a required change.
Typing Changes
F Prime is removing the
NATIVE_INT_TYPE,PlatformIntType, etc. Additionally, F Prime has begun ensuring that configurable types (e.g.FwIndexType) are configured to fixed-width values. The requirements (signed, minimum sizes) can be found in the numerical types document.Users needing non-default values for configurable types should set them as type aliases in FPP using the new configuration system.
Warning
All Typing changes are required for upgrade to v4.0.0.
Port Indicies and
NATIVE_INT_TYPEandNATIVE_UINT_TYPEFwIndexType RemovalNATIVE_INT_TYPEmust be replaced withFwIndexTypein port indices. Other uses ofNATIVE_INT_TYPEandNATIVE_UINT_TYPEmust also be replaced as these violate the fixed-width type standard.For other configurable type options, see numerical types design.
Before:
const NATIVE_INT_TYPE portNumAfter:
Rate Group Contexts
Rate group context has been changed to the fixed-width type
U32to meet compliance with fixed-with types usage.Before
NATIVE_INT_TYPE rateGroup1Context[Svc::ActiveRateGroup::CONNECTION_COUNT_MAX] = {}; NATIVE_INT_TYPE rateGroup2Context[Svc::ActiveRateGroup::CONNECTION_COUNT_MAX] = {}; NATIVE_INT_TYPE rateGroup3Context[Svc::ActiveRateGroup::CONNECTION_COUNT_MAX] = {};After:
U32 rateGroup1Context[Svc::ActiveRateGroup::CONNECTION_COUNT_MAX] = {}; U32 rateGroup2Context[Svc::ActiveRateGroup::CONNECTION_COUNT_MAX] = {}; U32 rateGroup3Context[Svc::ActiveRateGroup::CONNECTION_COUNT_MAX] = {};Unit Test Constant Changes
Use of
NATIVE_INT_TYPEhas been removed in unit tests.Before:
After:
Fw::Buffer size type
The
Fw::Buffersize type has been changed toFwSizeType(previously U32). This allows for configuration and better integration with other types. Switch to usingFwSizeTypewhen reading / settingFw::Buffersizes.Struct Member Access
C++ getters and setters for fields of FPP structs are now autocoded in the form
get_<field>()andset_<field>()(used to beget<field>()andset<field>()). C++ code using those getters and setters must be updated.Component Changes
Component implementations in v4.0.0 have also changed.
Removal of
PRIVATE,PROTECTED, andSTATICMacro definitions
PRIVATE,PROTECTED, andSTATICwere as close to redefining a language feature as one could get without technically redefining a language feature. Users must switch to friend classes for white-box unit tests.Warning
This change is required.
Unittest base classes are automatically and a tester classes are automatically added as friends to the component's base class to enable unit testing. Users may implement test-access to the base class through their tester class (e.g.
SignalGenTester).Users needing access to the component implementation class should add a friendship statement by hand.
Component Configuration Usage Changes
Configuration headers have been placed in the name-spacing folder
config. This is to reduce the possibility of collision with project and external headers. Configuration paths must be updated.FpConfig.hpp/FpConfig.hhas been updated toFw/FPrimeBasicTypes.hpp/Fw/FPrimeBasicTypes.hand a dependency onFw_Typesis now explicitly required.Warning
These changes are required and affects configuration headers and autocoded configuration headers.
Before:
After:
Before: C++
After: C++
Before: CMakeLists.txt
After: CMakeLists.txt
Tip
Fw_Typesis auto-detected for FPP-based modules. Add this dependency when not using FPP autocoding on your module.Built-In Component Changes
FileUplink and FileDownlink now prepend the buffers (file packets) they send out with the appropriate
FW_PACKET_FILEmarker, as it is expected for all F´ data packets.ComQueue has been updated to handle buffer management according the "Data Return" pattern mentioned above.
Svc.ActiveLoggerhas been renamed toSvc.EventManagerDrv.BlockDriverhas been removed. Users can use a timer component to tick theRateGroupDriverinstead, such asSvc.LinuxTimer. An example of such a changeset can be found here: fprime-tutorial-hello-world#46The
Drv.ByteStreamDriverinterface has been slightly modified and theDrv.AsyncByteStreamDriverhas been introduced. TheSvc.ComStubcomponent has been updated to work with either of those interfaces.<interface>.fppistyle interfaces have been replaced with format FPPinterface/import. Examples can be found inSvc/Interfaces/andDrv/Interfaces/Deployment Changes
Deployments in v4.0.0 have substantially changed, and F´ now ships subtopologies to help construct deployments with minimal copy-and-paste from F´ into users topologies.
Tip
It may be easiest to reconstruct a deployment using
fprime-util new --deploymentas it will stamp-out a basic subtopology-powered deployment. Users would need to re-add their custom component instances and connections.Pre-built subtopologies
F Prime now ships with the following subtopologies that users can use to reduce the size and complexity of their topology.
Tip
This change is not required but can help adopting required changes more easily.
- Event logging and telemetry collection
- Health monitoring system
- Fatal error handling
- Frame processing and routing
- Frame processing and routing
- Parameter database management
- File system operations
- Storage and retrieval capabilities
- Product metadata management
Before:
After:
Communications component stack
The Uplink and Downlink components have been updated for better modularity and to allow for easy support of other communication protocols.
Tip
Rather than making all these changes by hand, users can instead import the Comms subtopologies.
Example Change Set
If using a standard Uplink/Downlink stack as generated by
fprime-util new --deployment, the full change-set that users need to apply to their topology is shown in the LedBlinker change logClick to Expand changes to a topology.fpp
Before (topology.fpp)
After (topology.fpp)
Click to Expand changes to a instances.fpp
Diff (instances.fpp)
Click to Expand changes to a Topology.cpp
The following removes the old framing/deframing protocols, and introduces the new
FprimeFrameDetector.Diff (Topology.cpp)
Uplink Changes
The old
Svc.Deframerwas performing 3 functionalities: (1) accumulating bytes in a circular buffer until it detects a full frame, (2) validating the frame and extracting the payload data, and (3) routing payload data to its destination.In the new Uplink stack, these 3 functionalities have been split into 3 distinct components: (1)
Svc.FrameAccumulator, (2)Svc.FprimeDeframer, and (3)Svc.FprimeRouter. To learn more about these components, please check out their SDDs on the website!Each component implements an FPP Interface (in
Svc/Interfaces/) so that they can be swapped with project-specific components, allowing for custom Deframing / Routing.Memory Management
Memory management in the Uplink/Downlink stack has been updated so that a buffer coming out of a component on
dataOutshall come back ondataReturnIn. This allows for components to allocate/deallocate memory as they see fit, and for the Topology Engineer not to have to track down memory management of each component to make sure they are wired correctly with the appropriate BufferManagers.Downlink Changes
In the Downlink stack, the port connections have been modified to fit the new memory management pattern. The Framer now implements the
FramerInterface.fppito allow projects to implement custom Framing easily.Build System Changes
These changes affect how the CMake system is used.
New CMake Module Structure
The old module registration structure in F Prime had one primary limitation: SOURCE_FILES and MOD_DEPS were variables and thus could bleed into other module registrations if not unset. This pollution of CMake's variable namespace, high chance for user error, and poor choice of the name "MOD_DEPS" led to a need to refactor how modules are done. To fit in with modern CMake practices, all module inputs are arguments to the registration calls with individual variables specified by directive arguments (e.g. SOURCES, DEPENDS).
Tip
register_fprime_module,register_fprime_deploymentandregister_fprime_utstill supportMOD_DEPS,SOURCE_FILES,UT_MOD_DEPS,UT_SOURCE_FILES. Updating to the new structure is only required forregister_fprime_configurationcalls. However, new features will only be supported with the new structure and as such, users are encouraged to update when needed.The new
register_fprime_*calls are provided arguments lists separated by argument directives to specify sources (SOURCES), dependencies (DEPENDS) etc.The first argument is an optional explicit module name followed by directives and their argument lists.
Before:
After:
Tip
Notice that autocoder inputs are now specifically called out separately from compiled source files.
Warning
Do not specify an explicit module name when autocoding FPP.
Old variable usage can be translated to new directives using the following table:
cc,c++, or other compilerDeployment Ordering
Since deployments in F Prime do recursive detection of items like unit tests, etc, deployments now check for the existence of F Prime modules that support them. This means F Prime deployments must be defined last in the CMake structure.
Warning
These changes are required.
Before:
After:
Project Configuration Changes
One of the flaws of historical F Prime is that configuration was an all-or-nothing copy. It meant that projects, libraries, etc could not just override what was changed. This presented projects with a maintenance issue: owning unchanged code provided by F Prime while tracking their own minor changes.
With
v4.0.0projects choose to override specific files and the rest are inherited from underlying configuration modules.Warning
These changes are required.
Additionally, each configuration is specified as a module. Use the
CONFIGURATION_OVERRIDESdirective to override existing config. UserSOURCES,HEADERS, andAUTOCODER_INPUTSas usual to specify new configuration (i.e. new configuration for your library). Modules specifying onlyCONFIGURATION_OVERRIDESmust also use theINTERFACEspecifier.To specify a new configuration module, ensure that some directory added to the project with
add_fprime_subdirectorycontains aCMakeLists.txtincluding aregister_fprime_configcall.See changes in cmake module structure to understand the format of the
register_fprime_configcall.CMakeLists.txt
This example shows how to override just
FpConifg.fppandIpCfg.hppfrom fprime.Tip
Configurations are overridden by filename, so remember to keep your filenames consistent with the file you wish to override.
Tip
Default F Prime configuration lives at
fprime/default/configprojects will use these settings unless the filename is included in a projects configuration module viaCONFIGURATION_OVERRIDES.Warning
F Prime only has the notion of a single configuration per project (i.e. build). You still may not specify different configurations for different modules built by the same project.
Platform Changes
Platforms have had several major changes in
v4.0.0:register_fprime_configWarning
All changes in this section are required.
Platform Types
Platform types were previously defined as header typedefs, however; this meant these types (which flow into configurable types) are not available to FPP models. These types are now aliases within FPP.
Before (PlatformTypes.h)
After (PlatformTypes.fpp)
Warning
Since
PlatfromPointerCastshould not be used in the model, it is kept inPlatformTypes.hThe requirements on these types, and the complete list are found in the numerical types documentation.
Platform Definitions
Platform definitions are defined in
cmake/platform/<name-of-platform>.cmake. This file must now define an fprime configuration module that performs the autocoding for the newPlatformTypes.fppBefore
After
Other breaking changes 🚨
Os::FileSystem::getPathType()is now implementation-specific. OSAL implementations should implement this method if they wish to use it in their project.Deprecations
Fw::Buffer::getSerializeRepr()has been deprecated in favor of two simpler-to-use methods for serialization and deserialization:Fw::Buffer::getSerializer()andFw::Buffer::getDeserializer(). Example changesets are found Deprecate Fw::Buffer::getSerializeRepr in favor of 'getSerializer' and 'getDeserializer' #3431.[de]serialize(U8* buff, Serializable::SizeType& length, bool noLength)are deprecated as they do not adhere to coding guidelines. Users should switch to the[de]serialize(U8* buff, FwSizeType& length, Serialization::t mode)variants instead.[de]serialize()will soon be deprecated. Users are recommended to switch to theserializeTo()anddeserializeFrom()methods.Other Significant Changes
These changes should not affect user developed code.
Subtopologies
F Prime v4 introduces better support for subtopologies (specification, configuration, etc.), which allow for better modularity and organization of components within a topology. Subtopologies can be used to group related components together, making it easier to manage complex systems. Core subtopologies are also available in
Svc.Subtopologies. New deployment generation has been switched to use these subtopologies.FPP v3
F Prime v4 ships with many significant new features to FPP (from FPP v3 release notes):
Miscellaneous
Os::StubMutexwill now only cause an error in the case that there should have been mutex contention. In cases where the lock is uncontested, no error will result.piprequirements.txt. Build time should be improved.fprime-gdsnow defaults to using the CCSDS protocols. Users who want to retain the F´ protocol should usefprime-gds --framing-selection fprime🚨What's Changed
Click to Expand Full list of changes
finalto component implementation classes by @jwest115 in Addfinalto component implementation classes #3292Fwby @LeStarch in Removes NATIVE_INT_TYPE, NATIVE_UINT_TYPE, and POINTER_CAST fromFw#3286PRI_format specifier typedefs for F Prime type aliases #3199) by @vincewoo in Adding format specifier aliases for primitives. Updating documentation. (#3199) #3375UT_AUTO_HELPERScontrol word to new CMake API by @thomas-bc in AddUT_AUTO_HELPERScontrol word to new CMake API #3648Types.fppto use optimized sizes for enumerations by @kyleajones in UpdatesTypes.fppto use optimized sizes for enumerations #3956New Contributors
Types.fppto use optimized sizes for enumerations #3956Full Changelog: v3.6.3...v4.0.0
This discussion was created from the release v4.0.0.
Beta Was this translation helpful? Give feedback.
All reactions