mbed library sources. Supersedes mbed-src.

Dependents:   Nucleo_Hello_Encoder BLE_iBeaconScan AM1805_DEMO DISCO-F429ZI_ExportTemplate1 ... more

Embed: (wiki syntax)

« Back to documentation index

Show/hide line numbers mbed_toolchain.h Source File

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