X-Git-Url: http://git.linex4red.de/pub/USBasp.git/blobdiff_plain/6a10d6b465be27db090d760dc0fbe722c94e4344..fa8beef82d1340a69390d4b11ca785ee016789c5:/LUFA/Common/Common.h diff --git a/LUFA/Common/Common.h b/LUFA/Common/Common.h index 97e9ce931..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"), \ @@ -88,31 +116,12 @@ } }MACROE /* Inline Functions: */ - /** Function for reliably setting the AVR's system clock prescaler, using inline assembly. This function - * is guaranteed to operate reliably regardless of optimization setting or other compile time options. - * - * \param PrescalerMask The mask of the new prescaler setting for CLKPR - */ - static inline void SetSystemClockPrescaler(uint8_t PrescalerMask) - { - uint8_t tmp = (1 << CLKPCE); - __asm__ __volatile__ ( - "in __tmp_reg__,__SREG__" "\n\t" - "cli" "\n\t" - "sts %1, %0" "\n\t" - "sts %1, %2" "\n\t" - "out __SREG__, __tmp_reg__" - : /* no outputs */ - : "d" (tmp), - "M" (_SFR_MEM_ADDR(CLKPR)), - "d" (PrescalerMask) - : "r0"); - } - /** 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) @@ -126,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) @@ -136,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) @@ -149,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) @@ -169,3 +184,5 @@ } #endif + +/** @} */