mbed_toolchain.h

00001 
00002 /** \addtogroup platform */
00003 /** @{*/
00004 /**
00005  * \defgroup platform_toolchain Toolchain functions
00006  * @{
00007  */
00008 
00009 /* mbed Microcontroller Library
00010  * Copyright (c) 2006-2013 ARM Limited
00011  *
00012  * Licensed under the Apache License, Version 2.0 (the "License");
00013  * you may not use this file except in compliance with the License.
00014  * You may obtain a copy of the License at
00015  *
00016  *     http://www.apache.org/licenses/LICENSE-2.0
00017  *
00018  * Unless required by applicable law or agreed to in writing, software
00019  * distributed under the License is distributed on an "AS IS" BASIS,
00020  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00021  * See the License for the specific language governing permissions and
00022  * limitations under the License.
00023  */
00024 #ifndef MBED_TOOLCHAIN_H
00025 #define MBED_TOOLCHAIN_H
00026 
00027 #include "mbed_preprocessor.h"
00028 
00029 
00030 // Warning for unsupported compilers
00031 #if !defined(__GNUC__)   /* GCC        */ \
00032  && !defined(__CC_ARM)   /* ARMCC      */ \
00033  && !defined(__clang__)  /* LLVM/Clang */ \
00034  && !defined(__ICCARM__) /* IAR        */
00035 #warning "This compiler is not yet supported."
00036 #endif
00037 
00038 
00039 // Attributes
00040 
00041 /** MBED_PACKED
00042  *  Pack a structure, preventing any padding from being added between fields.
00043  *
00044  *  @code
00045  *  #include "mbed_toolchain.h"
00046  *
00047  *  MBED_PACKED(struct) foo {
00048  *      char x;
00049  *      int y;
00050  *  };
00051  *  @endcode
00052  */
00053 #ifndef MBED_PACKED
00054 #if defined(__ICCARM__)
00055 #define MBED_PACKED(struct) __packed struct
00056 #else
00057 #define MBED_PACKED(struct) struct __attribute__((packed))
00058 #endif
00059 #endif
00060 
00061 /** MBED_ALIGN(N)
00062  *  Declare a variable to be aligned on an N-byte boundary.
00063  *
00064  *  @note
00065  *  IAR does not support alignment greater than word size on the stack
00066  *
00067  *  @code
00068  *  #include "mbed_toolchain.h"
00069  *
00070  *  MBED_ALIGN(16) char a;
00071  *  @endcode
00072  */
00073 #ifndef MBED_ALIGN
00074 #if defined(__ICCARM__)
00075 #define MBED_ALIGN(N) _Pragma(MBED_STRINGIFY(data_alignment=N))
00076 #else
00077 #define MBED_ALIGN(N) __attribute__((aligned(N)))
00078 #endif
00079 #endif
00080 
00081 /** MBED_UNUSED
00082  *  Declare a function argument to be unused, suppressing compiler warnings
00083  *
00084  *  @code
00085  *  #include "mbed_toolchain.h"
00086  *
00087  *  void foo(MBED_UNUSED int arg) {
00088  *
00089  *  }
00090  *  @endcode
00091  */
00092 #ifndef MBED_UNUSED
00093 #if defined(__GNUC__) || defined(__clang__) || defined(__CC_ARM)
00094 #define MBED_UNUSED __attribute__((__unused__))
00095 #else
00096 #define MBED_UNUSED
00097 #endif
00098 #endif
00099 
00100 /** MBED_USED
00101  *  Inform the compiler that a static variable is to be retained in the object file, even if it is unreferenced.
00102  *
00103  *  @code
00104  *  #include "mbed_toolchain.h"
00105  *
00106  *  MBED_USED int foo;
00107  *
00108  *  @endcode
00109  */
00110 #ifndef MBED_USED
00111 #if defined(__GNUC__) || defined(__clang__) || defined(__CC_ARM)
00112 #define MBED_USED __attribute__((used))
00113 #elif defined(__ICCARM__)
00114 #define MBED_USED __root
00115 #else
00116 #define MBED_USED
00117 #endif
00118 #endif
00119 
00120 /** MBED_WEAK
00121  *  Mark a function as being weak.
00122  *
00123  *  @note
00124  *  Functions should only be marked as weak in the source file. The header file
00125  *  should contain a regular function declaration to insure the function is emitted.
00126  *  A function marked weak will not be emitted if an alternative non-weak
00127  *  implementation is defined.
00128  *
00129  *  @note
00130  *  Weak functions are not friendly to making code re-usable, as they can only
00131  *  be overridden once (and if they are multiply overridden the linker will emit
00132  *  no warning). You should not normally use weak symbols as part of the API to
00133  *  re-usable modules.
00134  *
00135  *  @code
00136  *  #include "mbed_toolchain.h"
00137  *
00138  *  MBED_WEAK void foo() {
00139  *      // a weak implementation of foo that can be overriden by a definition
00140  *      // without  __weak
00141  *  }
00142  *  @endcode
00143  */
00144 #ifndef MBED_WEAK
00145 #if defined(__ICCARM__)
00146 #define MBED_WEAK __weak
00147 #elif defined(__MINGW32__)
00148 #define MBED_WEAK
00149 #else
00150 #define MBED_WEAK __attribute__((weak))
00151 #endif
00152 #endif
00153 
00154 /** MBED_PURE
00155  *  Hint to the compiler that a function depends only on parameters
00156  *
00157  *  @code
00158  *  #include "mbed_toolchain.h"
00159  *
00160  *  MBED_PURE int foo(int arg){
00161  *      // no access to global variables
00162  *  }
00163  *  @endcode
00164  */
00165 #ifndef MBED_PURE
00166 #if defined(__GNUC__) || defined(__clang__) || defined(__CC_ARM)
00167 #define MBED_PURE __attribute__((const))
00168 #else
00169 #define MBED_PURE
00170 #endif
00171 #endif
00172 
00173 /** MBED_NOINLINE
00174  *  Declare a function that must not be inlined.
00175  *
00176  *  @code
00177  *  #include "mbed_toolchain.h"
00178  *
00179  *  MBED_NOINLINE void foo() {
00180  *
00181  *  }
00182  *  @endcode
00183  */
00184 #ifndef MBED_NOINLINE
00185 #if defined(__GNUC__) || defined(__clang__) || defined(__CC_ARM)
00186 #define MBED_NOINLINE __attribute__((noinline))
00187 #elif defined(__ICCARM__)
00188 #define MBED_NOINLINE _Pragma("inline=never")
00189 #else
00190 #define MBED_NOINLINE
00191 #endif
00192 #endif
00193 
00194 /** MBED_FORCEINLINE
00195  *  Declare a function that must always be inlined. Failure to inline
00196  *  such a function will result in an error.
00197  *
00198  *  @code
00199  *  #include "mbed_toolchain.h"
00200  *
00201  *  MBED_FORCEINLINE void foo() {
00202  *
00203  *  }
00204  *  @endcode
00205  */
00206 #ifndef MBED_FORCEINLINE
00207 #if defined(__GNUC__) || defined(__clang__) || defined(__CC_ARM)
00208 #define MBED_FORCEINLINE static inline __attribute__((always_inline))
00209 #elif defined(__ICCARM__)
00210 #define MBED_FORCEINLINE _Pragma("inline=forced") static
00211 #else
00212 #define MBED_FORCEINLINE static inline
00213 #endif
00214 #endif
00215 
00216 /** MBED_NORETURN
00217  *  Declare a function that will never return.
00218  *
00219  *  @code
00220  *  #include "mbed_toolchain.h"
00221  *
00222  *  MBED_NORETURN void foo() {
00223  *      // must never return
00224  *      while (1) {}
00225  *  }
00226  *  @endcode
00227  */
00228 #ifndef MBED_NORETURN
00229 #if defined(__GNUC__) || defined(__clang__) || defined(__CC_ARM)
00230 #define MBED_NORETURN __attribute__((noreturn))
00231 #elif defined(__ICCARM__)
00232 #define MBED_NORETURN __noreturn
00233 #else
00234 #define MBED_NORETURN
00235 #endif
00236 #endif
00237 
00238 /** MBED_UNREACHABLE
00239  *  An unreachable statement. If the statement is reached,
00240  *  behaviour is undefined. Useful in situations where the compiler
00241  *  cannot deduce the unreachability of code.
00242  *
00243  *  @code
00244  *  #include "mbed_toolchain.h"
00245  *
00246  *  void foo(int arg) {
00247  *      switch (arg) {
00248  *          case 1: return 1;
00249  *          case 2: return 2;
00250  *          ...
00251  *      }
00252  *      MBED_UNREACHABLE;
00253  *  }
00254  *  @endcode
00255  */
00256 #ifndef MBED_UNREACHABLE
00257 #if (defined(__GNUC__) || defined(__clang__)) && !defined(__CC_ARM)
00258 #define MBED_UNREACHABLE __builtin_unreachable()
00259 #else
00260 #define MBED_UNREACHABLE while (1)
00261 #endif
00262 #endif
00263 
00264 /** MBED_DEPRECATED("message string")
00265  *  Mark a function declaration as deprecated, if it used then a warning will be
00266  *  issued by the compiler possibly including the provided message. Note that not
00267  *  all compilers are able to display the message.
00268  *
00269  *  @code
00270  *  #include "mbed_toolchain.h"
00271  *
00272  *  MBED_DEPRECATED("don't foo any more, bar instead")
00273  *  void foo(int arg);
00274  *  @endcode
00275  */
00276 #ifndef MBED_DEPRECATED
00277 #if defined(__CC_ARM)
00278 #define MBED_DEPRECATED(M) __attribute__((deprecated))
00279 #elif defined(__GNUC__) || defined(__clang__)
00280 #define MBED_DEPRECATED(M) __attribute__((deprecated(M)))
00281 #else
00282 #define MBED_DEPRECATED(M)
00283 #endif
00284 #endif
00285 
00286 /** MBED_DEPRECATED_SINCE("version", "message string")
00287  *  Mark a function declaration as deprecated, noting that the declaration was
00288  *  deprecated on the specified version. If the function is used then a warning
00289  *  will be issued by the compiler possibly including the provided message.
00290  *  Note that not all compilers are able to display this message.
00291  *
00292  *  @code
00293  *  #include "mbed_toolchain.h"
00294  *
00295  *  MBED_DEPRECATED_SINCE("mbed-os-5.1", "don't foo any more, bar instead")
00296  *  void foo(int arg);
00297  *  @endcode
00298  */
00299 #define MBED_DEPRECATED_SINCE(D, M) MBED_DEPRECATED(M " [since " D "]")
00300 
00301 /** MBED_CALLER_ADDR()
00302  * Returns the caller of the current function.
00303  *
00304  * @note
00305  * This macro is only implemented for GCC and ARMCC.
00306  *
00307  * @code
00308  * #include "mbed_toolchain.h"
00309  *
00310  * printf("This function was called from %p", MBED_CALLER_ADDR());
00311  * @endcode
00312  *
00313  * @return Address of the calling function
00314  */
00315 #ifndef MBED_CALLER_ADDR
00316 #if (defined(__GNUC__) || defined(__clang__)) && !defined(__CC_ARM)
00317 #define MBED_CALLER_ADDR() __builtin_extract_return_addr(__builtin_return_address(0))
00318 #elif defined(__CC_ARM)
00319 #define MBED_CALLER_ADDR() __builtin_return_address(0)
00320 #else
00321 #define MBED_CALLER_ADDR() (NULL)
00322 #endif
00323 #endif
00324 
00325 #ifndef MBED_SECTION
00326 #if (defined(__GNUC__) || defined(__clang__)) || defined(__CC_ARM)
00327 #define MBED_SECTION(name) __attribute__ ((section (name)))
00328 #elif defined(__ICCARM__)
00329 #define MBED_SECTION(name) _Pragma(MBED_STRINGIFY(location=name))
00330 #else
00331 #error "Missing MBED_SECTION directive"
00332 #endif
00333 #endif
00334 
00335 /**
00336  * Macro expanding to a string literal of the enclosing function name.
00337  *
00338  * The string returned takes into account language specificity and yield human
00339  * readable content.
00340  *
00341  * As an example, if the macro is used within a C++ function then the string
00342  * literal containing the function name will contain the complete signature of
00343  * the function - including template parameters - and namespace qualifications.
00344  */
00345 #ifndef MBED_PRETTY_FUNCTION
00346 #define MBED_PRETTY_FUNCTION __PRETTY_FUNCTION__
00347 #endif
00348 
00349 #ifndef MBED_PRINTF
00350 #if defined(__GNUC__) || defined(__CC_ARM)
00351 #define MBED_PRINTF(format_idx, first_param_idx) __attribute__ ((__format__(__printf__, format_idx, first_param_idx)))
00352 #else
00353 #define MBED_PRINTF(format_idx, first_param_idx)
00354 #endif
00355 #endif
00356 
00357 #ifndef MBED_PRINTF_METHOD
00358 #if defined(__GNUC__) || defined(__CC_ARM)
00359 #define MBED_PRINTF_METHOD(format_idx, first_param_idx) __attribute__ ((__format__(__printf__, format_idx+1, first_param_idx+1)))
00360 #else
00361 #define MBED_PRINTF_METHOD(format_idx, first_param_idx)
00362 #endif
00363 #endif
00364 
00365 #ifndef MBED_SCANF
00366 #if defined(__GNUC__) || defined(__CC_ARM)
00367 #define MBED_SCANF(format_idx, first_param_idx) __attribute__ ((__format__(__scanf__, format_idx, first_param_idx)))
00368 #else
00369 #define MBED_SCANF(format_idx, first_param_idx)
00370 #endif
00371 #endif
00372 
00373 #ifndef MBED_SCANF_METHOD
00374 #if defined(__GNUC__) || defined(__CC_ARM)
00375 #define MBED_SCANF_METHOD(format_idx, first_param_idx) __attribute__ ((__format__(__scanf__, format_idx+1, first_param_idx+1)))
00376 #else
00377 #define MBED_SCANF_METHOD(format_idx, first_param_idx)
00378 #endif
00379 #endif
00380 
00381 // Macro containing the filename part of the value of __FILE__. Defined as
00382 // string literal.
00383 #ifndef MBED_FILENAME
00384 #if defined(__CC_ARM)
00385 #define MBED_FILENAME __MODULE__
00386 #elif defined(__GNUC__)
00387 #define MBED_FILENAME (__builtin_strrchr(__FILE__, '/') ? __builtin_strrchr(__FILE__, '/') + 1 : __builtin_strrchr(__FILE__, '\\') ? __builtin_strrchr(__FILE__, '\\') + 1 : __FILE__)
00388 #elif defined(__ICCARM__)
00389 #define MBED_FILENAME (strrchr(__FILE__, '/') ? strrchr(__FILE__, '/') + 1 : strrchr(__FILE__, '\\') ? strrchr(__FILE__, '\\') + 1 : __FILE__)
00390 #else
00391 #define MBED_FILENAME __FILE__
00392 #endif
00393 #endif // #ifndef MBED_FILENAME
00394 
00395 // FILEHANDLE declaration
00396 #if defined(TOOLCHAIN_ARM)
00397 #include <rt_sys.h>
00398 #endif
00399 
00400 #ifndef FILEHANDLE
00401 typedef int FILEHANDLE;
00402 #endif
00403 
00404 // Backwards compatibility
00405 #ifndef WEAK
00406 #define WEAK MBED_WEAK
00407 #endif
00408 
00409 #ifndef PACKED
00410 #define PACKED MBED_PACKED()
00411 #endif
00412 
00413 #ifndef EXTERN
00414 #define EXTERN extern
00415 #endif
00416 
00417 /** MBED_NONSECURE_ENTRY
00418  *  Declare a function that can be called from non-secure world or secure world
00419  *
00420  *  @code
00421  *  #include "mbed_toolchain.h"
00422  *
00423  *  MBED_NONSECURE_ENTRY void foo() {
00424  *
00425  *  }
00426  *  @endcode
00427  */
00428 #if defined (__ARM_FEATURE_CMSE) && (__ARM_FEATURE_CMSE == 3L)
00429 #if defined (__ICCARM__)
00430 #define MBED_NONSECURE_ENTRY       __cmse_nonsecure_entry
00431 #else
00432 #define MBED_NONSECURE_ENTRY       __attribute__((cmse_nonsecure_entry))
00433 #endif
00434 #else
00435 #define MBED_NONSECURE_ENTRY
00436 #endif
00437 
00438 #endif
00439 
00440 /** @}*/
00441 /** @}*/