qmpool.h

00001 //////////////////////////////////////////////////////////////////////////////
00002 // Product: QF/C++
00003 // Last Updated for Version: 4.0.00
00004 // Date of the Last Update:  Apr 06, 2008
00005 //
00006 //                    Q u a n t u m     L e a P s
00007 //                    ---------------------------
00008 //                    innovating embedded systems
00009 //
00010 // Copyright (C) 2002-2008 Quantum Leaps, LLC. All rights reserved.
00011 //
00012 // This software may be distributed and modified under the terms of the GNU
00013 // General Public License version 2 (GPL) as published by the Free Software
00014 // Foundation and appearing in the file GPL.TXT included in the packaging of
00015 // this file. Please note that GPL Section 2[b] requires that all works based
00016 // on this software must also be made publicly available under the terms of
00017 // the GPL ("Copyleft").
00018 //
00019 // Alternatively, this software may be distributed and modified under the
00020 // terms of Quantum Leaps commercial licenses, which expressly supersede
00021 // the GPL and are specifically designed for licensees interested in
00022 // retaining the proprietary status of their code.
00023 //
00024 // Contact information:
00025 // Quantum Leaps Web site:  http://www.quantum-leaps.com
00026 // e-mail:                  info@quantum-leaps.com
00027 //////////////////////////////////////////////////////////////////////////////
00028 #ifndef qmpool_h
00029 #define qmpool_h
00030 
00031 /// \file
00032 /// \ingroup qf
00033 /// \brief platform-independent memory pool interface.
00034 ///
00035 /// This header file must be included in all QF ports that use native QF
00036 /// memory pool implementation.
00037 
00038 
00039 //////////////////////////////////////////////////////////////////////////////
00040 #ifndef QF_MPOOL_SIZ_SIZE
00041     /// \brief macro to override the default ::QMPoolSize size.
00042     /// Valid values 1, 2, or 4; default 2
00043     #define QF_MPOOL_SIZ_SIZE 2
00044 #endif
00045 #if (QF_MPOOL_SIZ_SIZE == 1)
00046 
00047     /// \brief The data type to store the block-size based on the macro
00048     /// #QF_MPOOL_SIZ_SIZE.
00049     ///
00050     /// The dynamic range of this data type determines the maximum size
00051     /// of blocks that can be managed by the native QF event pool.
00052     typedef uint8_t QMPoolSize;
00053 #elif (QF_MPOOL_SIZ_SIZE == 2)
00054 
00055     typedef uint16_t QMPoolSize;
00056 #elif (QF_MPOOL_SIZ_SIZE == 4)
00057     typedef uint32_t QMPoolSize;
00058 #else
00059     #error "QF_MPOOL_SIZ_SIZE defined incorrectly, expected 1, 2, or 4"
00060 #endif
00061 
00062 //////////////////////////////////////////////////////////////////////////////
00063 #ifndef QF_MPOOL_CTR_SIZE
00064 
00065     /// \brief macro to override the default QMPoolCtr size.
00066     /// Valid values 1, 2, or 4; default 2
00067     #define QF_MPOOL_CTR_SIZE 2
00068 #endif
00069 #if (QF_MPOOL_CTR_SIZE == 1)
00070 
00071     /// \brief The data type to store the block-counter based on the macro
00072     /// #QF_MPOOL_CTR_SIZE.
00073     ///
00074     /// The dynamic range of this data type determines the maximum number
00075     /// of blocks that can be stored in the pool.
00076     typedef uint8_t QMPoolCtr;
00077 #elif (QF_MPOOL_CTR_SIZE == 2)
00078     typedef uint16_t QMPoolCtr;
00079 #elif (QF_MPOOL_CTR_SIZE == 4)
00080     typedef uint32_t QMPoolCtr;
00081 #else
00082     #error "QF_MPOOL_CTR_SIZE defined incorrectly, expected 1, 2, or 4"
00083 #endif
00084 
00085 //////////////////////////////////////////////////////////////////////////////
00086 /// \brief Native QF memory pool class
00087 ///
00088 /// This class describes the native QF memory pool, which can be used as
00089 /// the event pool for dynamic event allocation, or as a fast, deterministic
00090 /// fixed block-size heap for any other objects in your application.
00091 ///
00092 /// The ::QMPool structure contains only data members for managing a memory
00093 /// pool, but does not contain the pool storage, which must be provided
00094 /// externally during the pool initialization.
00095 ///
00096 /// The native QF event pool is configured by defining the macro
00097 /// #QF_EPOOL_TYPE_ as QEQueue in the specific QF port header file.
00098 class QMPool {
00099 private:
00100 
00101     /// start of the memory managed by this memory pool
00102     void *m_start;
00103 
00104     /// end of the memory managed by this memory pool
00105     void *m_end;
00106 
00107     /// linked list of free blocks
00108     void *m_free;
00109 
00110     ///  maximum block size (in bytes)
00111     QMPoolSize m_blockSize;
00112 
00113     /// total number of blocks
00114     QMPoolCtr m_nTot;
00115 
00116     /// number of free blocks remaining
00117     QMPoolCtr m_nFree;
00118 
00119     /// minimum number of free blocks ever present in this pool
00120     ///
00121     /// \note this attribute remembers the low watermark of the pool,
00122     /// which provides a valuable information for sizing event pools.
00123     /// \sa QF::getPoolMargin().
00124     QMPoolCtr m_nMin;
00125 
00126 public:
00127 
00128     /// \brief Initializes the native QF event pool
00129     ///
00130     /// The parameters are as follows: \a poolSto is the pool storage,
00131     /// \a poolSize is the size of the pool storage in bytes, and
00132     /// \a blockSize is the block size of this pool.
00133     ///
00134     /// The caller of this method must make sure that the \a poolSto pointer
00135     /// is properly aligned. In particular, it must be possible to efficiently
00136     /// store a pointer at the location pointed to by \a poolSto.
00137     /// Internally, the QMPool::init() function rounds up the block size
00138     /// \a blockSize so that it can fit an integer number of pointers.
00139     /// This is done to achieve proper alignment of the blocks within the
00140     /// pool.
00141     ///
00142     /// \note Due to the rounding of block size the actual capacity of the
00143     /// pool might be less than (\a poolSize / \a blockSize). You can check
00144     ///  the capacity of the pool by calling the QF::getPoolMargin() function.
00145     void init(void *poolSto, uint32_t poolSize, QMPoolSize blockSize);
00146 
00147     /// \brief Obtains a memory block from a memory pool.
00148     ///
00149     /// The only parameter \a me is a pointer to the ::QMPool from which the
00150     /// block is requested. The function returns a pointer to the allocated
00151     /// memory block or NULL if no free blocks are available.
00152     ///
00153     /// A allocated block must be returned to the same pool from which it has
00154     /// been allocated.
00155     ///
00156     /// This function can be called from any task level or ISR level.
00157     ///
00158     /// \note The memory pool \a me must be initialized before any events can
00159     /// be requested from it. Also, the QMPool::get() function uses internally
00160     /// a QF critical section, so you should be careful not to call it from
00161     /// within a critical section when nesting of critical section is not
00162     /// supported.
00163     ///
00164     /// \sa QMPool::put()
00165     void *get(void);
00166 
00167     /// \brief Returns a memory block back to a memory pool.
00168     ///
00169     ///
00170     /// This function can be called from any task level or ISR level.
00171     ///
00172     /// \note The block must be allocated from the same memory pool to which
00173     /// it is returned. The QMPool::put() function raises an assertion if the
00174     /// returned pointer to the block points outside of the original memory
00175     /// buffer managed by the memory pool. Also, the QMPool::put() function
00176     /// uses internally a QF critical section, so you should be careful not
00177     /// to call it from within a critical section when nesting of critical
00178     /// section is not supported.
00179     ///
00180     /// \sa QMPool::get()
00181     void put(void *b);
00182 
00183     /// \brief return the fixed block-size of the blocks managed by this pool
00184     QMPoolSize getBlockSize(void) const {
00185         return m_blockSize;
00186     }
00187 
00188 private:
00189     friend class QF;
00190 };
00191 
00192 #endif                                                             // qmpool_h