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 
00023 // Warning for unsupported compilers
00024 #if !defined(__GNUC__)   /* GCC        */ \
00025  && !defined(__CC_ARM)   /* ARMCC      */ \
00026  && !defined(__clang__)  /* LLVM/Clang */ \
00027  && !defined(__ICCARM__) /* IAR        */
00028 #warning "This compiler is not yet supported."
00029 #endif
00030 
00031 
00032 // Attributes
00033 
00034 /** MBED_PACKED
00035  *  Pack a structure, preventing any padding from being added between fields.
00036  *
00037  *  @code
00038  *  #include "toolchain.h"
00039  *
00040  *  MBED_PACKED(struct) foo {
00041  *      char x;
00042  *      int y;
00043  *  };
00044  *  @endcode
00045  */
00046 #ifndef MBED_PACKED
00047 #if defined(__ICCARM__)
00048 #define MBED_PACKED(struct) __packed struct
00049 #else
00050 #define MBED_PACKED(struct) struct __attribute__((packed))
00051 #endif
00052 #endif
00053 
00054 /** MBED_ALIGN(N)
00055  *  Declare a variable to be aligned on an N-byte boundary.
00056  *
00057  *  @note
00058  *  IAR does not support alignment greater than word size on the stack
00059  *  
00060  *  @code
00061  *  #include "toolchain.h"
00062  *
00063  *  MBED_ALIGN(16) char a;
00064  *  @endcode
00065  */
00066 #ifndef MBED_ALIGN
00067 #if defined(__ICCARM__)
00068 #define _MBED_ALIGN(N) _Pragma(#N)
00069 #define MBED_ALIGN(N) _MBED_ALIGN(data_alignment=N)
00070 #else
00071 #define MBED_ALIGN(N) __attribute__((aligned(N)))
00072 #endif
00073 #endif
00074 
00075 /** MBED_UNUSED
00076  *  Declare a function argument to be unused, suppressing compiler warnings
00077  *
00078  *  @code
00079  *  #include "toolchain.h"
00080  *
00081  *  void foo(MBED_UNUSED int arg) {
00082  *
00083  *  }
00084  *  @endcode
00085  */
00086 #ifndef MBED_UNUSED
00087 #if defined(__GNUC__) || defined(__clang__) || defined(__CC_ARM)
00088 #define MBED_UNUSED __attribute__((__unused__))
00089 #else
00090 #define MBED_UNUSED
00091 #endif
00092 #endif
00093 
00094 /** MBED_WEAK
00095  *  Mark a function as being weak.
00096  *  
00097  *  @note
00098  *  weak functions are not friendly to making code re-usable, as they can only
00099  *  be overridden once (and if they are multiply overridden the linker will emit
00100  *  no warning). You should not normally use weak symbols as part of the API to
00101  *  re-usable modules.
00102  *  
00103  *  @code
00104  *  #include "toolchain.h"
00105  *  
00106  *  MBED_WEAK void foo() {
00107  *      // a weak implementation of foo that can be overriden by a definition
00108  *      // without  __weak
00109  *  }
00110  *  @endcode
00111  */
00112 #ifndef MBED_WEAK
00113 #if defined(__ICCARM__)
00114 #define MBED_WEAK __weak
00115 #else
00116 #define MBED_WEAK __attribute__((weak))
00117 #endif
00118 #endif
00119 
00120 /** MBED_PURE
00121  *  Hint to the compiler that a function depends only on parameters
00122  *
00123  *  @code
00124  *  #include "toolchain.h"
00125  *
00126  *  MBED_PURE int foo(int arg){
00127  *      // no access to global variables
00128  *  }
00129  *  @endcode
00130  */
00131 #ifndef MBED_PURE
00132 #if defined(__GNUC__) || defined(__clang__) || defined(__CC_ARM)
00133 #define MBED_PURE __attribute__((const))
00134 #else
00135 #define MBED_PURE
00136 #endif
00137 #endif
00138 
00139 /** MBED_FORCEINLINE
00140  *  Declare a function that must always be inlined. Failure to inline
00141  *  such a function will result in an error.
00142  *
00143  *  @code
00144  *  #include "toolchain.h"
00145  *  
00146  *  MBED_FORCEINLINE void foo() {
00147  *  
00148  *  }
00149  *  @endcode
00150  */
00151 #ifndef MBED_FORCEINLINE
00152 #if defined(__GNUC__) || defined(__clang__) || defined(__CC_ARM)
00153 #define MBED_FORCEINLINE static inline __attribute__((always_inline))
00154 #elif defined(__ICCARM__)
00155 #define MBED_FORCEINLINE _Pragma("inline=forced") static
00156 #else
00157 #define MBED_FORCEINLINE static inline
00158 #endif
00159 #endif
00160 
00161 /** MBED_NORETURN
00162  *  Declare a function that will never return.
00163  *
00164  *  @code
00165  *  #include "toolchain.h"
00166  *  
00167  *  MBED_NORETURN void foo() {
00168  *      // must never return
00169  *      while (1) {}
00170  *  }
00171  *  @endcode
00172  */
00173 #ifndef MBED_NORETURN
00174 #if defined(__GNUC__) || defined(__clang__) || defined(__CC_ARM)
00175 #define MBED_NORETURN __attribute__((noreturn))
00176 #elif defined(__ICCARM__)
00177 #define MBED_NORETURN __noreturn
00178 #else
00179 #define MBED_NORETURN
00180 #endif
00181 #endif
00182 
00183 /** MBED_UNREACHABLE
00184  *  An unreachable statement. If the statement is reached,
00185  *  behaviour is undefined. Useful in situations where the compiler
00186  *  cannot deduce the unreachability of code.
00187  *
00188  *  @code
00189  *  #include "toolchain.h"
00190  *
00191  *  void foo(int arg) {
00192  *      switch (arg) {
00193  *          case 1: return 1;
00194  *          case 2: return 2;
00195  *          ...
00196  *      }
00197  *      MBED_UNREACHABLE;
00198  *  }
00199  *  @endcode
00200  */
00201 #ifndef MBED_UNREACHABLE
00202 #if (defined(__GNUC__) || defined(__clang__)) && !defined(__CC_ARM)
00203 #define MBED_UNREACHABLE __builtin_unreachable()
00204 #else
00205 #define MBED_UNREACHABLE while (1)
00206 #endif
00207 #endif
00208 
00209 /** MBED_DEPRECATED("message string")
00210  *  Mark a function declaration as deprecated, if it used then a warning will be
00211  *  issued by the compiler possibly including the provided message. Note that not
00212  *  all compilers are able to display the message.
00213  *
00214  *  @code
00215  *  #include "toolchain.h"
00216  *  
00217  *  MBED_DEPRECATED("don't foo any more, bar instead")
00218  *  void foo(int arg);
00219  *  @endcode
00220  */
00221 #ifndef MBED_DEPRECATED
00222 #if defined(__GNUC__) || defined(__clang__)
00223 #define MBED_DEPRECATED(M) __attribute__((deprecated(M)))
00224 #elif defined(__CC_ARM)
00225 #define MBED_DEPRECATED(M) __attribute__((deprecated))
00226 #else
00227 #define MBED_DEPRECATED(M)
00228 #endif
00229 #endif
00230 
00231 /** MBED_DEPRECATED_SINCE("version", "message string")
00232  *  Mark a function declaration as deprecated, noting that the declaration was
00233  *  deprecated on the specified version. If the function is used then a warning
00234  *  will be issued by the compiler possibly including the provided message.
00235  *  Note that not all compilers are able to display this message.
00236  *
00237  *  @code
00238  *  #include "toolchain.h"
00239  *
00240  *  MBED_DEPRECATED_SINCE("mbed-os-5.1", "don't foo any more, bar instead")
00241  *  void foo(int arg);
00242  *  @endcode
00243  */
00244 #define MBED_DEPRECATED_SINCE(D, M) MBED_DEPRECATED(M " [since " D "]")
00245 
00246 /** MBED_CALLER_ADDR()
00247  * Returns the caller of the current function.
00248  *
00249  * @note
00250  * This macro is only implemented for GCC and ARMCC.
00251  *
00252  * @code
00253  * #include "toolchain.h"
00254  *
00255  * printf("This function was called from %p", MBED_CALLER_ADDR());
00256  * @endcode
00257  *
00258  * @return Address of the calling function
00259  */
00260 #ifndef MBED_CALLER_ADDR
00261 #if (defined(__GNUC__) || defined(__clang__)) && !defined(__CC_ARM)
00262 #define MBED_CALLER_ADDR() __builtin_extract_return_addr(__builtin_return_address(0))
00263 #elif defined(__CC_ARM)
00264 #define MBED_CALLER_ADDR() __builtin_return_address(0)
00265 #else
00266 #define MBED_CALLER_ADDR() (NULL)
00267 #endif
00268 #endif
00269 
00270 // FILEHANDLE declaration
00271 #if defined(TOOLCHAIN_ARM)
00272 #include <rt_sys.h>
00273 #endif
00274 
00275 #ifndef FILEHANDLE
00276 typedef int FILEHANDLE;
00277 #endif
00278 
00279 // Backwards compatibility
00280 #ifndef WEAK
00281 #define WEAK MBED_WEAK
00282 #endif
00283 
00284 #ifndef PACKED
00285 #define PACKED MBED_PACKED()
00286 #endif
00287 
00288 #ifndef EXTERN
00289 #define EXTERN extern
00290 #endif
00291 
00292 #endif
00293 
00294 /** @}*/