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 <Fw/Types/MemAllocator.hpp>
#include "Svc/BufferManager/BufferManagerComponentAc.hpp"
#include "config/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 final : public BufferManagerComponentBase {
    friend class BufferManagerTester;

  public:
    // ----------------------------------------------------------------------
    // Construction, initialization, and destruction
    // ----------------------------------------------------------------------

    BufferManagerComponentImpl(const char* const compName 
    );

    // Defines a buffer bin
    struct BufferBin {
        Fw::Buffer::SizeType bufferSize;  
        U16 numBuffers;                   
    };

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


    void setup(U16 mgrID,                    
               FwEnumStoreType 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 FwIndexType portNum, 
                              Fw::Buffer& fwBuffer);

    Fw::Buffer bufferGetCallee_handler(const FwIndexType portNum, 
                                       Fw::Buffer::SizeType size);

    void schedIn_handler(const FwIndexType portNum, 
                         U32 context                
    );

    bool m_setup;    
    bool m_cleaned;  
    U16 m_mgrId;     

    BufferBins m_bufferBins;  

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

    AllocatedBuffer* m_buffers;     
    Fw::MemAllocator* m_allocator;  
    FwEnumStoreType m_memId;        
    U16 m_numStructs;               

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

}  // end namespace Svc

#endif