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 #else
00148 #define MBED_WEAK __attribute__((weak))
00149 #endif
00150 #endif
00151 
00152 /** MBED_PURE
00153  *  Hint to the compiler that a function depends only on parameters
00154  *
00155  *  @code
00156  *  #include "mbed_toolchain.h"
00157  *
00158  *  MBED_PURE int foo(int arg){
00159  *      // no access to global variables
00160  *  }
00161  *  @endcode
00162  */
00163 #ifndef MBED_PURE
00164 #if defined(__GNUC__) || defined(__clang__) || defined(__CC_ARM)
00165 #define MBED_PURE __attribute__((const))
00166 #else
00167 #define MBED_PURE
00168 #endif
00169 #endif
00170 
00171 /** MBED_NOINLINE
00172  *  Declare a function that must not be inlined.
00173  *
00174  *  @code
00175  *  #include "mbed_toolchain.h"
00176  *
00177  *  MBED_NOINLINE void foo() {
00178  *
00179  *  }
00180  *  @endcode
00181  */
00182 #ifndef MBED_NOINLINE
00183 #if defined(__GNUC__) || defined(__clang__) || defined(__CC_ARM)
00184 #define MBED_NOINLINE __attribute__((noinline))
00185 #elif defined(__ICCARM__)
00186 #define MBED_NOINLINE _Pragma("inline=never")
00187 #else
00188 #define MBED_NOINLINE
00189 #endif
00190 #endif
00191 
00192 /** MBED_FORCEINLINE
00193  *  Declare a function that must always be inlined. Failure to inline
00194  *  such a function will result in an error.
00195  *
00196  *  @code
00197  *  #include "mbed_toolchain.h"
00198  *
00199  *  MBED_FORCEINLINE void foo() {
00200  *
00201  *  }
00202  *  @endcode
00203  */
00204 #ifndef MBED_FORCEINLINE
00205 #if defined(__GNUC__) || defined(__clang__) || defined(__CC_ARM)
00206 #define MBED_FORCEINLINE static inline __attribute__((always_inline))
00207 #elif defined(__ICCARM__)
00208 #define MBED_FORCEINLINE _Pragma("inline=forced") static
00209 #else
00210 #define MBED_FORCEINLINE static inline
00211 #endif
00212 #endif
00213 
00214 /** MBED_NORETURN
00215  *  Declare a function that will never return.
00216  *
00217  *  @code
00218  *  #include "mbed_toolchain.h"
00219  *
00220  *  MBED_NORETURN void foo() {
00221  *      // must never return
00222  *      while (1) {}
00223  *  }
00224  *  @endcode
00225  */
00226 #ifndef MBED_NORETURN
00227 #if defined(__GNUC__) || defined(__clang__) || defined(__CC_ARM)
00228 #define MBED_NORETURN __attribute__((noreturn))
00229 #elif defined(__ICCARM__)
00230 #define MBED_NORETURN __noreturn
00231 #else
00232 #define MBED_NORETURN
00233 #endif
00234 #endif
00235 
00236 /** MBED_UNREACHABLE
00237  *  An unreachable statement. If the statement is reached,
00238  *  behaviour is undefined. Useful in situations where the compiler
00239  *  cannot deduce the unreachability of code.
00240  *
00241  *  @code
00242  *  #include "mbed_toolchain.h"
00243  *
00244  *  void foo(int arg) {
00245  *      switch (arg) {
00246  *          case 1: return 1;
00247  *          case 2: return 2;
00248  *          ...
00249  *      }
00250  *      MBED_UNREACHABLE;
00251  *  }
00252  *  @endcode
00253  */
00254 #ifndef MBED_UNREACHABLE
00255 #if (defined(__GNUC__) || defined(__clang__)) && !defined(__CC_ARM)
00256 #define MBED_UNREACHABLE __builtin_unreachable()
00257 #else
00258 #define MBED_UNREACHABLE while (1)
00259 #endif
00260 #endif
00261 
00262 /** MBED_DEPRECATED("message string")
00263  *  Mark a function declaration as deprecated, if it used then a warning will be
00264  *  issued by the compiler possibly including the provided message. Note that not
00265  *  all compilers are able to display the message.
00266  *
00267  *  @code
00268  *  #include "mbed_toolchain.h"
00269  *
00270  *  MBED_DEPRECATED("don't foo any more, bar instead")
00271  *  void foo(int arg);
00272  *  @endcode
00273  */
00274 #ifndef MBED_DEPRECATED
00275 #if defined(__CC_ARM)
00276 #define MBED_DEPRECATED(M) __attribute__((deprecated))
00277 #elif defined(__GNUC__) || defined(__clang__)
00278 #define MBED_DEPRECATED(M) __attribute__((deprecated(M)))
00279 #else
00280 #define MBED_DEPRECATED(M)
00281 #endif
00282 #endif
00283 
00284 /** MBED_DEPRECATED_SINCE("version", "message string")
00285  *  Mark a function declaration as deprecated, noting that the declaration was
00286  *  deprecated on the specified version. If the function is used then a warning
00287  *  will be issued by the compiler possibly including the provided message.
00288  *  Note that not all compilers are able to display this message.
00289  *
00290  *  @code
00291  *  #include "mbed_toolchain.h"
00292  *
00293  *  MBED_DEPRECATED_SINCE("mbed-os-5.1", "don't foo any more, bar instead")
00294  *  void foo(int arg);
00295  *  @endcode
00296  */
00297 #define MBED_DEPRECATED_SINCE(D, M) MBED_DEPRECATED(M " [since " D "]")
00298 
00299 /** MBED_CALLER_ADDR()
00300  * Returns the caller of the current function.
00301  *
00302  * @note
00303  * This macro is only implemented for GCC and ARMCC.
00304  *
00305  * @code
00306  * #include "mbed_toolchain.h"
00307  *
00308  * printf("This function was called from %p", MBED_CALLER_ADDR());
00309  * @endcode
00310  *
00311  * @return Address of the calling function
00312  */
00313 #ifndef MBED_CALLER_ADDR
00314 #if (defined(__GNUC__) || defined(__clang__)) && !defined(__CC_ARM)
00315 #define MBED_CALLER_ADDR() __builtin_extract_return_addr(__builtin_return_address(0))
00316 #elif defined(__CC_ARM)
00317 #define MBED_CALLER_ADDR() __builtin_return_address(0)
00318 #else
00319 #define MBED_CALLER_ADDR() (NULL)
00320 #endif
00321 #endif
00322 
00323 #ifndef MBED_SECTION
00324 #if (defined(__GNUC__) || defined(__clang__)) || defined(__CC_ARM)
00325 #define MBED_SECTION(name) __attribute__ ((section (name)))
00326 #elif defined(__ICCARM__)
00327 #define MBED_SECTION(name) _Pragma(MBED_STRINGIFY(location=name))
00328 #else
00329 #error "Missing MBED_SECTION directive"
00330 #endif
00331 #endif
00332 
00333 /**
00334  * Macro expanding to a string literal of the enclosing function name.
00335  *
00336  * The string returned takes into account language specificity and yield human
00337  * readable content.
00338  *
00339  * As an example, if the macro is used within a C++ function then the string
00340  * literal containing the function name will contain the complete signature of
00341  * the function - including template parameters - and namespace qualifications.
00342  */
00343 #ifndef MBED_PRETTY_FUNCTION
00344 #define MBED_PRETTY_FUNCTION __PRETTY_FUNCTION__
00345 #endif
00346 
00347 #ifndef MBED_PRINTF
00348 #if defined(__GNUC__) || defined(__CC_ARM)
00349 #define MBED_PRINTF(format_idx, first_param_idx) __attribute__ ((__format__(__printf__, format_idx, first_param_idx)))
00350 #else
00351 #define MBED_PRINTF(format_idx, first_param_idx)
00352 #endif
00353 #endif
00354 
00355 #ifndef MBED_PRINTF_METHOD
00356 #if defined(__GNUC__) || defined(__CC_ARM)
00357 #define MBED_PRINTF_METHOD(format_idx, first_param_idx) __attribute__ ((__format__(__printf__, format_idx+1, first_param_idx+1)))
00358 #else
00359 #define MBED_PRINTF_METHOD(format_idx, first_param_idx)
00360 #endif
00361 #endif
00362 
00363 #ifndef MBED_SCANF
00364 #if defined(__GNUC__) || defined(__CC_ARM)
00365 #define MBED_SCANF(format_idx, first_param_idx) __attribute__ ((__format__(__scanf__, format_idx, first_param_idx)))
00366 #else
00367 #define MBED_SCANF(format_idx, first_param_idx)
00368 #endif
00369 #endif
00370 
00371 #ifndef MBED_SCANF_METHOD
00372 #if defined(__GNUC__) || defined(__CC_ARM)
00373 #define MBED_SCANF_METHOD(format_idx, first_param_idx) __attribute__ ((__format__(__scanf__, format_idx+1, first_param_idx+1)))
00374 #else
00375 #define MBED_SCANF_METHOD(format_idx, first_param_idx)
00376 #endif
00377 #endif
00378 
00379 // Macro containing the filename part of the value of __FILE__. Defined as
00380 // string literal.
00381 #ifndef MBED_FILENAME
00382 #if defined(__CC_ARM)
00383 #define MBED_FILENAME __MODULE__
00384 #elif defined(__GNUC__)
00385 #define MBED_FILENAME (__builtin_strrchr(__FILE__, '/') ? __builtin_strrchr(__FILE__, '/') + 1 : __builtin_strrchr(__FILE__, '\\') ? __builtin_strrchr(__FILE__, '\\') + 1 : __FILE__)
00386 #elif defined(__ICCARM__)
00387 #define MBED_FILENAME (strrchr(__FILE__, '/') ? strrchr(__FILE__, '/') + 1 : strrchr(__FILE__, '\\') ? strrchr(__FILE__, '\\') + 1 : __FILE__)
00388 #else
00389 #define MBED_FILENAME __FILE__
00390 #endif
00391 #endif // #ifndef MBED_FILENAME
00392 
00393 // FILEHANDLE declaration
00394 #if defined(TOOLCHAIN_ARM)
00395 #include <rt_sys.h>
00396 #endif
00397 
00398 #ifndef FILEHANDLE
00399     typedef int FILEHANDLE;
00400 #endif
00401 
00402 // Backwards compatibility
00403 #ifndef WEAK
00404 #define WEAK MBED_WEAK
00405 #endif
00406 
00407 #ifndef PACKED
00408 #define PACKED MBED_PACKED()
00409 #endif
00410 
00411 #ifndef EXTERN
00412 #define EXTERN extern
00413 #endif
00414 
00415 #endif
00416 
00417 /** @}*/
00418 /** @}*/