ChibiOS/RT Architecture - Reference Manual - Guides |
00001 /* 00002 ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. 00003 00004 This file is part of ChibiOS/RT. 00005 00006 ChibiOS/RT is free software; you can redistribute it and/or modify 00007 it under the terms of the GNU General Public License as published by 00008 the Free Software Foundation; either version 3 of the License, or 00009 (at your option) any later version. 00010 00011 ChibiOS/RT is distributed in the hope that it will be useful, 00012 but WITHOUT ANY WARRANTY; without even the implied warranty of 00013 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 00014 GNU General Public License for more details. 00015 00016 You should have received a copy of the GNU General Public License 00017 along with this program. If not, see <http://www.gnu.org/licenses/>. 00018 00019 --- 00020 00021 A special exception to the GPL can be applied should you wish to distribute 00022 a combined work that includes ChibiOS/RT, without being obliged to provide 00023 the source code for any proprietary components. See the file exception.txt 00024 for full details of how and when the exception can be applied. 00025 */ 00026 00027 /** 00028 * @file chmboxes.h 00029 * @brief Mailboxes macros and structures. 00030 * 00031 * @addtogroup mailboxes 00032 * @{ 00033 */ 00034 00035 #ifndef _CHMBOXES_H_ 00036 #define _CHMBOXES_H_ 00037 00038 #if CH_USE_MAILBOXES 00039 00040 /* 00041 * Module dependencies check. 00042 */ 00043 #if !CH_USE_SEMAPHORES 00044 #error "CH_USE_MAILBOXES requires CH_USE_SEMAPHORES" 00045 #endif 00046 00047 typedef struct { 00048 msg_t *mb_buffer; /**< @brief Pointer to the mailbox 00049 buffer. */ 00050 msg_t *mb_top; /**< @brief Pointer to the location 00051 after the buffer. */ 00052 msg_t *mb_wrptr; /**< @brief Write pointer. */ 00053 msg_t *mb_rdptr; /**< @brief Read pointer. */ 00054 Semaphore mb_fullsem; /**< @brief Full counter 00055 @p Semaphore. */ 00056 Semaphore mb_emptysem; /**< @brief Empty counter 00057 @p Semaphore. */ 00058 } Mailbox; 00059 00060 #ifdef __cplusplus 00061 extern "C" { 00062 #endif 00063 void chMBInit(Mailbox *mbp, msg_t *buf, cnt_t n); 00064 void chMBReset(Mailbox *mbp); 00065 msg_t chMBPost(Mailbox *mbp, msg_t msg, systime_t timeout); 00066 msg_t chMBPostS(Mailbox *mbp, msg_t msg, systime_t timeout); 00067 msg_t chMBPostAhead(Mailbox *mbp, msg_t msg, systime_t timeout); 00068 msg_t chMBPostAheadS(Mailbox *mbp, msg_t msg, systime_t timeout); 00069 msg_t chMBFetch(Mailbox *mbp, msg_t *msgp, systime_t timeout); 00070 msg_t chMBFetchS(Mailbox *mbp, msg_t *msgp, systime_t timeout); 00071 #ifdef __cplusplus 00072 } 00073 #endif 00074 00075 /** 00076 * @brief Returns the mailbox buffer size. 00077 * 00078 * @param[in] mbp the pointer to an initialized Mailbox object 00079 */ 00080 #define chMBSize(mbp) \ 00081 ((mbp)->mb_top - (mbp)->mb_buffer) 00082 00083 /** 00084 * @brief Returns the free space into the mailbox. 00085 * @note Can be invoked in any system state but if invoked out of a locked 00086 * state then the returned value may change after reading. 00087 * @note The returned value can be less than zero when there are waiting 00088 * threads on the internal semaphore. 00089 * 00090 * @param[in] mbp the pointer to an initialized Mailbox object 00091 * @return The number of empty message slots. 00092 */ 00093 #define chMBGetEmpty(mbp) chSemGetCounterI(&(mbp)->mb_emptysem) 00094 00095 /** 00096 * @brief Returns the number of messages into the mailbox. 00097 * @note Can be invoked in any system state but if invoked out of a locked 00098 * state then the returned value may change after reading. 00099 * @note The returned value can be less than zero when there are waiting 00100 * threads on the internal semaphore. 00101 * 00102 * @param[in] mbp the pointer to an initialized Mailbox object 00103 * @return The number of queued messages. 00104 */ 00105 #define chMBGetFull(mbp) chSemGetCounterI(&(mbp)->mb_fullsem) 00106 00107 /** 00108 * @brief Returns the next message in the queue without removing it. 00109 * @note A message must be waiting in the queue for this function to work or 00110 * it would return garbage. The correct way to use this macro is to 00111 * use @p chMBGetFull() and then use this macro, all within a lock 00112 * state. 00113 */ 00114 #define chMBPeek(mbp) (*(mbp)->mb_rdptr) 00115 00116 /** 00117 * @brief Data part of a static mailbox initializer. 00118 * @details This macro should be used when statically initializing a 00119 * mailbox that is part of a bigger structure. 00120 * 00121 * @param[in] name the name of the mailbox variable 00122 * @param[in] buffer pointer to the mailbox buffer area 00123 * @param[in] size size of the mailbox buffer area 00124 */ 00125 #define _MAILBOX_DATA(name, buffer, size) { \ 00126 (msg_t *)(buffer), \ 00127 (msg_t *)(buffer) + size, \ 00128 (msg_t *)(buffer), \ 00129 (msg_t *)(buffer), \ 00130 _SEMAPHORE_DATA(name.mb_fullsem, 0), \ 00131 _SEMAPHORE_DATA(name.mb_emptysem, size), \ 00132 } 00133 00134 /** 00135 * @brief Static mailbox initializer. 00136 * @details Statically initialized mailboxes require no explicit 00137 * initialization using @p chMBInit(). 00138 * 00139 * @param[in] name the name of the mailbox variable 00140 * @param[in] buffer pointer to the mailbox buffer area 00141 * @param[in] size size of the mailbox buffer area 00142 */ 00143 #define MAILBOX_DECL(name, buffer, size) \ 00144 Mailbox name = _MAILBOX_DATA(name, buffer, size) 00145 00146 #endif /* CH_USE_MAILBOXES */ 00147 00148 #endif /* _CHMBOXES_H_ */ 00149 00150 /** @} */