sbgECom Library  4.0.1987-stable
C library to interface SBG Systems IMU/AHRS/INS
sbgVersion.h File Reference

Helper methods and definitions used to handle version. More...

#include <sbgCommon.h>

Go to the source code of this file.

Data Structures

struct  _SbgVersion
 

Macros

#define SBG_VERSION_SOFT_SCHEME   (0x00000001u << 31)
 
#define SBG_VERSION_SOFT_SCHEME_QUALIFIER_MASK   (0x07)
 
#define SBG_VERSION_SOFT_SCHEME_QUALIFIER_SHIFT   (28)
 
#define SBG_VERSION_SOFT_SCHEME_MAJOR_MASK   (0x3F)
 
#define SBG_VERSION_SOFT_SCHEME_MAJOR_SHIFT   (22)
 
#define SBG_VERSION_SOFT_SCHEME_MINOR_MASK   (0x3F)
 
#define SBG_VERSION_SOFT_SCHEME_MINOR_SHIFT   (16)
 
#define SBG_VERSION_SOFT_SCHEME_BUILD_MASK   (0xFFFF)
 
#define SBG_VERSION_SOFT_SCHEME_BUILD_SHIFT   (0)
 
#define SBG_VERSION_BASIC(major, minor, rev, build)
 
#define SBG_VERSION_SOFTWARE(major, minor, build, qualifier)
 

Typedefs

typedef enum _SbgVersionQualifier SbgVersionQualifier
 
typedef enum _SbgVersionCmpThreshold SbgVersionCmpThreshold
 
typedef struct _SbgVersion SbgVersion
 

Enumerations

enum  _SbgVersionQualifier {
  SBG_VERSION_QUALIFIER_DEV = 0 ,
  SBG_VERSION_QUALIFIER_ALPHA = 1 ,
  SBG_VERSION_QUALIFIER_BETA = 2 ,
  SBG_VERSION_QUALIFIER_RC = 3 ,
  SBG_VERSION_QUALIFIER_STABLE = 4 ,
  SBG_VERSION_QUALIFIER_HOT_FIX = 5
}
 
enum  _SbgVersionCmpThreshold {
  SBG_VERSION_CMP_THRESHOLD_MAJOR = 0 ,
  SBG_VERSION_CMP_THRESHOLD_MINOR = 1 ,
  SBG_VERSION_CMP_THRESHOLD_REVISION = 2 ,
  SBG_VERSION_CMP_THRESHOLD_BUILD = 3 ,
  SBG_VERSION_CMP_THRESHOLD_QUALIFIER = 4
}
 

Functions

SBG_COMMON_LIB_API void sbgVersionCreateBasic (SbgVersion *pVersion, uint8_t major, uint8_t minor, uint8_t revision, uint8_t build)
 
SBG_COMMON_LIB_API void sbgVersionCreateSoftware (SbgVersion *pVersion, uint8_t major, uint8_t minor, uint16_t build, SbgVersionQualifier qualifier)
 
SBG_COMMON_LIB_API void sbgVersionConstructCopy (SbgVersion *pVersion, const SbgVersion *pOtherVersion)
 
SBG_COMMON_LIB_API void sbgVersionDecode (uint32_t encodedVersion, SbgVersion *pVersionInfo)
 
SBG_COMMON_LIB_API uint32_t sbgVersionEncode (const SbgVersion *pVersionInfo)
 
SBG_INLINE bool sbgVersionIsUsingSoftwareScheme (uint32_t encodedVersion)
 
SBG_COMMON_LIB_API int32_t sbgVersionCompare (const SbgVersion *pVersionA, const SbgVersion *pVersionB, SbgVersionCmpThreshold threshold)
 
SBG_COMMON_LIB_API int32_t sbgVersionCompareEncoded (uint32_t versionA, uint32_t versionB, SbgVersionCmpThreshold threshold)
 
SBG_COMMON_LIB_API int32_t sbgVersionIsWithinRange (const SbgVersion *pLowerVersion, const SbgVersion *pHigherVersion, const SbgVersion *pVersion)
 
SBG_COMMON_LIB_API int32_t sbgVersionIsWithinRangeEncoded (uint32_t lowerVersion, uint32_t higherVersion, uint32_t version)
 
SBG_COMMON_LIB_API SbgErrorCode sbgVersionToString (const SbgVersion *pVersionInfo, char *pBuffer, size_t sizeOfBuffer)
 
SBG_COMMON_LIB_API SbgErrorCode sbgVersionToStringEncoded (uint32_t version, char *pBuffer, size_t sizeOfBuffer)
 
SBG_COMMON_LIB_API SbgErrorCode sbgVersionFromString (const char *pVersionStr, SbgVersion *pVersionInfo)
 
SBG_COMMON_LIB_API SbgErrorCode sbgVersionFromStringEncoded (const char *pVersionStr, uint32_t *pVersion)
 
 SBG_DEPRECATED (SBG_INLINE uint32_t SBG_VERSION(uint8_t major, uint8_t minor, uint8_t rev, uint8_t build))
 
SBG_INLINE uint32_t SBG_VERSION (uint8_t major, uint8_t minor, uint8_t rev, uint8_t build)
 
SBG_INLINE uint8_t SBG_VERSION_GET_MAJOR (uint32_t encodedVersion)
 
SBG_INLINE uint8_t SBG_VERSION_GET_MINOR (uint32_t encodedVersion)
 
SBG_INLINE uint8_t SBG_VERSION_GET_REV (uint32_t encodedVersion)
 
SBG_INLINE uint8_t SBG_VERSION_GET_BUILD (uint32_t encodedVersion)
 

Detailed Description

Helper methods and definitions used to handle version.

Author
SBG Systems
Date
April 23, 2015

Version information is stored within a single uint32_t. There are two different versions schemes to better handle software revisions and file format / hardware ones.

Software version are only used for firmware and software. This versions is defined as a Major.Minor.Build-Qualifier for example: 1.3.1845-rc Major and Minor can range from 0 to 63. Build is an uint16_t ranging from 0 to 65535. Qualifier is an enum encoded on 3 bits.

Basic version is used for hardware or file formats and is the legacy one for software. This versions is defined as a Major.Minor.Revision.Build Each element is stored in an uint8_t. The Major version should NEVER go above 31

License

The MIT license

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Macro Definition Documentation

◆ SBG_VERSION_SOFT_SCHEME

#define SBG_VERSION_SOFT_SCHEME   (0x00000001u << 31)

Set to 1 to indicate a version number that uses the software scheme. Set to 0 means a basic version scheme.

◆ SBG_VERSION_SOFT_SCHEME_QUALIFIER_MASK

#define SBG_VERSION_SOFT_SCHEME_QUALIFIER_MASK   (0x07)

Mask used to keep only the version qualifier enum.

◆ SBG_VERSION_SOFT_SCHEME_QUALIFIER_SHIFT

#define SBG_VERSION_SOFT_SCHEME_QUALIFIER_SHIFT   (28)

Bitshift to apply to get the qualifier enum.

◆ SBG_VERSION_SOFT_SCHEME_MAJOR_MASK

#define SBG_VERSION_SOFT_SCHEME_MAJOR_MASK   (0x3F)

Mask used to keep only the major version field.

◆ SBG_VERSION_SOFT_SCHEME_MAJOR_SHIFT

#define SBG_VERSION_SOFT_SCHEME_MAJOR_SHIFT   (22)

Bitshift used to get the major version field.

◆ SBG_VERSION_SOFT_SCHEME_MINOR_MASK

#define SBG_VERSION_SOFT_SCHEME_MINOR_MASK   (0x3F)

Mask used to keep only the minor version field.

◆ SBG_VERSION_SOFT_SCHEME_MINOR_SHIFT

#define SBG_VERSION_SOFT_SCHEME_MINOR_SHIFT   (16)

Bitshift used to get the minor version field.

◆ SBG_VERSION_SOFT_SCHEME_BUILD_MASK

#define SBG_VERSION_SOFT_SCHEME_BUILD_MASK   (0xFFFF)

Mask used to keep only the build version field.

◆ SBG_VERSION_SOFT_SCHEME_BUILD_SHIFT

#define SBG_VERSION_SOFT_SCHEME_BUILD_SHIFT   (0)

Bitshift used to get the build version field.

◆ SBG_VERSION_BASIC

#define SBG_VERSION_BASIC (   major,
  minor,
  rev,
  build 
)
Value:
( (((uint32_t)(major)) << 24) | \
(((uint32_t)(minor)) << 16) | \
(((uint32_t)(rev)) << 8) | \
(((uint32_t)(build))) )

Compile a version number using the basic scheme based on major, minor, revision and build information

Parameters
[in]majorThe major version between 0 to 127.
[in]minorThe minor version between 0 to 255.
[in]revThe revision version between 0 to 255.
[in]buildThe build number between 0 to 255.
Returns
The encoded version number.

◆ SBG_VERSION_SOFTWARE

#define SBG_VERSION_SOFTWARE (   major,
  minor,
  build,
  qualifier 
)
Value:
#define SBG_VERSION_SOFT_SCHEME_MAJOR_MASK
Definition: sbgVersion.h:66
#define SBG_VERSION_SOFT_SCHEME_BUILD_SHIFT
Definition: sbgVersion.h:73
#define SBG_VERSION_SOFT_SCHEME_MINOR_MASK
Definition: sbgVersion.h:69
#define SBG_VERSION_SOFT_SCHEME
Definition: sbgVersion.h:61
#define SBG_VERSION_SOFT_SCHEME_MAJOR_SHIFT
Definition: sbgVersion.h:67
#define SBG_VERSION_SOFT_SCHEME_QUALIFIER_MASK
Definition: sbgVersion.h:63
#define SBG_VERSION_SOFT_SCHEME_MINOR_SHIFT
Definition: sbgVersion.h:70
#define SBG_VERSION_SOFT_SCHEME_QUALIFIER_SHIFT
Definition: sbgVersion.h:64
#define SBG_VERSION_SOFT_SCHEME_BUILD_MASK
Definition: sbgVersion.h:72

Compile a version number using the software scheme based on major, minor, build, qualifier.

Parameters
[in]majorThe major version between 0 to 63.
[in]minorThe minor version between 0 to 63.
[in]buildThe build version between 0 to 65535.
[in]qualifierThe version qualifier within the SbgVersionQualifier enum.
Returns
The encoded version number.

Typedef Documentation

◆ SbgVersionQualifier

Version qualifier enum definition. This enum is used to identify if we have a basic version scheme or a software one. If it's a software one, we can easly know if the software version is a beta, a stable one.

◆ SbgVersionCmpThreshold

Version qualifier enum definition. This enum is used to identify if we have a basic version scheme or a software one. If it's a software one, we can easily know if the software version is a beta, a stable one.

◆ SbgVersion

typedef struct _SbgVersion SbgVersion

This structure contains all the fields provided by a version number. It handles both basic and software version numbers.

Enumeration Type Documentation

◆ _SbgVersionQualifier

Version qualifier enum definition. This enum is used to identify if we have a basic version scheme or a software one. If it's a software one, we can easly know if the software version is a beta, a stable one.

Enumerator
SBG_VERSION_QUALIFIER_DEV 

Development only version or pre-alpha. Customer shouldn't get this version qualifier.

SBG_VERSION_QUALIFIER_ALPHA 

Alpha version, missing features, can be unstable and could cause crashes or data loss. API can still change.

SBG_VERSION_QUALIFIER_BETA 

Beta version, features are freezed, can be unstable and could cause crashes or data loss. API shouldn't change.

SBG_VERSION_QUALIFIER_RC 

Release Candidate, features are freezed, with no known bug. API is freezed.

SBG_VERSION_QUALIFIER_STABLE 

Stable release, the version is the standard delivered one.

SBG_VERSION_QUALIFIER_HOT_FIX 

Hot fixes were applied on a stable release. It should be bug fixes. This qualifier is temporary as the version should return to stable release as soon as the test procedure has been performed.

◆ _SbgVersionCmpThreshold

Version qualifier enum definition. This enum is used to identify if we have a basic version scheme or a software one. If it's a software one, we can easily know if the software version is a beta, a stable one.

Enumerator
SBG_VERSION_CMP_THRESHOLD_MAJOR 

Compare only the major field.

SBG_VERSION_CMP_THRESHOLD_MINOR 

Compare the major and minor fields.

SBG_VERSION_CMP_THRESHOLD_REVISION 

Compare the major, minor and revision fields (only for basic versions).

SBG_VERSION_CMP_THRESHOLD_BUILD 

Compare the major, minor, revision and build fields.

SBG_VERSION_CMP_THRESHOLD_QUALIFIER 

Compare the major, minor, revision, build and qualifier fields (only for software scheme).

Function Documentation

◆ sbgVersionCreateBasic()

SBG_COMMON_LIB_API void sbgVersionCreateBasic ( SbgVersion pVersion,
uint8_t  major,
uint8_t  minor,
uint8_t  revision,
uint8_t  build 
)

Create a basic scheme version given the components major.minor.rev.build

Parameters
[out]pVersionVersion instance
[in]majorThe major component between 0 to 127
[in]minorThe minor component between 0 to 255
[in]revisionThe revision component between 0 to 255
[in]buildThe build component between 0 to 255

◆ sbgVersionCreateSoftware()

SBG_COMMON_LIB_API void sbgVersionCreateSoftware ( SbgVersion pVersion,
uint8_t  major,
uint8_t  minor,
uint16_t  build,
SbgVersionQualifier  qualifier 
)

Create a software scheme version given the components major.minor.build.qualifier

Parameters
[out]pVersionVersion instance
[in]majorThe major component between 0 to 63
[in]minorThe minor component between 0 to 63
[in]buildThe build component between 0 to 65535
[in]qualifierThe version qualifier enum value.

◆ sbgVersionConstructCopy()

SBG_COMMON_LIB_API void sbgVersionConstructCopy ( SbgVersion pVersion,
const SbgVersion pOtherVersion 
)

Version copy constructor.

Parameters
[in]pVersionVersion.
[in]pOtherVersionVersion to copy from.

◆ sbgVersionDecode()

SBG_COMMON_LIB_API void sbgVersionDecode ( uint32_t  encodedVersion,
SbgVersion pVersionInfo 
)

Fill a SbgVersion structure based on an uint32_t that stores the 'compiled' version information.

Parameters
[in]encodedVersionThe version information stored within a uint32_t.
[out]pVersionInfoPointer on an allocated SbgVersion structure to fill.

Referenced by SBG_VERSION_GET_BUILD(), SBG_VERSION_GET_MAJOR(), SBG_VERSION_GET_MINOR(), SBG_VERSION_GET_REV(), and sbgVersionIsUsingSoftwareScheme().

◆ sbgVersionEncode()

SBG_COMMON_LIB_API uint32_t sbgVersionEncode ( const SbgVersion pVersionInfo)

Construct a uint32_t containing a version information based on a SbgVersion structure.

Parameters
[in]pVersionInfoPointer on a read only version structure to encode.
Returns
The encoded version information on an uint32_t or 0 if an error has occurred.

◆ sbgVersionIsUsingSoftwareScheme()

SBG_INLINE bool sbgVersionIsUsingSoftwareScheme ( uint32_t  encodedVersion)

Returns true if this encoded version number is using a software scheme.

Parameters
[in]encodedVersionThe encoded version number to test stored in a uint32_t.
Returns
true if the version number is using a software scheme.

References sbgVersionDecode(), and _SbgVersion::softwareScheme.

◆ sbgVersionCompare()

SBG_COMMON_LIB_API int32_t sbgVersionCompare ( const SbgVersion pVersionA,
const SbgVersion pVersionB,
SbgVersionCmpThreshold  threshold 
)

Compare two version information structures and return if the version A is greater, less or equal than the version B.

The computation is roughly result = version A - version B We can define how far we will check if the version A is greater than the version B. For example, we can only check the major or major and minor fields.

Parameters
[in]pVersionAThe first version to compare.
[in]pVersionBThe second version to compare.
[in]thresholdThe comparaison threshold to know if we are checking the major, minor, revision, build, ...
Returns
A positive value if the version A is greater than B, a negative one if version A is less than B and 0 if the two versions are the same (according to the threshold).

◆ sbgVersionCompareEncoded()

SBG_COMMON_LIB_API int32_t sbgVersionCompareEncoded ( uint32_t  versionA,
uint32_t  versionB,
SbgVersionCmpThreshold  threshold 
)

Compare two encoded versions and return if the version A is greater, less or equal than the version B.

The computation is roughly result = version A - version B We can define how far we will check if the version A is greater than the version B. For example, we can only check the major or major and minor fields.

Parameters
[in]versionAThe first compiled version to compare.
[in]versionBThe second compiled version to compare.
[in]thresholdThe comparaison threshold to know if we are checking the major, minor, revision, build, ...
Returns
A positive value if the version A is greater than B, a negative one if version A is less than B and 0 if the two versions are the same (according to the threshold).

◆ sbgVersionIsWithinRange()

SBG_COMMON_LIB_API int32_t sbgVersionIsWithinRange ( const SbgVersion pLowerVersion,
const SbgVersion pHigherVersion,
const SbgVersion pVersion 
)

Check if the provided version is between the provided version interval. All versions should have the same scheme.

Parameters
[in]pLowerVersionThe lower version bound of the interval.
[in]pHigherVersionThe hiver version bound of the interval.
[in]pVersionThe version to check.
Returns
A negative value if the version is stricly below the lower version bound Zero if the version if equal or greater than lower version and equal or smaller than higer version A positive value if the version is strictly above the higher version bound

◆ sbgVersionIsWithinRangeEncoded()

SBG_COMMON_LIB_API int32_t sbgVersionIsWithinRangeEncoded ( uint32_t  lowerVersion,
uint32_t  higherVersion,
uint32_t  version 
)

Check if the provided encoded version is between the provided version interval. All versions should have the same scheme.

Parameters
[in]lowerVersionThe lower version bound of the interval.
[in]higherVersionThe hiver version bound of the interval.
[in]versionThe version to check.
Returns
A negative value if the version is stricly below the lower version bound Zero if the version if equal or greater than lower version and equal or smaller than higer version A positive value if the version is strictly above the higher version bound

◆ sbgVersionToString()

SBG_COMMON_LIB_API SbgErrorCode sbgVersionToString ( const SbgVersion pVersionInfo,
char *  pBuffer,
size_t  sizeOfBuffer 
)

Convert a version information to a human readable string.

Parameters
[in]pVersionInfoPointer on a read only version structure to convert to a human readable string.
[out]pBufferBuffer to store the version as a human readable null terminated string.
[in]sizeOfBufferMaximum buffer size including the null terminated char.
Returns
SBG_NO_ERROR if the version information has been converted to a string. SBG_BUFFER_OVERFLOW is the buffer isn't big enough to store the converted version string.

◆ sbgVersionToStringEncoded()

SBG_COMMON_LIB_API SbgErrorCode sbgVersionToStringEncoded ( uint32_t  version,
char *  pBuffer,
size_t  sizeOfBuffer 
)

Convert an encoded version number to a human readable string.

Parameters
[in]versionEncoded version value to to convert to a human readable string.
[out]pBufferBuffer to store the version as a human readable null terminated string.
[in]sizeOfBufferMaximum buffer size including the null terminated char.
Returns
SBG_NO_ERROR if the version information has been converted to a string. SBG_BUFFER_OVERFLOW is the buffer isn't big enough to store the converted version string.

◆ sbgVersionFromString()

SBG_COMMON_LIB_API SbgErrorCode sbgVersionFromString ( const char *  pVersionStr,
SbgVersion pVersionInfo 
)

Convert a human readable string to a version structure.

Parameters
[in]pVersionStrThe string containing the version to convert.
[out]pVersionInfoPointer to a version structure to store the parsed version info.
Returns
SBG_NO_ERROR if the version information has been converted from a string.

◆ sbgVersionFromStringEncoded()

SBG_COMMON_LIB_API SbgErrorCode sbgVersionFromStringEncoded ( const char *  pVersionStr,
uint32_t *  pVersion 
)

Convert an encoded version number to a human readable string.

Parameters
[in]pVersionStrThe string containing the version to convert.
[out]pVersionReturned encoded version value parsed from the string.
Returns
SBG_NO_ERROR if the version information has been converted from a string.

◆ SBG_DEPRECATED()

SBG_DEPRECATED ( SBG_INLINE uint32_t   SBG_VERSIONuint8_t major, uint8_t minor, uint8_t rev, uint8_t build)

Define all these methods as deprecated.

◆ SBG_VERSION()

SBG_INLINE uint32_t SBG_VERSION ( uint8_t  major,
uint8_t  minor,
uint8_t  rev,
uint8_t  build 
)

DEPRECATED macro, please update your code

Compile a version number using the basic scheme based on major, minor, revision and build information

Parameters
[in]majorThe major version between 0 to 127.
[in]minorThe minor version between 0 to 255.
[in]revThe revision version between 0 to 255.
[in]buildThe build number between 0 to 255.
Returns
The encoded version number.

References SBG_VERSION_BASIC.

◆ SBG_VERSION_GET_MAJOR()

SBG_INLINE uint8_t SBG_VERSION_GET_MAJOR ( uint32_t  encodedVersion)

DEPRECATED method, please update your code.

Extract a basic version scheme using legacy methods.

Parameters
[in]encodedVersionThe encoded version to extract the major version.
Returns
The major version.

References _SbgVersion::major, and sbgVersionDecode().

◆ SBG_VERSION_GET_MINOR()

SBG_INLINE uint8_t SBG_VERSION_GET_MINOR ( uint32_t  encodedVersion)

DEPRECATED method, please update your code.

Extract a basic version scheme using legacy methods.

Parameters
[in]encodedVersionThe encoded version to extract the major version.
Returns
The major version.

References _SbgVersion::minor, and sbgVersionDecode().

◆ SBG_VERSION_GET_REV()

SBG_INLINE uint8_t SBG_VERSION_GET_REV ( uint32_t  encodedVersion)

DEPRECATED method, please update your code.

Extract a basic version scheme using legacy methods.

Parameters
[in]encodedVersionThe encoded version to extract the major version.
Returns
The major version.

References _SbgVersion::rev, and sbgVersionDecode().

◆ SBG_VERSION_GET_BUILD()

SBG_INLINE uint8_t SBG_VERSION_GET_BUILD ( uint32_t  encodedVersion)

DEPRECATED method, please update your code.

Extract a basic version scheme using legacy methods

Parameters
[in]encodedVersionThe encoded version to extract the major version.
Returns
The major version.

References _SbgVersion::build, and sbgVersionDecode().