You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
243 lines
8.3 KiB
243 lines
8.3 KiB
/*
|
|
*
|
|
* (C) COPYRIGHT 2010-2011 ARM Limited. All rights reserved.
|
|
*
|
|
* This program is free software and is provided to you under the terms of the GNU General Public License version 2
|
|
* as published by the Free Software Foundation, and any use by you of this program is subject to the terms of such GNU licence.
|
|
*
|
|
* A copy of the licence is included with the program, and can also be obtained from Free Software
|
|
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
|
|
*
|
|
*/
|
|
|
|
|
|
|
|
#ifndef _MALISW_VERSION_MACROS_H_
|
|
#define _MALISW_VERSION_MACROS_H_
|
|
|
|
/**
|
|
* @file mali_version_macros.h
|
|
* Mali version control macros.
|
|
*/
|
|
|
|
/**
|
|
* @addtogroup malisw
|
|
* @{
|
|
*/
|
|
|
|
/**
|
|
* @defgroup malisw_version Mali module version control
|
|
*
|
|
* This file provides a set of macros used to check a module's version. This
|
|
* version information can be used to perform compile time checks of a module's
|
|
* suitability for use with another.
|
|
*
|
|
* Module versions have both a Major and Minor value which specify the version
|
|
* of the interface only. These are defined in the following way:
|
|
*
|
|
* @li Major: This version is incremented whenever a compatibility-breaking
|
|
* change is made. For example, removing an interface function.
|
|
* @li Minor: This version is incremented whenever an interface change is made
|
|
* that does not break compatibility. For example, adding a new function to the
|
|
* interface. This value is reset to zero whenever the major number is
|
|
* incremented.
|
|
*
|
|
* When providing a driver module that will be used with this system, the public
|
|
* header must include a major and minor define of the following form:
|
|
*
|
|
* @code
|
|
* #define MALI_MODULE_<module>_MAJOR X
|
|
* #define MALI_MODULE_<module>_MINOR Y
|
|
* @endcode
|
|
* e.g. for a module CZAM with include czam/mali_czam.h
|
|
* @code
|
|
*
|
|
* #define MALI_MODULE_CZAM_MAJOR 1
|
|
* #define MALI_MODULE_CZAM_MINOR 0
|
|
* @endcode
|
|
*
|
|
* The version assertion macros outlined below are wrapped with a static function.
|
|
* This provides more useful error messages when the assertions fail, and allows
|
|
* the assertions to be specified adjacent to the inclusion of the module header.
|
|
*
|
|
* These macros should be used in the global scope of the file. Normal use would be:
|
|
*
|
|
* @code
|
|
* #include <modulex/mali_modulex.h>
|
|
* #include <moduley/mali_moduley.h>
|
|
* #include <modulez/mali_modulez.h>
|
|
* #include <modulez/mali_modulew.h>
|
|
*
|
|
* // This module added an enum we needed on minor 4 of major release 2
|
|
* MALI_MODULE_ASSERT_MAJOR_EQUALS_MINOR_AT_LEAST( MODULEW, 2, 4 )
|
|
*
|
|
* // this module really needs to be a specific version
|
|
* MALI_MODULE_ASSERT_EQUALS( MODULEX, 2, 0 )
|
|
*
|
|
* // 1.4 has performance problems
|
|
* MALI_MODULE_ASSERT_MAXIMUM( MODULEY, 1, 3 )
|
|
*
|
|
* // Major defines a backward compatible series of versions
|
|
* MALI_MODULE_ASSERT_MAJOR_EQUALS( MODULEZ, 1 )
|
|
* @endcode
|
|
*
|
|
* @par Version Assertions
|
|
*
|
|
* This module provides the following compile time version assertion macros.
|
|
*
|
|
* @li #MALI_MODULE_ASSERT_MAJOR_EQUALS_MINOR_AT_LEAST
|
|
* @li #MALI_MODULE_ASSERT_MAJOR_EQUALS
|
|
* @li #MALI_MODULE_ASSERT_EQUALS
|
|
* @li #MALI_MODULE_ASSERT_MINIMUM
|
|
* @li #MALI_MODULE_ASSERT_MAXIMUM
|
|
*
|
|
* @par Limitations
|
|
*
|
|
* To allow the macros to be placed in the global scope and report more readable
|
|
* errors, they produce a static function. This makes them unsuitable for use
|
|
* within headers as the names are only unique on the name of the module under test,
|
|
* the line number of the current file, and assert type (min, max, equals, ...).
|
|
*/
|
|
|
|
/**
|
|
* @addtogroup malisw_version
|
|
* @{
|
|
*/
|
|
|
|
#include "arm_cstd/arm_cstd.h"
|
|
|
|
/**
|
|
* Private helper macro, indirection so that __LINE__ resolves correctly.
|
|
*/
|
|
#define MALIP_MODULE_ASSERT_FUNCTION_SIGNATURE2( module, type, line ) \
|
|
static INLINE void _mali_module_##module##_version_check_##type##_##line(void)
|
|
|
|
#define MALIP_MODULE_ASSERT_FUNCTION_SIGNATURE( module, type, line ) \
|
|
MALIP_MODULE_ASSERT_FUNCTION_SIGNATURE2( module, type, line )
|
|
|
|
/**
|
|
* @hideinitializer
|
|
* This macro provides a compile time assert that a module interface that has been
|
|
* @#included in the source base has is greater than or equal to the version specified.
|
|
*
|
|
* Expected use is for cases where a module version before the requested minimum
|
|
* does not support a specific function or is missing an enum affecting the code that is
|
|
* importing the module.
|
|
*
|
|
* It should be invoked at the global scope and ideally following straight after
|
|
* the module header has been included. For example:
|
|
*
|
|
* @code
|
|
* #include <modulex/mali_modulex.h>
|
|
*
|
|
* MALI_MODULE_ASSERT_MINIMUM( MODULEX, 1, 3 )
|
|
* @endcode
|
|
*/
|
|
#define MALI_MODULE_ASSERT_MINIMUM( module, major, minor ) \
|
|
MALIP_MODULE_ASSERT_FUNCTION_SIGNATURE( module, minimum, __LINE__ ) \
|
|
{ \
|
|
CSTD_COMPILE_TIME_ASSERT( ( ( MALI_MODULE_##module##_MAJOR << 16 ) | MALI_MODULE_##module##_MINOR ) \
|
|
>= ( ( (major) << 16 ) | (minor) ) ); \
|
|
}
|
|
|
|
/**
|
|
* @hideinitializer
|
|
* This macro provides a compile time assert that a module interface that has been
|
|
* @#included in the source base is less than or equal to the version specified.
|
|
*
|
|
* Expected use is for cases where a later published minor version is found to be
|
|
* incompatible in some way after the new minor has been issued.
|
|
*
|
|
* It should be invoked at the global scope and ideally following straight after
|
|
* the module header has been included. For example:
|
|
*
|
|
* @code
|
|
* #include <modulex/mali_modulex.h>
|
|
*
|
|
* MALI_MODULE_ASSERT_MAXIMUM( MODULEX, 1, 3 )
|
|
* @endcode
|
|
*/
|
|
#define MALI_MODULE_ASSERT_MAXIMUM( module, major, minor ) \
|
|
MALIP_MODULE_ASSERT_FUNCTION_SIGNATURE( module, maximum, __LINE__ ) \
|
|
{ \
|
|
CSTD_COMPILE_TIME_ASSERT( ( ( MALI_MODULE_##module##_MAJOR << 16 ) | MALI_MODULE_##module##_MINOR ) \
|
|
<= ( ( (major) << 16 ) | (minor) ) ); \
|
|
}
|
|
|
|
/**
|
|
* @hideinitializer
|
|
* This macro provides a compile time assert that a module interface that has been
|
|
* @#included in the source base is equal to the version specified.
|
|
*
|
|
* Expected use is for cases where a specific version is known to work and other
|
|
* versions are considered to be risky.
|
|
*
|
|
* It should be invoked at the global scope and ideally following straight after
|
|
* the module header has been included. For example:
|
|
*
|
|
* @code
|
|
* #include <modulex/mali_modulex.h>
|
|
*
|
|
* MALI_MODULE_ASSERT_EQUALS( MODULEX, 1, 3 )
|
|
* @endcode
|
|
*/
|
|
#define MALI_MODULE_ASSERT_EQUALS( module, major, minor ) \
|
|
MALIP_MODULE_ASSERT_FUNCTION_SIGNATURE( module, equals, __LINE__ ) \
|
|
{ \
|
|
CSTD_COMPILE_TIME_ASSERT( MALI_MODULE_##module##_MAJOR == major ); \
|
|
CSTD_COMPILE_TIME_ASSERT( MALI_MODULE_##module##_MINOR == minor ); \
|
|
}
|
|
|
|
/**
|
|
* @hideinitializer
|
|
* This macro provides a compile time assert that a module interface that has been
|
|
* @#included in the source base has a major version equal to the major version specified.
|
|
*
|
|
* Expected use is for cases where a module is considered low risk and any minor changes
|
|
* are not considered to be important.
|
|
*
|
|
* It should be invoked at the global scope and ideally following straight after
|
|
* the module header has been included. For example:
|
|
*
|
|
* @code
|
|
* #include <modulex/mali_modulex.h>
|
|
*
|
|
* MALI_MODULE_ASSERT_MAJOR_EQUALS( MODULEX, 1, 3 )
|
|
* @endcode
|
|
*/
|
|
#define MALI_MODULE_ASSERT_MAJOR_EQUALS( module, major ) \
|
|
MALIP_MODULE_ASSERT_FUNCTION_SIGNATURE( module, major_equals, __LINE__ ) \
|
|
{ \
|
|
CSTD_COMPILE_TIME_ASSERT( MALI_MODULE_##module##_MAJOR == major ); \
|
|
}
|
|
|
|
/**
|
|
* @hideinitializer
|
|
* This macro provides a compile time assert that a module interface that has been
|
|
* @#included in the source base has a major version equal to the major version specified
|
|
* and that the minor version is at least that which is specified.
|
|
*
|
|
* Expected use is for cases where a major revision is suitable from a specific minor
|
|
* revision but future major versions are a risk.
|
|
*
|
|
* It should be invoked at the global scope and ideally following straight after
|
|
* the module header has been included. For example:
|
|
*
|
|
* @code
|
|
* #include <modulex/mali_modulex.h>
|
|
*
|
|
* MALI_MODULE_ASSERT_MAJOR_EQUALS_MINOR_AT_LEAST( MODULEX, 1, 3 )
|
|
* @endcode
|
|
*/
|
|
#define MALI_MODULE_ASSERT_MAJOR_EQUALS_MINOR_AT_LEAST( module, major, minor ) \
|
|
MALIP_MODULE_ASSERT_FUNCTION_SIGNATURE( module, major_equals_minor_at_least, __LINE__ ) \
|
|
{ \
|
|
CSTD_COMPILE_TIME_ASSERT( MALI_MODULE_##module##_MAJOR == major ); \
|
|
CSTD_COMPILE_TIME_ASSERT( MALI_MODULE_##module##_MINOR >= minor ); \
|
|
}
|
|
|
|
/* @} */
|
|
|
|
/* @} */
|
|
|
|
#endif /* _MALISW_VERSION_MACROS_H_ */
|
|
|