LUFA/Common/FunctionAttributes.h

   1 /*
   2              LUFA Library
   3      Copyright (C) Dean Camera, 2009.
   4
   5   dean [at] fourwalledcubicle [dot] com
   6       www.fourwalledcubicle.com
   7 */
   8
   9 /*
  10   Copyright 2009  Dean Camera (dean [at] fourwalledcubicle [dot] com)
  11
  12   Permission to use, copy, modify, and distribute this software
  13   and its documentation for any purpose and without fee is hereby
  14   granted, provided that the above copyright notice appear in all
  15   copies and that both that the copyright notice and this
  16   permission notice and warranty disclaimer appear in supporting
  17   documentation, and that the name of the author not be used in
  18   advertising or publicity pertaining to distribution of the
  19   software without specific, written prior permission.
  20
  21   The author disclaim all warranties with regard to this
  22   software, including all implied warranties of merchantability
  23   and fitness.  In no event shall the author be liable for any
  24   special, indirect or consequential damages or any damages
  25   whatsoever resulting from loss of use, data or profits, whether
  26   in an action of contract, negligence or other tortious action,
  27   arising out of or in connection with the use or performance of
  28   this software.
  29 */
  30
  31 /** \file
  32  *
  33  *  This file contains macros for applying GCC specific attributes to functions to control various optimizer
  34  *  and code generation features of the compiler. Attributes may be placed in the function prototype in any
  35  *  order, and multiple attributes can be specified for a single function via a space seperated list.
  36  *
  37  *  \note Do not include this file directly, rather include the Common.h header file instead to gain this file's
  38  *        functionality.
  39  */
  40
  41 #ifndef __FUNCATTR_H__
  42 #define __FUNCATTR_H__
  43
  44         /* Preprocessor Checks: */
  45                 #if !defined(__COMMON_H__)
  46                         #error Do not include this file directly. Include LUFA/Common/Common.h instead to gain this functionality.
  47                 #endif
  48
  49         /* Public Interface - May be used in end-application: */
  50                 /* Macros: */
  51                         /** Indicates to the compiler that the function can not ever return, so that any stack restoring or
  52                          *  return code may be ommited by the compiler in the resulting binary.
  53                          */
  54                         #define ATTR_NO_RETURN              __attribute__ ((noreturn))
  55
  56                         /** Places the function in one of the initilization sections, which execute before the main function
  57                          *  of the application. The init function number can be specified as "x", as an integer. Refer to the
  58                          *  avr-libc manual for more information on the initialization sections.
  59                          */
  60                         #define ATTR_INIT_SECTION(x)        __attribute__ ((naked, section (".init" #x )))
  61
  62                         /** Indicates that the function returns a value which should not be ignored by the user code. When
  63                          *  applied, any ignored return value from calling the function will produce a compiler warning.
  64                          */
  65                         #define ATTR_WARN_UNUSED_RESULT     __attribute__ ((warn_unused_result))
  66
  67                         /** Indicates that the specified parameters of the function are pointers which should never be NULL.
  68                          *  When applied as a 1-based comma seperated list the compiler will emmit a warning if the specified
  69                          *  parameters are known at compiler time to be NULL at the point of calling the function.
  70                          */
  71                         #define ATTR_NON_NULL_PTR_ARG(...)  __attribute__ ((nonnull (__VA_ARGS__)))
  72
  73                         /** Removes any preample or postample from the function. When used, the function will not have any
  74                          *  register or stack saving code. This should be used with caution, and when used the programmer
  75                          *  is responsible for maintaining stack and register integrity.
  76                          */
  77                         #define ATTR_NAKED                  __attribute__ ((naked))
  78
  79                         /** Prevents the compiler from considering a specified function for inlining. When applied, the given
  80                          *  function will not be inlined under any circumstances.
  81                          */
  82                         #define ATTR_NOINLINE               __attribute__ ((noinline))
  83
  84                         /** Forces the compiler to inline the specified function. When applied, the given function will be
  85                          *  inlined under all circumstances.
  86                          */
  87                         #define ATTR_ALWAYS_INLINE          __attribute__ ((always_inline))
  88
  89                         /** Indicates that the specified function is pure, in that it has no side-effects other than global
  90                          *  or parameter variable access.
  91                          */
  92                         #define ATTR_PURE                   __attribute__ ((pure))
  93
  94                         /** Indicates that the specified function is constant, in that it has no side effects other than
  95                          *  parameter access.
  96                          */
  97                         #define ATTR_CONST                  __attribute__ ((const))
  98
  99                         /** Marks a given function as deprecated, which produces a warning if the function is called. */
 100                         #define ATTR_DEPRECATED             __attribute__ ((deprecated))
 101
 102                         /** Marks a function as a weak reference, which can be overridden by other functions with an
 103                          *  identical name (in which case the weak reference is discarded at link time).
 104                          */
 105                         #define ATTR_WEAK                   __attribute__ ((weak))
 106
 107                         /** Marks a function as an alias for another function of name "x". */
 108                         #define ATTR_ALIAS(x)               __attribute__ ((alias( #x )))
 109
 110 #endif