X-Git-Url: http://git.linex4red.de/pub/USBasp.git/blobdiff_plain/4a09da20989dfe0c41dc1272fa6dce1e11539c15..fa8beef82d1340a69390d4b11ca785ee016789c5:/LUFA/Common/Common.h diff --git a/LUFA/Common/Common.h b/LUFA/Common/Common.h index ed2d1bc90..92f4f22fa 100644 --- a/LUFA/Common/Common.h +++ b/LUFA/Common/Common.h @@ -31,7 +31,25 @@ /** \file * * This file contains macros which are common to all library elements, and which may be useful in user code. It - * also includes other common headees, such as Atomic.h, FunctionAttributes.h and BoardTypes.h. + * also includes other common headers, such as Atomic.h, FunctionAttributes.h and BoardTypes.h. + */ + +/** @defgroup Group_Common Common Utility Headers - LUFA/Drivers/Common/Common.h + * + * Common utility headers containing macros, functions, enums and types which are common to all + * aspects of the library. + * + * @{ + */ + +/** @defgroup Group_Debugging Debugging Macros + * + * Macros for debugging use. + */ + +/** @defgroup Group_BitManip Endian and Bit Macros + * + * Functions for swapping endianness and reversing bit orders. */ #ifndef __COMMON_H__ @@ -49,38 +67,48 @@ /* Public Interface - May be used in end-application: */ /* Macros: */ - /** Macro for encasing other multi-statment macros. This should be used along with an opening brace + /** Macro for encasing other multi-statement macros. This should be used along with an opening brace * before the start of any multi-statement macro, so that the macros contents as a whole are treated - * as a discreete block and not as a list of seperate statements which may cause problems when used as - * a block (such as inline IF statments). + * as a discrete block and not as a list of separate statements which may cause problems when used as + * a block (such as inline IF statements). */ #define MACROS do - /** Macro for encasing other multi-statment macros. This should be used along with a preceeding closing + /** Macro for encasing other multi-statement macros. This should be used along with a preceding closing * brace at the end of any multi-statement macro, so that the macros contents as a whole are treated - * as a discreete block and not as a list of seperate statements which may cause problems when used as - * a block (such as inline IF statments). + * as a discrete block and not as a list of separate statements which may cause problems when used as + * a block (such as inline IF statements). */ #define MACROE while (0) - /** Defines a volatile NOP statment which cannot be optimized out by the compiler, and thus can always + /** Defines a volatile NOP statement which cannot be optimized out by the compiler, and thus can always * be set as a breakpoint in the resulting code. Useful for debugging purposes, where the optimizer * removes/reorders code to the point where break points cannot reliably be set. + * + * \ingroup Group_Debugging */ #define JTAG_DEBUG_POINT() asm volatile ("NOP" ::) - /** Defines an explicit JTAG break point in the resulting binary via the ASM BREAK statment. When - * a JTAG is used, this causes the program execution to halt when reached until manually resumed. */ + /** Defines an explicit JTAG break point in the resulting binary via the ASM BREAK statement. When + * a JTAG is used, this causes the program execution to halt when reached until manually resumed. + * + * \ingroup Group_Debugging + */ #define JTAG_DEBUG_BREAK() asm volatile ("BREAK" ::) - /** Macro for testing condition "x" and breaking via JTAG_DEBUG_BREAK() if the condition is false. */ + /** Macro for testing condition "x" and breaking via JTAG_DEBUG_BREAK() if the condition is false. + * + * \ingroup Group_Debugging + */ #define JTAG_DEBUG_ASSERT(x) MACROS{ if (!(x)) { JTAG_DEBUG_BREAK(); } }MACROE /** Macro for testing condition "x" and writing debug data to the serial stream if false. As a - * prerequisite for this macro, the serial stream should be configured via the Serial_Stream driver. + * prerequisite for this macro, the serial stream should be configured via the Peripheral/SerialStream driver. * * The serial output takes the form "{FILENAME}: Function {FUNCTION NAME}, Line {LINE NUMBER}: Assertion * {x} failed." + * + * \ingroup Group_Debugging */ #define SERIAL_STREAM_ASSERT(x) MACROS{ if (!(x)) { printf_P(PSTR("%s: Function \"%s\", Line %d: " \ "Assertion \"%s\" failed.\r\n"), \ @@ -91,7 +119,9 @@ /** Function to reverse the individual bits in a byte - i.e. bit 7 is moved to bit 0, bit 6 to bit 1, * etc. * - * \param Byte Byte of data whose bits are to be reversed + * \ingroup Group_BitManip + * + * \param[in] Byte Byte of data whose bits are to be reversed */ static inline uint8_t BitReverse(uint8_t Byte) ATTR_WARN_UNUSED_RESULT ATTR_CONST; static inline uint8_t BitReverse(uint8_t Byte) @@ -105,7 +135,9 @@ /** Function to reverse the byte ordering of the individual bytes in a 16 bit number. * - * \param Word Word of data whose bytes are to be swapped + * \ingroup Group_BitManip + * + * \param[in] Word Word of data whose bytes are to be swapped */ static inline uint16_t SwapEndian_16(uint16_t Word) ATTR_WARN_UNUSED_RESULT ATTR_CONST; static inline uint16_t SwapEndian_16(uint16_t Word) @@ -115,7 +147,9 @@ /** Function to reverse the byte ordering of the individual bytes in a 32 bit number. * - * \param DWord Double word of data whose bytes are to be swapped + * \ingroup Group_BitManip + * + * \param[in] DWord Double word of data whose bytes are to be swapped */ static inline uint32_t SwapEndian_32(uint32_t DWord) ATTR_WARN_UNUSED_RESULT ATTR_CONST; static inline uint32_t SwapEndian_32(uint32_t DWord) @@ -128,8 +162,10 @@ /** Function to reverse the byte ordering of the individual bytes in a n byte number. * - * \param Data Pointer to a number containing an even number of bytes to be reversed - * \param Bytes Length of the data in bytes + * \ingroup Group_BitManip + * + * \param[in,out] Data Pointer to a number containing an even number of bytes to be reversed + * \param[in] Bytes Length of the data in bytes */ static inline void SwapEndian_n(uint8_t* Data, uint8_t Bytes); static inline void SwapEndian_n(uint8_t* Data, uint8_t Bytes) @@ -148,3 +184,5 @@ } #endif + +/** @} */