BufferManagerComponentImpl.hpp

Go to the documentation of this file.

// ======================================================================
// \title  BufferManagerComponentImpl.hpp
// \author tcanham
// \brief  hpp file for BufferManager component implementation class
//
// \copyright
// Copyright 2009-2015, by the California Institute of Technology.
// ALL RIGHTS RESERVED.  United States Government Sponsorship
// acknowledged.
//
// ======================================================================

#ifndef BufferManager_HPP
#define BufferManager_HPP

#include "Svc/BufferManager/BufferManagerComponentAc.hpp"
#include <Fw/Types/MemAllocator.hpp>
#include "BufferManagerComponentImplCfg.hpp"

namespace Svc
{

    // To use the class, instantiate an instance of the BufferBins struct below. This
    // table specifies N buffers of M size per bin. Up to MAX_NUM_BINS bins can be specified.
    // The table is copied when setup() is called, so it does not need to be retained after
    // the call.
    //
    // The rules for specifying bins:
    // 1. For each bin (BufferBins.bins[n]), specify the size of the buffers (bufferSize) in the
    //    bin and how many buffers for that bin (numBuffers).
    // 2. The bins should be ordered based on an increasing bufferSize to allow BufferManager to
    //    search for available buffers. When receiving a request for a buffer, the component will
    //    search for the first buffer from the bins that is equal to or greater
    //    than the requested size, starting at the beginning of the table.
    // 3. Any unused bins should have numBuffers set to 0.
    // 4. A single bin can be specified if a single size is needed.
    //
    // If a buffer is requested that can't be found among available buffers, the call will
    //    return an Fw::Buffer with a size of zero. It is expected that the user will notice
    //    and have the appropriate response for the design. If an empty buffer is returned to
    //    the BufferManager instance, a warning event will be issued but no other action will
    //    be taken.
    //
    // Buffer manager will assert under the following conditions:
    // 1. A returned buffer has the incorrect manager ID.
    // 2. A returned buffer has an incorrect buffer ID.
    // 3. A returned buffer is returned with a correct buffer ID, but it isn't already allocated.
    // 4. A returned buffer has an indicated size larger than originally allocated.
    // 5. A returned buffer has a pointer different than the one originally allocated.
    //
    // Note that a pointer to the Fw::MemAllocator used in setup() is stored for later memory cleanup.
    // The instance of the allocator must persist beyond calling the cleanup() function or the
    // destructor of BufferManager if cleanup() is not called. If a project-specific manual memory
    // allocator is not needed, Fw::MallocAllocator can be used.

    class BufferManagerComponentImpl : public BufferManagerComponentBase
    {

    public:

        // ----------------------------------------------------------------------
        // Construction, initialization, and destruction
        // ----------------------------------------------------------------------

        BufferManagerComponentImpl(
            const char *const compName 
        );

        // Defines a buffer bin
        struct BufferBin
        {
            NATIVE_UINT_TYPE bufferSize; 
            NATIVE_UINT_TYPE numBuffers; 
        };

        // Set of bins for the BufferManager
        struct BufferBins
        {
            BufferBin bins[BUFFERMGR_MAX_NUM_BINS]; 
        };


        void setup(
            NATIVE_UINT_TYPE mgrID,      
            NATIVE_UINT_TYPE memID,      
            Fw::MemAllocator &allocator, 
            const BufferBins &bins       
        );

        void cleanup();              // Free memory prior to end of program if desired. Otherwise,
                                         // will be deleted in destructor

        ~BufferManagerComponentImpl();

    PRIVATE :

        // ----------------------------------------------------------------------
        // Handler implementations for user-defined typed input ports
        // ----------------------------------------------------------------------

        void
        bufferSendIn_handler(
            const NATIVE_INT_TYPE portNum, 
            Fw::Buffer &fwBuffer);

        Fw::Buffer bufferGetCallee_handler(
            const NATIVE_INT_TYPE portNum, 
            U32 size);

        void schedIn_handler(
            const NATIVE_INT_TYPE portNum, 
            U32 context 
        );


        bool m_setup;             
        bool m_cleaned;           
        NATIVE_UINT_TYPE m_mgrId; 

        BufferBins m_bufferBins; 

        struct AllocatedBuffer
        {
            Fw::Buffer buff; 
            U8 *memory;      
            U32 size;        
            bool allocated;  
        };

        AllocatedBuffer *m_buffers;    
        Fw::MemAllocator *m_allocator; 
        NATIVE_UINT_TYPE m_memId; 
        NATIVE_UINT_TYPE m_numStructs; 

        // stats
        U32 m_highWater; 
        U32 m_currBuffs; 
        U32 m_noBuffs; 
        U32 m_emptyBuffs; 
    };

} // end namespace Svc

#endif