qf_mem.c

Go to the documentation of this file.

//$file${src::qf::qf_mem.c} vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv
//
// Model: qpc.qm
// File:  ${src::qf::qf_mem.c}
//
// This code has been generated by QM 7.0.0 <www.state-machine.com/qm>.
// DO NOT EDIT THIS FILE MANUALLY. All your changes will be lost.
//
// Copyright (C) 2005 Quantum Leaps, LLC. All rights reserved.
//
//                    Q u a n t u m  L e a P s
//                    ------------------------
//                    Modern Embedded Software
//
// SPDX-License-Identifier: GPL-3.0-or-later OR LicenseRef-QL-commercial
//
// The QP/C software is dual-licensed under the terms of the open-source GNU
// General Public License (GPL) or under the terms of one of the closed-
// source Quantum Leaps commercial licenses.
//
// Redistributions in source code must retain this top-level comment block.
// Plagiarizing this software to sidestep the license obligations is illegal.
//
// NOTE:
// The GPL does NOT permit the incorporation of this code into proprietary
// programs. Please contact Quantum Leaps for commercial licensing options,
// which expressly supersede the GPL and are designed explicitly for
// closed-source distribution.
//
// Quantum Leaps contact information:
// <www.state-machine.com/licensing>
// <info@state-machine.com>
//
//$endhead${src::qf::qf_mem.c} ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
#define QP_IMPL           // this is QP implementation
#include "qp_port.h"      // QP port
#include "qp_pkg.h"       // QP package-scope interface
#include "qsafe.h"        // QP Functional Safety (FuSa) Subsystem
#ifdef Q_SPY              // QS software tracing enabled?
    #include "qs_port.h"  // QS port
    #include "qs_pkg.h"   // QS facilities for pre-defined trace records
#else
    #include "qs_dummy.h" // disable the QS software tracing
#endif // Q_SPY
 
Q_DEFINE_THIS_MODULE("qf_mem")
 
//$skip${QP_VERSION} vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv
// Check for the minimum required QP version
#if (QP_VERSION < 730U) || (QP_VERSION != ((QP_RELEASE^4294967295U)%0x2710U))
#error qpc version 7.3.0 or higher required
#endif
//$endskip${QP_VERSION} ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
//$define${QF::QMPool} vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv
 
//${QF::QMPool} ..............................................................
 
//${QF::QMPool::init} ........................................................
//! @public @memberof QMPool
void QMPool_init(QMPool * const me,
    void * const poolSto,
    uint_fast32_t const poolSize,
    uint_fast16_t const blockSize)
{
    QF_CRIT_STAT
    QF_CRIT_ENTRY();
    QF_MEM_SYS();
 
    Q_REQUIRE_INCRIT(100, poolSto != (void *)0);
    Q_REQUIRE_INCRIT(101, poolSize >= (uint_fast32_t)sizeof(QFreeBlock));
    Q_REQUIRE_INCRIT(102, (uint_fast16_t)(blockSize + sizeof(QFreeBlock))
                          > blockSize);
 
    me->free_head = (QFreeBlock *)poolSto;
 
    // find # free blocks in a memory block, NO DIVISION
    me->blockSize = (QMPoolSize)(2U * sizeof(void *));
    uint_fast16_t nblocks = 1U;
    while (me->blockSize < (QMPoolSize)blockSize) {
        me->blockSize += (QMPoolSize)sizeof(QFreeBlock);
        ++nblocks;
    }
 
    // the pool buffer must fit at least one rounded-up block
    Q_ASSERT_INCRIT(110, poolSize >= me->blockSize);
 
    // start at the head of the free list
    QFreeBlock *fb = me->free_head;
    uint32_t nTot = 1U; // the last block already in the list
 
    // chain all blocks together in a free-list...
    for (uint_fast32_t size = poolSize - me->blockSize;
         size >= (uint_fast32_t)me->blockSize;
         size -= (uint_fast32_t)me->blockSize)
    {
        fb->next = &fb[nblocks]; // point next link to next block
    #ifndef Q_UNSAFE
        fb->next_dis = (uintptr_t)(~Q_PTR2UINT_CAST_(fb->next));
    #endif
        fb = fb->next;   // advance to the next block
        ++nTot;          // one more free block in the pool
    }
 
    // dynamic range check
    #if (QF_MPOOL_CTR_SIZE == 1U)
    Q_ENSURE_INCRIT(190, nTot < 0xFFU);
    #elif (QF_MPOOL_CTR_SIZE == 2U)
    Q_ENSURE_INCRIT(190, nTot < 0xFFFFU);
    #endif
 
    fb->next  = (QFreeBlock *)0; // the last link points to NULL
 
    me->nTot  = (QMPoolCtr)nTot;
    me->nFree = me->nTot;        // all blocks are free
    me->start = (QFreeBlock *)poolSto; // the original start this pool buffer
    me->end   = fb;              // the last block in this pool
 
    #ifndef Q_UNSAFE
    me->free_head_dis = (uintptr_t)~Q_PTR2UINT_CAST_(me->free_head);
    me->nFree_dis     = (QMPoolCtr)~me->nFree;
    me->nMin          = me->nTot;  // the minimum # free blocks
    fb->next_dis      = (uintptr_t)(~Q_PTR2UINT_CAST_(fb->next));
    #endif
 
    QF_MEM_APP();
    QF_CRIT_EXIT();
}
 
//${QF::QMPool::get} .........................................................
//! @public @memberof QMPool
void * QMPool_get(QMPool * const me,
    uint_fast16_t const margin,
    uint_fast8_t const qsId)
{
    #ifndef Q_SPY
    Q_UNUSED_PAR(qsId);
    #endif
 
    QF_CRIT_STAT
    QF_CRIT_ENTRY();
    QF_MEM_SYS();
 
    // get volatile into temporaries
    QFreeBlock *fb = me->free_head;
    QMPoolCtr nFree = me->nFree;
 
    #ifndef Q_UNSAFE
    Q_INVARIANT_INCRIT(301, Q_PTR2UINT_CAST_(fb)
                            == (uintptr_t)~me->free_head_dis);
    QMPoolCtr const dis = (QMPoolCtr)~me->nFree_dis;
    Q_INVARIANT_INCRIT(302, nFree == dis);
    #endif // ndef Q_UNSAFE
 
    // have more free blocks than the requested margin?
    if (nFree > (QMPoolCtr)margin) {
        Q_ASSERT_INCRIT(310, fb != (QFreeBlock *)0);
 
        QFreeBlock * const fb_next = fb->next; // fast temporary
 
    #ifndef Q_UNSAFE
        // the free block must have integrity (duplicate inverse storage)
        Q_INVARIANT_INCRIT(311, Q_PTR2UINT_CAST_(fb_next)
                                == (uintptr_t)~fb->next_dis);
    #endif // ndef Q_UNSAFE
 
        --nFree; // one less free block
        if (nFree == 0U) { // is the pool becoming empty?
            // pool is becoming empty, so the next free block must be NULL
            Q_ASSERT_INCRIT(320, fb_next == (QFreeBlock *)0);
 
            me->nFree = 0U;
    #ifndef Q_UNSAFE
            me->nFree_dis = (QMPoolCtr)~0U;
            me->nMin = 0U; // remember that the pool got empty
    #endif // ndef Q_UNSAFE
        }
        else {
            me->nFree = nFree; // update the original
    #ifndef Q_UNSAFE
            me->nFree_dis = (QMPoolCtr)~nFree;
 
            // The pool is not empty, so the next free-block pointer
            // must be in range.
            Q_INVARIANT_INCRIT(330,
                (me->start <= fb_next) && (fb_next <= me->end));
 
            // is the # free blocks the new minimum so far?
            if (me->nMin > nFree) {
                me->nMin = nFree; // remember the minimum so far
            }
    #endif // ndef Q_UNSAFE
        }
 
        me->free_head = fb_next; // set the head to the next free block
    #ifndef Q_UNSAFE
        me->free_head_dis = (uintptr_t)(~Q_PTR2UINT_CAST_(fb_next));
    #endif // ndef Q_UNSAFE
 
        QS_BEGIN_PRE(QS_QF_MPOOL_GET, qsId)
            QS_TIME_PRE();         // timestamp
            QS_OBJ_PRE(me);        // this memory pool
            QS_MPC_PRE(nFree);     // # of free blocks in the pool
    #ifndef Q_UNSAFE
            QS_MPC_PRE(me->nMin);  // min # free blocks ever in the pool
    #else
            QS_MPC_PRE(0U);        // min # free blocks (not available)
    #endif // ndef Q_UNSAFE
        QS_END_PRE()
    }
    else { // don't have enough free blocks at this point
        fb = (QFreeBlock *)0;
 
        QS_BEGIN_PRE(QS_QF_MPOOL_GET_ATTEMPT, qsId)
            QS_TIME_PRE();         // timestamp
            QS_OBJ_PRE(me);        // this memory pool
            QS_MPC_PRE(nFree);     // # of free blocks in the pool
            QS_MPC_PRE(margin);    // the requested margin
        QS_END_PRE()
    }
 
    QF_MEM_APP();
    QF_CRIT_EXIT();
 
    return fb; // return the block or NULL pointer to the caller
}
 
//${QF::QMPool::put} .........................................................
//! @public @memberof QMPool
void QMPool_put(QMPool * const me,
    void * const block,
    uint_fast8_t const qsId)
{
    #ifndef Q_SPY
    Q_UNUSED_PAR(qsId);
    #endif
 
    QFreeBlock * const fb = (QFreeBlock *)block;
 
    QF_CRIT_STAT
    QF_CRIT_ENTRY();
    QF_MEM_SYS();
 
    // get volatile into temporaries
    QFreeBlock * const free_head = me->free_head;
    QMPoolCtr nFree = me->nFree;
 
    #ifndef Q_UNSAFE
    Q_INVARIANT_INCRIT(401, Q_PTR2UINT_CAST_(free_head)
                            == (uintptr_t)~me->free_head_dis);
    QMPoolCtr const dis = (QMPoolCtr)~me->nFree_dis;
    Q_INVARIANT_INCRIT(402, nFree == dis);
 
    Q_REQUIRE_INCRIT(410, nFree < me->nTot);
    Q_REQUIRE_INCRIT(411, (me->start <= fb) && (fb <= me->end));
 
    // the block must not be in the pool already
    Q_REQUIRE_INCRIT(412, Q_PTR2UINT_CAST_(fb->next)
        != (uintptr_t)~fb->next_dis);
    #endif // ndef Q_UNSAFE
 
    ++nFree; // one more free block in this pool
 
    me->free_head = fb; // set as new head of the free list
    me->nFree     = nFree;
    fb->next      = free_head; // link into the list
    #ifndef Q_UNSAFE
    me->free_head_dis = (uintptr_t)(~Q_PTR2UINT_CAST_(fb));
    me->nFree_dis     = (QMPoolCtr)~nFree;
    fb->next_dis      = (uintptr_t)(~Q_PTR2UINT_CAST_(free_head));
    #endif
 
    QS_BEGIN_PRE(QS_QF_MPOOL_PUT, qsId)
        QS_TIME_PRE();         // timestamp
        QS_OBJ_PRE(me);        // this memory pool
        QS_MPC_PRE(nFree);     // the # free blocks in the pool
    QS_END_PRE()
 
    QF_MEM_APP();
    QF_CRIT_EXIT();
}
//$enddef${QF::QMPool} ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^