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.
hardware_samsung/exynos5/hal/include/malisw/mali_version_macros.h

244 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_ */