Minor documentation adjustments to the demos, projects and bootloaders to ensure...

[pub/USBasp.git] / LUFA / Common / Attributes.h

diff --git a/LUFA/Common/Attributes.h b/LUFA/Common/Attributes.h
index 62ce9f2..ee83db1 100644 (file)
--- a/LUFA/Common/Attributes.h
+++ b/LUFA/Common/Attributes.h
@@ -1,13 +1,13 @@
 /*
              LUFA Library
 /*
              LUFA Library

-     Copyright (C) Dean Camera, 2011.
+     Copyright (C) Dean Camera, 2012.

 
   dean [at] fourwalledcubicle [dot] com
            www.lufa-lib.org
 */
 
 /*
 
   dean [at] fourwalledcubicle [dot] com
            www.lufa-lib.org
 */
 
 /*

-  Copyright 2011  Dean Camera (dean [at] fourwalledcubicle [dot] com)
+  Copyright 2012  Dean Camera (dean [at] fourwalledcubicle [dot] com)

 
   Permission to use, copy, modify, distribute, and sell this
   software and its documentation for any purpose is hereby granted
 
   Permission to use, copy, modify, distribute, and sell this
   software and its documentation for any purpose is hereby granted


@@ -29,20 +29,20 @@
 */
 
 /** \file
 */
 
 /** \file

- *  \brief GCC special function/variable attribute macros.
+ *  \brief Special function/variable attribute macros.

  *
  *

- *  \copydetails Group_GCCAttributes
+ *  \copydetails Group_FuncVarAttributes

  *
  *  \note Do not include this file directly, rather include the Common.h header file instead to gain this file's
  *        functionality.
  */
 
 /** \ingroup Group_Common
  *
  *  \note Do not include this file directly, rather include the Common.h header file instead to gain this file's
  *        functionality.
  */
 
 /** \ingroup Group_Common

- *  \defgroup Group_GCCAttributes Function/Variable Attributes
- *  \brief GCC special function/variable attribute macros.
+ *  \defgroup Group_FuncVarAttributes Function/Variable Attributes
+ *  \brief Special function/variable attribute macros.

  *
  *

- *  This module contains macros for applying GCC specific attributes to functions and variables to control various
- *  optimiser and code generation features of the compiler. Attributes may be placed in the function prototype
+ *  This module contains macros for applying specific attributes to functions and variables to control various
+ *  optimizer and code generation features of the compiler. Attributes may be placed in the function prototype

  *  or variable declaration in any order, and multiple attributes can be specified for a single item via a space
  *  separated list.
  *
  *  or variable declaration in any order, and multiple attributes can be specified for a single item via a space
  *  separated list.
  *


@@ -85,13 +85,13 @@
                                 */
                                #define ATTR_NAKED                  __attribute__ ((naked))
 
                                 */
                                #define ATTR_NAKED                  __attribute__ ((naked))
 

-                               /** Prevents the compiler from considering a specified function for inlining. When applied, the given
-                                *  function will not be inlined under any circumstances.
+                               /** Prevents the compiler from considering a specified function for in-lining. When applied, the given
+                                *  function will not be in-lined under any circumstances.

                                 */
                                #define ATTR_NO_INLINE              __attribute__ ((noinline))
 
                                /** Forces the compiler to inline the specified function. When applied, the given function will be
                                 */
                                #define ATTR_NO_INLINE              __attribute__ ((noinline))
 
                                /** Forces the compiler to inline the specified function. When applied, the given function will be

-                                *  inlined under all circumstances.
+                                *  in-lined under all circumstances.

                                 */
                                #define ATTR_ALWAYS_INLINE          __attribute__ ((always_inline))
 
                                 */
                                #define ATTR_ALWAYS_INLINE          __attribute__ ((always_inline))
 


@@ -112,33 +112,35 @@
                                 *  identical name (in which case the weak reference is discarded at link time).
                                 */
                                #define ATTR_WEAK                   __attribute__ ((weak))
                                 *  identical name (in which case the weak reference is discarded at link time).
                                 */
                                #define ATTR_WEAK                   __attribute__ ((weak))

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

                        #endif
 
                        #endif
 

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

                        /** Places the function in one of the initialization sections, which execute before the main function
                         *  of the application. Refer to the avr-libc manual for more information on the initialization sections.
                         *
                         *  \param[in] SectionIndex  Initialization section number where the function should be placed.
                         */
                        /** Places the function in one of the initialization sections, which execute before the main function
                         *  of the application. Refer to the avr-libc manual for more information on the initialization sections.
                         *
                         *  \param[in] SectionIndex  Initialization section number where the function should be placed.
                         */

-                       #define ATTR_INIT_SECTION(SectionIndex) __attribute__ ((naked, section (".init" #SectionIndex )))
+                       #define ATTR_INIT_SECTION(SectionIndex) __attribute__ ((used, naked, section (".init" #SectionIndex )))

 
                        /** Marks a function as an alias for another function.
                         *
                         *  \param[in] Func  Name of the function which the given function name should alias.
                         */
                        #define ATTR_ALIAS(Func)               __attribute__ ((alias( #Func )))
 
                        /** Marks a function as an alias for another function.
                         *
                         *  \param[in] Func  Name of the function which the given function name should alias.
                         */
                        #define ATTR_ALIAS(Func)               __attribute__ ((alias( #Func )))

-                       
-                       /** Marks a variable or struct element for packing into the smallest space available. */
+
+                       /** Marks a variable or struct element for packing into the smallest space available, omitting any
+                        *  alignment bytes usually added between fields to optimize field accesses.
+                        */

                        #define ATTR_PACKED                     __attribute__ ((packed))
 
                        /** Indicates the minimum alignment in bytes for a variable or struct element.
                        #define ATTR_PACKED                     __attribute__ ((packed))
 
                        /** Indicates the minimum alignment in bytes for a variable or struct element.

-                        * 
+                        *

                         *  \param[in] Bytes  Minimum number of bytes the item should be aligned to.
                         */
                        #define ATTR_ALIGNED(Bytes)            __attribute__ ((aligned(Bytes)))
                         *  \param[in] Bytes  Minimum number of bytes the item should be aligned to.
                         */
                        #define ATTR_ALIGNED(Bytes)            __attribute__ ((aligned(Bytes)))