From 8e428dbd1a48615c36c8c086dd51079050c9fb1c Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sat, 6 Feb 2010 12:31:09 +0000 Subject: Kernel headers cleanup. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1568 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- os/kernel/include/mailboxes.h | 84 ++++++++++++++++++++++++------------------- 1 file changed, 47 insertions(+), 37 deletions(-) (limited to 'os/kernel/include/mailboxes.h') diff --git a/os/kernel/include/mailboxes.h b/os/kernel/include/mailboxes.h index 7012bf7dc..33048229f 100644 --- a/os/kernel/include/mailboxes.h +++ b/os/kernel/include/mailboxes.h @@ -18,8 +18,9 @@ */ /** - * @file mailboxes.h - * @brief Mailboxes macros and structures. + * @file mailboxes.h + * @brief Mailboxes macros and structures. + * * @addtogroup mailboxes * @{ */ @@ -37,13 +38,16 @@ #endif typedef struct { - msg_t *mb_buffer; /**< Pointer to the mailbox buffer.*/ - msg_t *mb_top; /**< Pointer to the first location - after the buffer.*/ - msg_t *mb_wrptr; /**< Write pointer.*/ - msg_t *mb_rdptr; /**< Read pointer.*/ - Semaphore mb_fullsem; /**< Full counter @p Semaphore.*/ - Semaphore mb_emptysem; /**< Empty counter @p Semaphore.*/ + msg_t *mb_buffer; /**< @brief Pointer to the mailbox + buffer. */ + msg_t *mb_top; /**< @brief Pointer to the location + after the buffer. */ + msg_t *mb_wrptr; /**< @brief Write pointer. */ + msg_t *mb_rdptr; /**< @brief Read pointer. */ + Semaphore mb_fullsem; /**< @brief Full counter + @p Semaphore. */ + Semaphore mb_emptysem; /**< @brief Empty counter + @p Semaphore. */ } Mailbox; #ifdef __cplusplus @@ -62,49 +66,54 @@ extern "C" { #endif /** - * Returns the mailbox buffer size. - * @param[in] mbp the pointer to an initialized Mailbox object + * @brief Returns the mailbox buffer size. + * + * @param[in] mbp the pointer to an initialized Mailbox object */ #define chMBSize(mbp) \ ((mbp)->mb_top - (mbp)->mb_buffer) /** - * Returns the free space into the mailbox. - * @param[in] mbp the pointer to an initialized Mailbox object - * @return The number of empty message slots. - * @note Can be invoked in any system state but if invoked out of a locked - * state then the returned value may change after reading. - * @note The returned value can be less than zero when there are waiting - * threads on the internal semaphore. + * @brief Returns the free space into the mailbox. + * @note Can be invoked in any system state but if invoked out of a locked + * state then the returned value may change after reading. + * @note The returned value can be less than zero when there are waiting + * threads on the internal semaphore. + * + * @param[in] mbp the pointer to an initialized Mailbox object + * @return The number of empty message slots. */ #define chMBGetEmpty(mbp) chSemGetCounterI(&(mbp)->mb_emptysem) /** - * Returns the number of messages into the mailbox. - * @param[in] mbp the pointer to an initialized Mailbox object - * @return The number of queued messages. - * @note Can be invoked in any system state but if invoked out of a locked - * state then the returned value may change after reading. - * @note The returned value can be less than zero when there are waiting - * threads on the internal semaphore. + * @brief Returns the number of messages into the mailbox. + * @note Can be invoked in any system state but if invoked out of a locked + * state then the returned value may change after reading. + * @note The returned value can be less than zero when there are waiting + * threads on the internal semaphore. + * + * @param[in] mbp the pointer to an initialized Mailbox object + * @return The number of queued messages. */ #define chMBGetFull(mbp) chSemGetCounterI(&(mbp)->mb_fullsem) /** - * Returns the next message in the queue without removing it. - * @note A message must be waiting in the queue for this function to work or - * it would return garbage. The correct way to use this macro is to - * use @p chMBGetFull() and then use this macro, all within a lock state. + * @brief Returns the next message in the queue without removing it. + * @note A message must be waiting in the queue for this function to work or + * it would return garbage. The correct way to use this macro is to + * use @p chMBGetFull() and then use this macro, all within a lock + * state. */ #define chMBPeek(mbp) (*(mbp)->mb_rdptr) /** - * @brief Data part of a static mailbox initializer. + * @brief Data part of a static mailbox initializer. * @details This macro should be used when statically initializing a * mailbox that is part of a bigger structure. - * @param name the name of the mailbox variable - * @param buffer pointer to the mailbox buffer area - * @param size size of the mailbox buffer area + * + * @param[in] name the name of the mailbox variable + * @param[in] buffer pointer to the mailbox buffer area + * @param[in] size size of the mailbox buffer area */ #define _MAILBOX_DATA(name, buffer, size) { \ (msg_t *)(buffer), \ @@ -116,12 +125,13 @@ extern "C" { } /** - * @brief Static mailbox initializer. + * @brief Static mailbox initializer. * @details Statically initialized mailboxes require no explicit * initialization using @p chMBInit(). - * @param name the name of the mailbox variable - * @param buffer pointer to the mailbox buffer area - * @param size size of the mailbox buffer area + * + * @param[in] name the name of the mailbox variable + * @param[in] buffer pointer to the mailbox buffer area + * @param[in] size size of the mailbox buffer area */ #define MAILBOX_DECL(name, buffer, size) \ Mailbox name = _MAILBOX_DATA(name, buffer, size) -- cgit v1.2.3