drivers/gpu/arm/midgard/malisw/mali_malisw.h

   1 /*
   2  *
   3  * (C) COPYRIGHT ARM Limited. All rights reserved.
   4  *
   5  * This program is free software and is provided to you under the terms of the
   6  * GNU General Public License version 2 as published by the Free Software
   7  * Foundation, and any use by you of this program is subject to the terms
   8  * of such GNU licence.
   9  *
  10  * A copy of the licence is included with the program, and can also be obtained
  11  * from Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  12  * Boston, MA  02110-1301, USA.
  13  *
  14  */
  15
  16
  17
  18
  19
  20 #ifndef _MALISW_H_
  21 #define _MALISW_H_
  22
  23 /**
  24  * @file mali_malisw.h
  25  * Driver-wide include for common macros and types.
  26  */
  27
  28 /**
  29  * @defgroup malisw Mali software definitions and types
  30  * @{
  31  */
  32
  33 #include <stddef.h>
  34
  35 #include "mali_stdtypes.h"
  36
  37 /** @brief Gets the container object when given a pointer to a member of an object. */
  38 #define CONTAINER_OF(ptr, type, member) ((type *)((char *)(ptr) - offsetof(type,member)))
  39
  40 /** @brief Gets the number of elements of type s in a fixed length array of s */
  41 #define NELEMS(s)       (sizeof(s)/sizeof((s)[0]))
  42
  43 /**
  44  * @brief The lesser of two values.
  45  * May evaluate its arguments more than once.
  46  * @see CSTD_MIN
  47  */
  48 #define MIN(x,y) CSTD_MIN(x,y)
  49
  50 /**
  51  * @brief The greater of two values.
  52  * May evaluate its arguments more than once.
  53  * @see CSTD_MAX
  54  */
  55 #define MAX(x,y) CSTD_MAX(x,y)
  56
  57 /**
  58  * @brief Clamp value x to within min and max inclusive
  59  * May evaluate its arguments more than once.
  60  * @see CSTD_CLAMP
  61  */
  62 #define CLAMP( x, min, max ) CSTD_CLAMP( x, min, max )
  63
  64 /**
  65  * @brief Convert a pointer into a u64 for storing in a data structure.
  66  * This is commonly used when pairing a 32-bit CPU with a 64-bit peripheral,
  67  * such as a Midgard GPU. C's type promotion is complex and a straight cast
  68  * does not work reliably as pointers are often considered as signed.
  69  */
  70 #define PTR_TO_U64( x ) CSTD_PTR_TO_U64( x )
  71
  72 /**
  73  * @name Mali library linkage specifiers
  74  * These directly map to the cstd versions described in detail here: @ref arm_cstd_linkage_specifiers
  75  * @{
  76  */
  77 #define MALI_IMPORT CSTD_LINK_IMPORT
  78 #define MALI_EXPORT CSTD_LINK_EXPORT
  79 #define MALI_IMPL   CSTD_LINK_IMPL
  80 #define MALI_LOCAL  CSTD_LINK_LOCAL
  81
  82 /** @brief Decorate exported function prototypes.
  83  *
  84  * The file containing the implementation of the function should define this to be MALI_EXPORT before including
  85  * malisw/mali_malisw.h.
  86  */
  87 #ifndef MALI_API
  88 #define MALI_API MALI_IMPORT
  89 #endif
  90 /** @} */
  91
  92 /** @name Testable static functions
  93  * @{
  94  *
  95  * These macros can be used to allow functions to be static in release builds but exported from a shared library in unit
  96  * test builds, allowing them to be tested or used to assist testing.
  97  *
  98  * Example mali_foo_bar.c containing the function to test:
  99  *
 100  * @code
 101  * #define MALI_API MALI_EXPORT
 102  *
 103  * #include <malisw/mali_malisw.h>
 104  * #include "mali_foo_testable_statics.h"
 105  *
 106  * MALI_TESTABLE_STATIC_IMPL void my_func()
 107  * {
 108  *      //Implementation
 109  * }
 110  * @endcode
 111  *
 112  * Example mali_foo_testable_statics.h:
 113  *
 114  * @code
 115  * #if 1 == MALI_UNIT_TEST
 116  * #include <malisw/mali_malisw.h>
 117  *
 118  * MALI_TESTABLE_STATIC_API void my_func();
 119  *
 120  * #endif
 121  * @endcode
 122  *
 123  * Example mali_foo_tests.c:
 124  *
 125  * @code
 126  * #include <foo/src/mali_foo_testable_statics.h>
 127  *
 128  * void my_test_func()
 129  * {
 130  *      my_func();
 131  * }
 132  * @endcode
 133  */
 134
 135 /** @brief Decorate testable static function implementations.
 136  *
 137  * A header file containing a MALI_TESTABLE_STATIC_API-decorated prototype for each static function will be required
 138  * when MALI_UNIT_TEST == 1 in order to link the function from the test.
 139  */
 140 #if 1 == MALI_UNIT_TEST
 141 #define MALI_TESTABLE_STATIC_IMPL MALI_IMPL
 142 #else
 143 #define MALI_TESTABLE_STATIC_IMPL static
 144 #endif
 145
 146 /** @brief Decorate testable static function prototypes.
 147  *
 148  * @note Prototypes should @em only be declared when MALI_UNIT_TEST == 1
 149  */
 150 #define MALI_TESTABLE_STATIC_API MALI_API
 151 /** @} */
 152
 153 /** @name Testable local functions
 154  * @{
 155  *
 156  * These macros can be used to allow functions to be local to a shared library in release builds but be exported in unit
 157  * test builds, allowing them to be tested or used to assist testing.
 158  *
 159  * Example mali_foo_bar.c containing the function to test:
 160  *
 161  * @code
 162  * #define MALI_API MALI_EXPORT
 163  *
 164  * #include <malisw/mali_malisw.h>
 165  * #include "mali_foo_bar.h"
 166  *
 167  * MALI_TESTABLE_LOCAL_IMPL void my_func()
 168  * {
 169  *      //Implementation
 170  * }
 171  * @endcode
 172  *
 173  * Example mali_foo_bar.h:
 174  *
 175  * @code
 176  * #include <malisw/mali_malisw.h>
 177  *
 178  * MALI_TESTABLE_LOCAL_API void my_func();
 179  *
 180  * @endcode
 181  *
 182  * Example mali_foo_tests.c:
 183  *
 184  * @code
 185  * #include <foo/src/mali_foo_bar.h>
 186  *
 187  * void my_test_func()
 188  * {
 189  *      my_func();
 190  * }
 191  * @endcode
 192  */
 193
 194 /** @brief Decorate testable local function implementations.
 195  *
 196  * This can be used to have a function normally local to the shared library except in debug builds where it will be
 197  * exported.
 198  */
 199 #ifdef CONFIG_MALI_DEBUG
 200 #define MALI_TESTABLE_LOCAL_IMPL MALI_IMPL
 201 #else
 202 #define MALI_TESTABLE_LOCAL_IMPL MALI_LOCAL
 203 #endif /* CONFIG_MALI_DEBUG */
 204
 205 /** @brief Decorate testable local function prototypes.
 206  *
 207  * This can be used to have a function normally local to the shared library except in debug builds where it will be
 208  * exported.
 209  */
 210 #ifdef CONFIG_MALI_DEBUG
 211 #define MALI_TESTABLE_LOCAL_API MALI_API
 212 #else
 213 #define MALI_TESTABLE_LOCAL_API MALI_LOCAL
 214 #endif /* CONFIG_MALI_DEBUG */
 215 /** @} */
 216
 217 /**
 218  * Flag a cast as a reinterpretation, usually of a pointer type.
 219  * @see CSTD_REINTERPRET_CAST
 220  */
 221 #define REINTERPRET_CAST(type) CSTD_REINTERPRET_CAST(type)
 222
 223 /**
 224  * Flag a cast as casting away const, usually of a pointer type.
 225  * @see CSTD_CONST_CAST
 226  */
 227 #define CONST_CAST(type) (type) CSTD_CONST_CAST(type)
 228
 229 /**
 230  * Flag a cast as a (potentially complex) value conversion, usually of a numerical type.
 231  * @see CSTD_STATIC_CAST
 232  */
 233 #define STATIC_CAST(type) (type) CSTD_STATIC_CAST(type)
 234
 235
 236 /** @} */
 237
 238 #endif /* _MALISW_H_ */