Daniel Vilela / Mbed 2 deprecated I2C

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Dependencies:   mbed_rtos_types Mutex mbed_rtos_storage mbed Semaphore

rtos/Mail.h@0:85df64b421a8, 2019-11-27 (annotated)

Committer:
daniwestside
Date:
Wed Nov 27 11:12:33 2019 +0000
Branch:
Sinthreads
Revision:
0:85df64b421a8
OK

Who changed what in which revision?

UserRevisionLine numberNew contents of line
daniwestside 0:85df64b421a8 1 /* mbed Microcontroller Library
daniwestside 0:85df64b421a8 2 * Copyright (c) 2006-2017 ARM Limited
daniwestside 0:85df64b421a8 3 *
daniwestside 0:85df64b421a8 4 * Permission is hereby granted, free of charge, to any person obtaining a copy
daniwestside 0:85df64b421a8 5 * of this software and associated documentation files (the "Software"), to deal
daniwestside 0:85df64b421a8 6 * in the Software without restriction, including without limitation the rights
daniwestside 0:85df64b421a8 7 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
daniwestside 0:85df64b421a8 8 * copies of the Software, and to permit persons to whom the Software is
daniwestside 0:85df64b421a8 9 * furnished to do so, subject to the following conditions:
daniwestside 0:85df64b421a8 10 *
daniwestside 0:85df64b421a8 11 * The above copyright notice and this permission notice shall be included in
daniwestside 0:85df64b421a8 12 * all copies or substantial portions of the Software.
daniwestside 0:85df64b421a8 13 *
daniwestside 0:85df64b421a8 14 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
daniwestside 0:85df64b421a8 15 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
daniwestside 0:85df64b421a8 16 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
daniwestside 0:85df64b421a8 17 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
daniwestside 0:85df64b421a8 18 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
daniwestside 0:85df64b421a8 19 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
daniwestside 0:85df64b421a8 20 * SOFTWARE.
daniwestside 0:85df64b421a8 21 */
daniwestside 0:85df64b421a8 22 #ifndef MAIL_H
daniwestside 0:85df64b421a8 23 #define MAIL_H
daniwestside 0:85df64b421a8 24
daniwestside 0:85df64b421a8 25 #include <stdint.h>
daniwestside 0:85df64b421a8 26 #include <string.h>
daniwestside 0:85df64b421a8 27
daniwestside 0:85df64b421a8 28 #include "rtos/Queue.h"
daniwestside 0:85df64b421a8 29 #include "rtos/MemoryPool.h"
daniwestside 0:85df64b421a8 30 #include "rtos/mbed_rtos_types.h"
daniwestside 0:85df64b421a8 31 #include "rtos/mbed_rtos_storage.h"
daniwestside 0:85df64b421a8 32 #include "rtos/mbed_rtos1_types.h"
daniwestside 0:85df64b421a8 33
daniwestside 0:85df64b421a8 34 #include "platform/mbed_toolchain.h"
daniwestside 0:85df64b421a8 35 #include "platform/NonCopyable.h"
daniwestside 0:85df64b421a8 36
daniwestside 0:85df64b421a8 37 #ifndef MBED_NO_GLOBAL_USING_DIRECTIVE
daniwestside 0:85df64b421a8 38 using namespace rtos;
daniwestside 0:85df64b421a8 39 #endif
daniwestside 0:85df64b421a8 40
daniwestside 0:85df64b421a8 41 #if MBED_CONF_RTOS_PRESENT || defined(DOXYGEN_ONLY)
daniwestside 0:85df64b421a8 42
daniwestside 0:85df64b421a8 43 namespace rtos {
daniwestside 0:85df64b421a8 44 /** \addtogroup rtos */
daniwestside 0:85df64b421a8 45 /** @{*/
daniwestside 0:85df64b421a8 46 /**
daniwestside 0:85df64b421a8 47 * \defgroup rtos_Mail Mail class
daniwestside 0:85df64b421a8 48 * @{
daniwestside 0:85df64b421a8 49 */
daniwestside 0:85df64b421a8 50
daniwestside 0:85df64b421a8 51 /** The Mail class allows you to control, send, receive or wait for mail.
daniwestside 0:85df64b421a8 52 * A mail is a memory block that is sent to a thread or interrupt service routine (ISR).
daniwestside 0:85df64b421a8 53 * @tparam T Data type of a single mail message element.
daniwestside 0:85df64b421a8 54 * @tparam queue_sz Maximum number of mail messages in queue.
daniwestside 0:85df64b421a8 55 *
daniwestside 0:85df64b421a8 56 * @note
daniwestside 0:85df64b421a8 57 * Memory considerations: The mail data store and control structures are part of this class - they do not (themselves)
daniwestside 0:85df64b421a8 58 * allocate memory on the heap, both for the Mbed OS and underlying RTOS objects (static or dynamic RTOS memory
daniwestside 0:85df64b421a8 59 * pools are not being used).
daniwestside 0:85df64b421a8 60 */
daniwestside 0:85df64b421a8 61 template<typename T, uint32_t queue_sz>
daniwestside 0:85df64b421a8 62 class Mail : private mbed::NonCopyable<Mail<T, queue_sz> > {
daniwestside 0:85df64b421a8 63 public:
daniwestside 0:85df64b421a8 64 /** Create and initialize Mail queue.
daniwestside 0:85df64b421a8 65 *
daniwestside 0:85df64b421a8 66 * @note You cannot call this function from ISR context.
daniwestside 0:85df64b421a8 67 */
daniwestside 0:85df64b421a8 68 Mail() { };
daniwestside 0:85df64b421a8 69
daniwestside 0:85df64b421a8 70 /** Check if the mail queue is empty.
daniwestside 0:85df64b421a8 71 *
daniwestside 0:85df64b421a8 72 * @return State of queue.
daniwestside 0:85df64b421a8 73 * @retval true Mail queue is empty.
daniwestside 0:85df64b421a8 74 * @retval false Mail queue contains mail.
daniwestside 0:85df64b421a8 75 *
daniwestside 0:85df64b421a8 76 * @note You may call this function from ISR context.
daniwestside 0:85df64b421a8 77 */
daniwestside 0:85df64b421a8 78 bool empty() const
daniwestside 0:85df64b421a8 79 {
daniwestside 0:85df64b421a8 80 return _queue.empty();
daniwestside 0:85df64b421a8 81 }
daniwestside 0:85df64b421a8 82
daniwestside 0:85df64b421a8 83 /** Check if the mail queue is full.
daniwestside 0:85df64b421a8 84 *
daniwestside 0:85df64b421a8 85 * @return State of queue.
daniwestside 0:85df64b421a8 86 * @retval true Mail queue is full.
daniwestside 0:85df64b421a8 87 * @retval false Mail queue is not full.
daniwestside 0:85df64b421a8 88 *
daniwestside 0:85df64b421a8 89 * @note You may call this function from ISR context.
daniwestside 0:85df64b421a8 90 */
daniwestside 0:85df64b421a8 91 bool full() const
daniwestside 0:85df64b421a8 92 {
daniwestside 0:85df64b421a8 93 return _queue.full();
daniwestside 0:85df64b421a8 94 }
daniwestside 0:85df64b421a8 95
daniwestside 0:85df64b421a8 96 /** Allocate a memory block of type T, without blocking.
daniwestside 0:85df64b421a8 97 *
daniwestside 0:85df64b421a8 98 * @param millisec Not used (see note).
daniwestside 0:85df64b421a8 99 *
daniwestside 0:85df64b421a8 100 * @return Pointer to memory block that you can fill with mail or nullptr in case error.
daniwestside 0:85df64b421a8 101 *
daniwestside 0:85df64b421a8 102 * @note You may call this function from ISR context.
daniwestside 0:85df64b421a8 103 * @note If blocking is required, use Mail::alloc_for or Mail::alloc_until
daniwestside 0:85df64b421a8 104 */
daniwestside 0:85df64b421a8 105 T *alloc(MBED_UNUSED uint32_t millisec = 0)
daniwestside 0:85df64b421a8 106 {
daniwestside 0:85df64b421a8 107 return _pool.alloc();
daniwestside 0:85df64b421a8 108 }
daniwestside 0:85df64b421a8 109
daniwestside 0:85df64b421a8 110 /** Allocate a memory block of type T, optionally blocking.
daniwestside 0:85df64b421a8 111 *
daniwestside 0:85df64b421a8 112 * @param millisec Timeout value, or osWaitForever.
daniwestside 0:85df64b421a8 113 *
daniwestside 0:85df64b421a8 114 * @return Pointer to memory block that you can fill with mail or nullptr in case error.
daniwestside 0:85df64b421a8 115 *
daniwestside 0:85df64b421a8 116 * @note You may call this function from ISR context if the millisec parameter is set to 0.
daniwestside 0:85df64b421a8 117 */
daniwestside 0:85df64b421a8 118 T *alloc_for(uint32_t millisec)
daniwestside 0:85df64b421a8 119 {
daniwestside 0:85df64b421a8 120 return _pool.alloc_for(millisec);
daniwestside 0:85df64b421a8 121 }
daniwestside 0:85df64b421a8 122
daniwestside 0:85df64b421a8 123 /** Allocate a memory block of type T, blocking.
daniwestside 0:85df64b421a8 124 *
daniwestside 0:85df64b421a8 125 * @param millisec Absolute timeout time, referenced to Kernel::get_ms_count().
daniwestside 0:85df64b421a8 126 *
daniwestside 0:85df64b421a8 127 * @return Pointer to memory block that you can fill with mail or nullptr in case error.
daniwestside 0:85df64b421a8 128 *
daniwestside 0:85df64b421a8 129 * @note You cannot call this function from ISR context.
daniwestside 0:85df64b421a8 130 * @note the underlying RTOS may have a limit to the maximum wait time
daniwestside 0:85df64b421a8 131 * due to internal 32-bit computations, but this is guaranteed to work if the
daniwestside 0:85df64b421a8 132 * wait is <= 0x7fffffff milliseconds (~24 days). If the limit is exceeded,
daniwestside 0:85df64b421a8 133 * the wait will time out earlier than specified.
daniwestside 0:85df64b421a8 134 */
daniwestside 0:85df64b421a8 135 T *alloc_until(uint64_t millisec)
daniwestside 0:85df64b421a8 136 {
daniwestside 0:85df64b421a8 137 return _pool.alloc_until(millisec);
daniwestside 0:85df64b421a8 138 }
daniwestside 0:85df64b421a8 139
daniwestside 0:85df64b421a8 140 /** Allocate a memory block of type T, and set memory block to zero.
daniwestside 0:85df64b421a8 141 *
daniwestside 0:85df64b421a8 142 * @param millisec Not used (see note).
daniwestside 0:85df64b421a8 143 *
daniwestside 0:85df64b421a8 144 * @return Pointer to memory block that you can fill with mail or nullptr in case error.
daniwestside 0:85df64b421a8 145 *
daniwestside 0:85df64b421a8 146 * @note You may call this function from ISR context if the millisec parameter is set to 0.
daniwestside 0:85df64b421a8 147 * @note If blocking is required, use Mail::calloc_for or Mail::calloc_until
daniwestside 0:85df64b421a8 148 */
daniwestside 0:85df64b421a8 149 T *calloc(MBED_UNUSED uint32_t millisec = 0)
daniwestside 0:85df64b421a8 150 {
daniwestside 0:85df64b421a8 151 return _pool.calloc();
daniwestside 0:85df64b421a8 152 }
daniwestside 0:85df64b421a8 153
daniwestside 0:85df64b421a8 154 /** Allocate a memory block of type T, optionally blocking, and set memory block to zero.
daniwestside 0:85df64b421a8 155 *
daniwestside 0:85df64b421a8 156 * @param millisec Timeout value, or osWaitForever.
daniwestside 0:85df64b421a8 157 *
daniwestside 0:85df64b421a8 158 * @return Pointer to memory block that you can fill with mail or nullptr in case error.
daniwestside 0:85df64b421a8 159 *
daniwestside 0:85df64b421a8 160 * @note You may call this function from ISR context if the millisec parameter is set to 0.
daniwestside 0:85df64b421a8 161 */
daniwestside 0:85df64b421a8 162 T *calloc_for(uint32_t millisec)
daniwestside 0:85df64b421a8 163 {
daniwestside 0:85df64b421a8 164 return _pool.calloc_for(millisec);
daniwestside 0:85df64b421a8 165 }
daniwestside 0:85df64b421a8 166
daniwestside 0:85df64b421a8 167 /** Allocate a memory block of type T, blocking, and set memory block to zero.
daniwestside 0:85df64b421a8 168 *
daniwestside 0:85df64b421a8 169 * @param millisec Absolute timeout time, referenced to Kernel::get_ms_count().
daniwestside 0:85df64b421a8 170 *
daniwestside 0:85df64b421a8 171 * @return Pointer to memory block that you can fill with mail or nullptr in case error.
daniwestside 0:85df64b421a8 172 *
daniwestside 0:85df64b421a8 173 * @note You cannot call this function from ISR context.
daniwestside 0:85df64b421a8 174 * @note the underlying RTOS may have a limit to the maximum wait time
daniwestside 0:85df64b421a8 175 * due to internal 32-bit computations, but this is guaranteed to work if the
daniwestside 0:85df64b421a8 176 * wait is <= 0x7fffffff milliseconds (~24 days). If the limit is exceeded,
daniwestside 0:85df64b421a8 177 * the wait will time out earlier than specified.
daniwestside 0:85df64b421a8 178 */
daniwestside 0:85df64b421a8 179 T *calloc_until(uint64_t millisec)
daniwestside 0:85df64b421a8 180 {
daniwestside 0:85df64b421a8 181 return _pool.calloc_until(millisec);
daniwestside 0:85df64b421a8 182 }
daniwestside 0:85df64b421a8 183
daniwestside 0:85df64b421a8 184 /** Put a mail in the queue.
daniwestside 0:85df64b421a8 185 *
daniwestside 0:85df64b421a8 186 * @param mptr Memory block previously allocated with Mail::alloc or Mail::calloc.
daniwestside 0:85df64b421a8 187 *
daniwestside 0:85df64b421a8 188 * @return Status code that indicates the execution status of the function (osOK on success).
daniwestside 0:85df64b421a8 189 *
daniwestside 0:85df64b421a8 190 * @note You may call this function from ISR context.
daniwestside 0:85df64b421a8 191 */
daniwestside 0:85df64b421a8 192 osStatus put(T *mptr)
daniwestside 0:85df64b421a8 193 {
daniwestside 0:85df64b421a8 194 return _queue.put(mptr);
daniwestside 0:85df64b421a8 195 }
daniwestside 0:85df64b421a8 196
daniwestside 0:85df64b421a8 197 /** Get a mail from the queue.
daniwestside 0:85df64b421a8 198 *
daniwestside 0:85df64b421a8 199 * @param millisec Timeout value (default: osWaitForever).
daniwestside 0:85df64b421a8 200 *
daniwestside 0:85df64b421a8 201 * @return Event that contains mail information or error code.
daniwestside 0:85df64b421a8 202 * @retval osEventMessage Message received.
daniwestside 0:85df64b421a8 203 * @retval osOK No mail is available (and no timeout was specified).
daniwestside 0:85df64b421a8 204 * @retval osEventTimeout No mail has arrived during the given timeout period.
daniwestside 0:85df64b421a8 205 * @retval osErrorParameter A parameter is invalid or outside of a permitted range.
daniwestside 0:85df64b421a8 206 *
daniwestside 0:85df64b421a8 207 * @note You may call this function from ISR context if the millisec parameter is set to 0.
daniwestside 0:85df64b421a8 208 */
daniwestside 0:85df64b421a8 209 osEvent get(uint32_t millisec = osWaitForever)
daniwestside 0:85df64b421a8 210 {
daniwestside 0:85df64b421a8 211 osEvent evt = _queue.get(millisec);
daniwestside 0:85df64b421a8 212 if (evt.status == osEventMessage) {
daniwestside 0:85df64b421a8 213 evt.status = osEventMail;
daniwestside 0:85df64b421a8 214 }
daniwestside 0:85df64b421a8 215 return evt;
daniwestside 0:85df64b421a8 216 }
daniwestside 0:85df64b421a8 217
daniwestside 0:85df64b421a8 218 /** Free a memory block from a mail.
daniwestside 0:85df64b421a8 219 *
daniwestside 0:85df64b421a8 220 * @param mptr Pointer to the memory block that was obtained with Mail::get.
daniwestside 0:85df64b421a8 221 *
daniwestside 0:85df64b421a8 222 * @return Status code that indicates the execution status of the function (osOK on success).
daniwestside 0:85df64b421a8 223 *
daniwestside 0:85df64b421a8 224 * @note You may call this function from ISR context.
daniwestside 0:85df64b421a8 225 */
daniwestside 0:85df64b421a8 226 osStatus free(T *mptr)
daniwestside 0:85df64b421a8 227 {
daniwestside 0:85df64b421a8 228 return _pool.free(mptr);
daniwestside 0:85df64b421a8 229 }
daniwestside 0:85df64b421a8 230
daniwestside 0:85df64b421a8 231 private:
daniwestside 0:85df64b421a8 232 Queue<T, queue_sz> _queue;
daniwestside 0:85df64b421a8 233 MemoryPool<T, queue_sz> _pool;
daniwestside 0:85df64b421a8 234 };
daniwestside 0:85df64b421a8 235
daniwestside 0:85df64b421a8 236 /** @}*/
daniwestside 0:85df64b421a8 237 /** @}*/
daniwestside 0:85df64b421a8 238
daniwestside 0:85df64b421a8 239 }
daniwestside 0:85df64b421a8 240
daniwestside 0:85df64b421a8 241 #endif
daniwestside 0:85df64b421a8 242
daniwestside 0:85df64b421a8 243 #endif
daniwestside 0:85df64b421a8 244
daniwestside 0:85df64b421a8 245