Statistics
| Branch: | Tag: | Revision:

root / LUFA / Common / Attributes.h @ 978b99e5

History | View | Annotate | Download (6.79 KB)

1
/*
2
             LUFA Library
3
     Copyright (C) Dean Camera, 2011.
4

5
  dean [at] fourwalledcubicle [dot] com
6
           www.lufa-lib.org
7
*/
8

    
9
/*
10
  Copyright 2011  Dean Camera (dean [at] fourwalledcubicle [dot] com)
11

12
  Permission to use, copy, modify, distribute, and sell this
13
  software and its documentation for any purpose is hereby granted
14
  without fee, provided that the above copyright notice appear in
15
  all 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
 *  \brief Special function/variable attribute macros.
33
 *
34
 *  \copydetails Group_FuncVarAttributes
35
 *
36
 *  \note Do not include this file directly, rather include the Common.h header file instead to gain this file's
37
 *        functionality.
38
 */
39

    
40
/** \ingroup Group_Common
41
 *  \defgroup Group_FuncVarAttributes Function/Variable Attributes
42
 *  \brief Special function/variable attribute macros.
43
 *
44
 *  This module contains macros for applying specific attributes to functions and variables to control various
45
 *  optimizer and code generation features of the compiler. Attributes may be placed in the function prototype
46
 *  or variable declaration in any order, and multiple attributes can be specified for a single item via a space
47
 *  separated list.
48
 *
49
 *  On incompatible versions of GCC or on other compilers, these macros evaluate to nothing unless they are
50
 *  critical to the code's function and thus must throw a compile error when used.
51
 *
52
 *  @{
53
 */
54

    
55
#ifndef __LUFA_FUNCATTR_H__
56
#define __LUFA_FUNCATTR_H__
57

    
58
        /* Preprocessor Checks: */
59
                #if !defined(__INCLUDE_FROM_COMMON_H)
60
                        #error Do not include this file directly. Include LUFA/Common/Common.h instead to gain this functionality.
61
                #endif
62

    
63
        /* Public Interface - May be used in end-application: */
64
                /* Macros: */
65
                        #if (__GNUC__ >= 3) || defined(__DOXYGEN__)
66
                                /** Indicates to the compiler that the function can not ever return, so that any stack restoring or
67
                                 *  return code may be omitted by the compiler in the resulting binary.
68
                                 */
69
                                #define ATTR_NO_RETURN              __attribute__ ((noreturn))
70

    
71
                                /** Indicates that the function returns a value which should not be ignored by the user code. When
72
                                 *  applied, any ignored return value from calling the function will produce a compiler warning.
73
                                 */
74
                                #define ATTR_WARN_UNUSED_RESULT     __attribute__ ((warn_unused_result))
75

    
76
                                /** Indicates that the specified parameters of the function are pointers which should never be \c NULL.
77
                                 *  When applied as a 1-based comma separated list the compiler will emit a warning if the specified
78
                                 *  parameters are known at compiler time to be \c NULL at the point of calling the function.
79
                                 */
80
                                #define ATTR_NON_NULL_PTR_ARG(...)  __attribute__ ((nonnull (__VA_ARGS__)))
81

    
82
                                /** Removes any preamble or postamble from the function. When used, the function will not have any
83
                                 *  register or stack saving code. This should be used with caution, and when used the programmer
84
                                 *  is responsible for maintaining stack and register integrity.
85
                                 */
86
                                #define ATTR_NAKED                  __attribute__ ((naked))
87

    
88
                                /** Prevents the compiler from considering a specified function for in-lining. When applied, the given
89
                                 *  function will not be in-lined under any circumstances.
90
                                 */
91
                                #define ATTR_NO_INLINE              __attribute__ ((noinline))
92

    
93
                                /** Forces the compiler to inline the specified function. When applied, the given function will be
94
                                 *  in-lined under all circumstances.
95
                                 */
96
                                #define ATTR_ALWAYS_INLINE          __attribute__ ((always_inline))
97

    
98
                                /** Indicates that the specified function is pure, in that it has no side-effects other than global
99
                                 *  or parameter variable access.
100
                                 */
101
                                #define ATTR_PURE                   __attribute__ ((pure))
102

    
103
                                /** Indicates that the specified function is constant, in that it has no side effects other than
104
                                 *  parameter access.
105
                                 */
106
                                #define ATTR_CONST                  __attribute__ ((const))
107

    
108
                                /** Marks a given function as deprecated, which produces a warning if the function is called. */
109
                                #define ATTR_DEPRECATED             __attribute__ ((deprecated))
110

    
111
                                /** Marks a function as a weak reference, which can be overridden by other functions with an
112
                                 *  identical name (in which case the weak reference is discarded at link time).
113
                                 */
114
                                #define ATTR_WEAK                   __attribute__ ((weak))
115

    
116
                                /** Forces the compiler to not automatically zero the given global variable on startup, so that the
117
                                 *  current RAM contents is retained. Under most conditions this value will be random due to the
118
                                 *  behaviour of volatile memory once power is removed, but may be used in some specific circumstances,
119
                                 *  like the passing of values back after a system watchdog reset.
120
                                 */
121
                                #define ATTR_NO_INIT                __attribute__ ((section (".noinit")))
122
                        #endif
123

    
124
                        /** Places the function in one of the initialization sections, which execute before the main function
125
                         *  of the application. Refer to the avr-libc manual for more information on the initialization sections.
126
                         *
127
                         *  \param[in] SectionIndex  Initialization section number where the function should be placed.
128
                         */
129
                        #define ATTR_INIT_SECTION(SectionIndex) __attribute__ ((used, naked, section (".init" #SectionIndex )))
130

    
131
                        /** Marks a function as an alias for another function.
132
                         *
133
                         *  \param[in] Func  Name of the function which the given function name should alias.
134
                         */
135
                        #define ATTR_ALIAS(Func)               __attribute__ ((alias( #Func )))
136
                        
137
                        /** Marks a variable or struct element for packing into the smallest space available, omitting any
138
                         *  alignment bytes usually added between fields to optimize field accesses.
139
                         */
140
                        #define ATTR_PACKED                     __attribute__ ((packed))
141

    
142
                        /** Indicates the minimum alignment in bytes for a variable or struct element.
143
                         * 
144
                         *  \param[in] Bytes  Minimum number of bytes the item should be aligned to.
145
                         */
146
                        #define ATTR_ALIGNED(Bytes)            __attribute__ ((aligned(Bytes)))
147
#endif
148

    
149
/** @} */
150