sbgVersion.h File Reference

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

#include <sbgCommon.h>

Include dependency graph for sbgVersion.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	_SbgVersion

Macros
#define	SBG_VERSION_BASIC(major, minor, rev, build)
#define	SBG_VERSION_SOFT_SCHEME   (0x00000001u << 31)
#define	SBG_VERSION_SOFT_SCHEME_BUILD_MASK   (0xFFFF)
#define	SBG_VERSION_SOFT_SCHEME_BUILD_SHIFT   (0)
#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_QUALIFIER_MASK   (0x07)
#define	SBG_VERSION_SOFT_SCHEME_QUALIFIER_SHIFT   (28)
#define	SBG_VERSION_SOFTWARE(major, minor, build, qualifier)

Typedefs
typedef struct _SbgVersion	SbgVersion
typedef enum _SbgVersionCmpThresold	SbgVersionCmpThresold
typedef enum _SbgVersionQualifier	SbgVersionQualifier

Enumerations
enum	_SbgVersionCmpThresold {   SBG_VERSION_CMP_THRESOLD_MAJOR = 0, SBG_VERSION_CMP_THRESOLD_MINOR = 1, SBG_VERSION_CMP_THRESOLD_REVISION = 2, SBG_VERSION_CMP_THRESOLD_BUILD = 3,   SBG_VERSION_CMP_THRESOLD_QUALIFIER = 4 }
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 }

Functions
	SBG_DEPRECATED (SBG_INLINE uint32_t SBG_VERSION(uint8_t major, uint8_t minor, uint8_t rev, uint8_t build))
	SBG_DEPRECATED (SBG_INLINE uint8_t SBG_VERSION_GET_MAJOR(uint32_t encodedVersion))
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_BUILD (uint32_t encodedVersion)
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_COMMON_LIB_API int32_t	sbgVersionCompare (const SbgVersion *pVersionA, const SbgVersion *pVersionB, SbgVersionCmpThresold thresold)
SBG_COMMON_LIB_API int32_t	sbgVersionCompareEncoded (uint32_t versionA, uint32_t versionB, SbgVersionCmpThresold thresold)
SBG_COMMON_LIB_API void	sbgVersionDecode (uint32_t encodedVersion, SbgVersion *pVersionInfo)
SBG_COMMON_LIB_API uint32_t	sbgVersionEncode (const SbgVersion *pVersionInfo)
SBG_COMMON_LIB_API SbgErrorCode	sbgVersionFromString (const char *pVersionStr, SbgVersion *pVersionInfo)
SBG_COMMON_LIB_API SbgErrorCode	sbgVersionFromStringEncoded (const char *pVersionStr, uint32_t *pVersion)
SBG_INLINE bool	sbgVersionIsUsingSoftwareScheme (uint32_t encodedVersion)
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, uint32_t sizeOfBuffer)
SBG_COMMON_LIB_API SbgErrorCode	sbgVersionToStringEncoded (uint32_t version, char *pBuffer, uint32_t sizeOfBuffer)

Detailed Description

Helper methods and definitions used to handle version.

Author

SBG Systems (Raphael Siryani)

Date

23 April 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

Copyright Notice

Copyright (C) 2007-2015, SBG Systems SAS. All rights reserved.

This source code is intended for use only by SBG Systems SAS and those that have explicit written permission to use it from SBG Systems SAS.

THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR PURPOSE.

Definition in file sbgVersion.h.

Macro Definition Documentation

#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]	maj	The major version between 0 to 127.
[in]	min	The minor version between 0 to 255.
[in]	rev	The revision version between 0 to 255.
[in]	build	The build number between 0 to 255.

Returns

The encoded version number.

Definition at line 118 of file sbgVersion.h.

#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.

Definition at line 49 of file sbgVersion.h.

#define SBG_VERSION_SOFT_SCHEME_BUILD_MASK   (0xFFFF)

Mask used to keep only the build version field.

Definition at line 60 of file sbgVersion.h.

#define SBG_VERSION_SOFT_SCHEME_BUILD_SHIFT   (0)

Bitshift used to get the build version field.

Definition at line 61 of file sbgVersion.h.

#define SBG_VERSION_SOFT_SCHEME_MAJOR_MASK   (0x3F)

Mask used to keep only the major version field.

Definition at line 54 of file sbgVersion.h.

#define SBG_VERSION_SOFT_SCHEME_MAJOR_SHIFT   (22)

Bitshift used to get the major version field.

Definition at line 55 of file sbgVersion.h.

#define SBG_VERSION_SOFT_SCHEME_MINOR_MASK   (0x3F)

Mask used to keep only the minor version field.

Definition at line 57 of file sbgVersion.h.

#define SBG_VERSION_SOFT_SCHEME_MINOR_SHIFT   (16)

Bitshift used to get the minor version field.

Definition at line 58 of file sbgVersion.h.

#define SBG_VERSION_SOFT_SCHEME_QUALIFIER_MASK   (0x07)

Mask used to keep only the version qualifier enum.

Definition at line 51 of file sbgVersion.h.

#define SBG_VERSION_SOFT_SCHEME_QUALIFIER_SHIFT   (28)

Bitshift to apply to get the qualifier enum.

Definition at line 52 of file sbgVersion.h.

#define SBG_VERSION_SOFTWARE	(		major,
			minor,
			build,
			qualifier
	)

Value:

(       SBG_VERSION_SOFT_SCHEME |                                                                                                                                                                               \
                                                                                                                                                ((((uint32_t)(qualifier)) & SBG_VERSION_SOFT_SCHEME_QUALIFIER_MASK) << SBG_VERSION_SOFT_SCHEME_QUALIFIER_SHIFT) |       \
                                                                                                                                                ((((uint32_t)(major)) & SBG_VERSION_SOFT_SCHEME_MAJOR_MASK) << SBG_VERSION_SOFT_SCHEME_MAJOR_SHIFT)             |               \
                                                                                                                                                ((((uint32_t)(minor)) & SBG_VERSION_SOFT_SCHEME_MINOR_MASK) << SBG_VERSION_SOFT_SCHEME_MINOR_SHIFT)             |               \
                                                                                                                                                ((((uint32_t)(build)) & SBG_VERSION_SOFT_SCHEME_BUILD_MASK) << SBG_VERSION_SOFT_SCHEME_BUILD_SHIFT)             )

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

Parameters

[in]	major	The major version between 0 to 63.
[in]	minor	The major version between 0 to 63.
[in]	build	The major version between 0 to 65535.
[in]	qualifier	The version qualifier within the SbgVersionQualifier enum.

Returns

The encoded version number.

Definition at line 131 of file sbgVersion.h.

Typedef Documentation

typedef struct _SbgVersion SbgVersion

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

typedef enum _SbgVersionCmpThresold SbgVersionCmpThresold

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.

typedef enum _SbgVersionQualifier 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.

Enumeration Type Documentation

enum _SbgVersionCmpThresold

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_CMP_THRESOLD_MAJOR	Compare only the major field.
SBG_VERSION_CMP_THRESOLD_MINOR	Compare the major and minor fields.
SBG_VERSION_CMP_THRESOLD_REVISION	Compare the major, minor and revision fields (only for basic versions).
SBG_VERSION_CMP_THRESOLD_BUILD	Compare the major, minor, revision and build fields.
SBG_VERSION_CMP_THRESOLD_QUALIFIER	Compare the major, minor, revision, build and qualifier fields (only for software scheme).

Definition at line 83 of file sbgVersion.h.

enum _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.

Definition at line 68 of file sbgVersion.h.

Function Documentation

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_DEPRECATED

(

SBG_INLINE uint8_t

SBG_VERSION_GET_MAJORuint32_t encodedVersion

)

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]	maj	The major version between 0 to 127.
[in]	min	The minor version between 0 to 255.
[in]	rev	The revision version between 0 to 255.
[in]	build	The build number between 0 to 255.

Returns

The encoded version number.

Definition at line 300 of file sbgVersion.h.

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]

encodedVersion

The encoded version to extract the major version.

Returns

The major version.

Definition at line 377 of file sbgVersion.h.

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]

encodedVersion

The encoded version to extract the major version.

Returns

The major version.

Definition at line 314 of file sbgVersion.h.

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]

encodedVersion

The encoded version to extract the major version.

Returns

The major version.

Definition at line 335 of file sbgVersion.h.

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]

encodedVersion

The encoded version to extract the major version.

Returns

The major version.

Definition at line 356 of file sbgVersion.h.

SBG_COMMON_LIB_API int32_t sbgVersionCompare	(	const SbgVersion *	pVersionA,
		const SbgVersion *	pVersionB,
		SbgVersionCmpThresold	thresold
	)

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]	pVersionA	The first version to compare.
[in]	pVersionB	The second version to compare.
[in]	thresold	The comparaison thresold 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 thresold).

Definition at line 123 of file sbgVersion.c.

SBG_COMMON_LIB_API int32_t sbgVersionCompareEncoded	(	uint32_t	versionA,
		uint32_t	versionB,
		SbgVersionCmpThresold	thresold
	)

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]	versionA	The first compiled version to compare.
[in]	versionB	The second compiled version to compare.
[in]	thresold	The comparaison thresold 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 thresold).

Definition at line 226 of file sbgVersion.c.

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]	encodedVersion	The version information stored within a uint32_t.
[out]	pVersionInfo	Pointer on an allocated SbgVersion structure to fill.

Definition at line 12 of file sbgVersion.c.

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]

pVersionInfo

Pointer on a read only version structure to encode.

Returns

The encoded version information on an uint32_t or 0 if an error has occurred.

Definition at line 69 of file sbgVersion.c.

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

Convert a human readable string to a version structure.

Parameters

[in]	pVersionStr	The string containing the version to convert.
[out]	pVersionInfo	Pointer to a version structure to store the parsed version info.

Returns

SBG_NO_ERROR if the version information has been converted from a string.

Definition at line 439 of file sbgVersion.c.

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

Convert an encoded version number to a human readable string.

Parameters

[in]	pVersionStr	The string containing the version to convert.
[out]	pVersion	Returned encoded version value parsed from the string.

Returns

SBG_NO_ERROR if the version information has been converted from a string.

Definition at line 560 of file sbgVersion.c.

SBG_INLINE bool sbgVersionIsUsingSoftwareScheme

(

uint32_t

encodedVersion

)

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

Parameters

[in]

encodedVersion

The encoded version number to test stored in a uint32_t.

Returns

true if the version number is using a software scheme.

Definition at line 164 of file sbgVersion.h.

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]	pLowerVersion	The lower version bound of the interval.
[in]	pHigherVersion	The hiver version bound of the interval.
[in]	pVersion	The 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

Definition at line 254 of file sbgVersion.c.

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]	lowerVersion	The lower version bound of the interval.
[in]	higherVersion	The hiver version bound of the interval.
[in]	version	The 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

Definition at line 277 of file sbgVersion.c.

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

Convert a version information to a human readable string.

Parameters

[in]	pVersionInfo	Pointer on a read only version structure to convert to a human readable string.
[out]	pBuffer	Buffer to store the version as a human readable null terminated string.
[in]	sizeOfBuffer	Maximum 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.

Definition at line 317 of file sbgVersion.c.

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

Convert an encoded version number to a human readable string.

Parameters

[in]	version	Encoded version value to to convert to a human readable string.
[out]	pBuffer	Buffer to store the version as a human readable null terminated string.
[in]	sizeOfBuffer	Maximum 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.

Definition at line 414 of file sbgVersion.c.