Mail.h

00001 /* Copyright (c) 2012 mbed.org */
00002 #ifndef MAIL_H
00003 #define MAIL_H 
00004 
00005 #include <stdint.h>
00006 #include <string.h>
00007 
00008 #include "cmsis_os.h"
00009 
00010 namespace rtos {
00011 
00012 /*! The Mail class allow to control, send, receive, or wait for mail.
00013  A mail is a memory block that is send to a thread or interrupt service routine.
00014   \tparam  T         data type of a single message element.
00015   \tparam  queue_sz  maximum number of messages in queue.
00016 */
00017 template<typename T, uint32_t queue_sz>
00018 class Mail  {
00019 public:
00020     /*! Create and Initialise Mail queue. */
00021     Mail () {
00022     #ifdef CMSIS_OS_RTX
00023         memset(_mail_q, 0, sizeof(_mail_q));
00024         _mail_p[0] = _mail_q;
00025         
00026         memset(_mail_m, 0, sizeof(_mail_m));
00027         _mail_p[1] = _mail_m;
00028         
00029         _mail_def.pool = _mail_p;
00030         _mail_def.queue_sz = queue_sz;
00031         _mail_def.item_sz = sizeof(T);
00032     #endif
00033         _mail_id = osMailCreate(&_mail_def, NULL);
00034     }
00035     
00036     /*! Allocate a memory block of type T
00037       \param   millisec  timeout value or 0 in case of no time-out. (default: 0).
00038       \return  pointer to memory block that can be filled with mail or NULL in case error.
00039     */
00040     T* alloc (uint32_t millisec=0) {
00041         return (T*)osMailAlloc(_mail_id, millisec);
00042     }
00043     
00044     /*! Allocate a memory block of type T and set memory block to zero. 
00045       \param   millisec  timeout value or 0 in case of no time-out.  (default: 0).
00046       \return  pointer to memory block that can be filled with mail or NULL in case error.
00047     */
00048     T* calloc (uint32_t millisec=0) {
00049         return (T*)osMailCAlloc(_mail_id, millisec);
00050     }
00051     
00052     /*! Put a mail in the queue.
00053       \param   mptr  memory block previously allocated with Mail::alloc or Mail::calloc.
00054       \return  status code that indicates the execution status of the function. 
00055     */
00056     osStatus put (T *mptr) {
00057         return osMailPut(_mail_id, (void*)mptr);
00058     }
00059     
00060     /*! Get a mail from a queue.
00061       \param   millisec  timeout value or 0 in case of no time-out. (default: osWaitForever).
00062       \return  event that contains mail information or error code.
00063     */
00064     osEvent get(uint32_t millisec=osWaitForever) {
00065         return osMailGet(_mail_id, millisec);
00066     }
00067     
00068     /*! Free a memory block from a mail.
00069       \param   mptr  pointer to the memory block that was obtained with Mail::get. 
00070       \return  status code that indicates the execution status of the function.
00071     */
00072     osStatus free (T *mptr) {
00073         return osMailFree(_mail_id, (void*)mptr);
00074     }
00075 
00076 private:
00077     osMailQId    _mail_id;
00078     osMailQDef_t _mail_def;
00079 #ifdef CMSIS_OS_RTX
00080     uint32_t     _mail_q[4+(queue_sz)];
00081     uint32_t     _mail_m[3+((sizeof(T)+3)/4)*(queue_sz)];
00082     void        *_mail_p[2];
00083 #endif
00084 };
00085 
00086 }
00087 
00088 #endif
00089