mbed_toolchain.h

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