Port.hpp

Go to the documentation of this file.

// <Port.hpp> -*- C++ -*-
 
 
#pragma once
#include <set>
#include <list>
#include <unordered_map>
#include <algorithm>
#include <ostream>
#include <string>
#include <vector>
 
#include "sparta/events/Event.hpp"
#include "sparta/simulation/TreeNode.hpp"
#include "sparta/simulation/Clock.hpp"
#include "sparta/events/Scheduleable.hpp"
#include "sparta/kernel/Scheduler.hpp"
#include "sparta/utils/SpartaAssert.hpp"
#include "sparta/utils/SpartaException.hpp"
#include "sparta/kernel/SpartaHandler.hpp"
#include "sparta/events/SchedulingPhases.hpp"
 
namespace sparta
{
    // Used for DAG predence rules
    class GlobalOrderingPoint;
 
    class Port : public TreeNode
    {
    public:
        typedef std::vector<Scheduleable *> ScheduleableList;
 
        enum Direction {
            IN,                 
            OUT,                
            UNKNOWN,            
            N_DIRECTIONS
        };
        Port(TreeNode* portset, Direction dir, const std::string & name) :
            TreeNode(nullptr, name, TreeNode::GROUP_NAME_NONE,
                     TreeNode::GROUP_IDX_NONE, "Ports"),
            dir_(dir),
            name_(name)
        {
            sparta_assert(name.length() != 0, "You cannot have an unnamed port.");
            sparta_assert(portset != nullptr,
                        "Ports must created with a PortSet: " << name);
            setExpectedParent_(portset);
            ensureParentIsPortSet_(portset);
            portset->addChild(this);
        }
 
        virtual ~Port() {}
 
        virtual void bind(Port * port) = 0;
 
        void bind(Port & port) {
            bind(&port);
        }
 
        virtual bool isBound() const {
            return (bound_ports_.empty() == false);
        }
 
        size_t getNumBoundPorts() const {
            return bound_ports_.size();
        }
 
        virtual Direction getDirection() const {
            return dir_;
        }
 
        virtual void participateInAutoPrecedence(bool participate) {
            participate_in_auto_precedence_ = participate;
        }
 
        virtual bool doesParticipateInAutoPrecedence() const {
            return participate_in_auto_precedence_;
        }
 
        std::string stringize(bool x) const override {
            (void)x;
            std::stringstream ss;
            ss << "[bound to] {";
            for(Port * p : bound_ports_) {
                if(p != bound_ports_[0]){
                    ss << ", ";
                }
                ss << p->getName() << " (" << p->getLocation() << ")";
            }
            ss << "}";
            return ss.str();
        }
 
        virtual void setPortDelay(sparta::Clock::Cycle ) {
            sparta_assert ("ERROR:Parent port's don't have delays" == 0);
        }
 
        virtual void setPortDelay(double ) {
            sparta_assert ("ERROR:Parent port's don't have delays" == 0);
        }
 
        virtual Clock::Cycle getPortDelay() const {
            sparta_assert ("ERROR:Parent port's don't have delays" == 0);
            return 0;
        }
 
        virtual void enableCollection(TreeNode*) { }
 
        virtual void setContinuing(bool continuing) {
            continuing_ = continuing;
        };
 
#ifndef DO_NOT_DOCUMENT
        template<class PObjT, void * precedes_obj = nullptr>
        void precedes(const PObjT &) {
            static_assert(precedes_obj != nullptr,
                          "You cannot set a precedence on a Port anymore -- use "
                          "registerConsumerEvent and registerProducingEvent instead");
        }
#endif
 
        bool isAlreadyBound(const Port * pt) {
            return (std::find(bound_ports_.begin(),
                              bound_ports_.end(), pt) != bound_ports_.end());
        }
 
        virtual bool isDriven(Clock::Cycle rel_cycle) const {
            (void) rel_cycle;
            bool NOT_DEFINED = true;
            sparta_assert(NOT_DEFINED == false,
                        "Function not defined for this Port: " << getName());
            return false;
        }
 
        virtual bool isDriven() const {
            bool NOT_DEFINED = true;
            sparta_assert(NOT_DEFINED == false,
                        "Function not defined for this Port: " << getName());
            return false;
        }
 
    private:
        const Direction dir_;
 
        void validateNode_() const override {
        }
 
        void ensureParentIsPortSet_(TreeNode * parent);
 
        bool participate_in_auto_precedence_ = true;
 
    protected:
 
        bool continuing_ = true;
 
        const std::string name_;
 
        std::vector<Port *> bound_ports_;
 
        SpartaHandler explicit_consumer_handler_{"base_port_null_consumer_handler"};
    };
 
    // Forward declaration
    class OutPort;
 
    class InPort : public Port
    {
    public:
        InPort(TreeNode* portset, const std::string & name,
               sparta::SchedulingPhase delivery_phase) :
            Port(portset, Port::Direction::IN, name),
            delivery_phase_(delivery_phase)
        { }
 
        void registerConsumerHandler(const SpartaHandler & handler)
        {
            sparta_assert(!explicit_consumer_handler_,
                        "Only one handler/callback is supported on this port: " << getName() <<
                        " \n\tCurrent registered handler: " << explicit_consumer_handler_.getName() <<
                        " \n\tTrying to register: " << handler.getName());
 
            explicit_consumer_handler_ = handler;
 
            // Let subclasses check out the handler...
            registerConsumerHandler_(handler);
        }
 
        void registerConsumerEvent(Scheduleable & consumer)
        {
            sparta_assert(getDirection() == Direction::IN,
                        "You cannot register a consumer on an OUT port -- that doesn't make sense: "
                        << getName() << " consumer being registered: " << consumer.Scheduleable::getLabel());
            // sparta_assert(getPhase() < TREE_FINALIZED);
            sparta_assert(isBound() == false,
                        "You cannot register a consuming event after the port is bound.  \n\tPort: '"
                        << getName() << "' Event: '" << consumer.Scheduleable::getLabel() << "'"
                        << "\n\tIf this is happening from sparta::Unit auto-precedence, set this Port's "
                        << "\n\tauto-precedence rule to false by calling the Port's method participateInAutoPrecedence(false)");
 
            port_consumers_.push_back(&consumer);
        }
 
        void bind(Port * out) override
        {
            if(out->getDirection() != Direction::OUT) {
                throw SpartaException("ERROR: Attempt to bind an inny: '" + out->getName() +
                                    "' to an inny: '" + getName() + "'");
            }
 
            // Make the OutPort do all the work including calling
            // bind_() further down...
            out->bind(this);
        }
 
        const ScheduleableList & getPortTickConsumers() const {
            return port_consumers_;
        }
 
        sparta::SchedulingPhase getDeliverySchedulingPhase() const {
            return delivery_phase_;
        }
 
        void precedes(InPort & consumer)
        {
            sparta_assert(getScheduleable_().getSchedulingPhase() == consumer.getScheduleable_().getSchedulingPhase(),
                          "ERROR: You cannot set precedence between two Ports on different phases: "
                          "producer: " << getLocation() << " consumer: " << consumer.getLocation());
            getScheduleable_().precedes(consumer.getScheduleable_());
        }
 
    protected:
 
        virtual Scheduleable & getScheduleable_() = 0;
 
        friend OutPort;
 
        friend InPort& operator>>(const GlobalOrderingPoint&, InPort&);
        friend const GlobalOrderingPoint& operator>>(InPort&, const GlobalOrderingPoint&);
 
        virtual void registerConsumerHandler_(const sparta::SpartaHandler &) {}
 
        virtual void setProducerPrecedence_(Scheduleable * producer) {
            (void) producer;
        };
 
        virtual void bind_(Port * outp) {
            bound_ports_.push_back(outp);
        }
 
        void checkSchedulerPhaseForZeroCycleDelivery_(const sparta::SchedulingPhase & user_callback_phase)
        {
            (void) user_callback_phase;
            sparta_assert(user_callback_phase >= scheduler_->getCurrentSchedulingPhase(),
                        "\n\n\tThe currently firing event: '" <<
                        scheduler_->getCurrentFiringEvent()->getLabel() <<
                        "' is in SchedulingPhase::" << scheduler_->getCurrentSchedulingPhase() <<
                        "\n\tand is driving an OutPort that's connected to a zero-cycle Inport: " << getLocation() <<
                        "\n\tUnfortunately, this InPort's registered handler '" <<
                        explicit_consumer_handler_.getName() << "' is in phase SchedulingPhase::" << user_callback_phase <<
                        ".\n\n\tThis won't work for a for a zero-cycle out_port->in_port send (where send delay == 0) "
                        "since an event on a higher phase cannot schedule an event on a lower phase within the same cycle."
                        "\n\n\tTo fix this, in the constructor of InPort '" << getName() <<
                        "' move the registered handler to at least 'sparta::SchedulingPhase::" <<
                        scheduler_->getCurrentSchedulingPhase() << "' or a later phase.\n\t\tExample: " <<
                        getName() << "(..., sparta::SchedulingPhase::" <<
                        scheduler_->getCurrentSchedulingPhase() << ");\n\n"
                        "\tOR you add a cycle delay to the InPort '" << getName() << "' via its last construction argument.\n\n");
        }
 
        ScheduleableList port_consumers_;
 
        Scheduler * scheduler_ = nullptr;
 
        const Clock * receiver_clock_ = nullptr;
 
        sparta::SchedulingPhase delivery_phase_;
    };
 
    class OutPort : public Port
    {
    public:
        OutPort(TreeNode* portset, const std::string & name,
                bool presume_zero_delay) :
            Port(portset, Port::Direction::OUT, name),
            presume_zero_delay_(presume_zero_delay)
        { }
 
        void registerProducingEvent(Scheduleable & producer)
        {
            sparta_assert(isBound() == false,
                        "You cannot register a producing event after the port is bound.  \n\tPort: '"
                        << getName() << "' Event: '" << producer.Scheduleable::getLabel() << "'"
                        << "\n\tIf this is happening from sparta::Unit auto-precedence, set this Port's "
                        << "\n\tauto-precedence rule to false by calling the Port's method participateInAutoPrecedence(false)");
 
            port_producers_.push_back(&producer);
 
            // Let derived classes know about it for precedence
            this->registerProducingEvent_(producer);
        }
 
        void registerProducingPort(InPort & producer)
        {
            sparta_assert(isBound() == false,
                          "You cannot register a producing port after the port is bound.  \n\tOutPort: '"
                          << getName() << "' InPort: '" << producer.getLocation() << "'"
                          << "\n\tIf this is happening from sparta::Unit auto-precedence, set this Port's "
                          << "\n\tauto-precedence rule to false by calling the Port's method participateInAutoPrecedence(false)");
 
            port_producers_.push_back(&producer.getScheduleable_());
 
            // Let derived classes know about it for precedence
            this->registerProducingEvent_(producer.getScheduleable_());
        }
 
        void bind(Port * in) override
        {
            if(in->getDirection() != Port::Direction::IN) {
                throw SpartaException("ERROR: Attempt to bind an outty: '" + in->getName() +
                                    "' to an outty: '" + getName() + "'");
            }
 
            if(!sync_port_) {
                sparta_assert(in->getClock()->getFrequencyMhz() == getClock()->getFrequencyMhz(),
                            "Trying to bind two ports that are on different clocks with different freq. "
                            "Recommend using SyncPorts");
            }
 
            sparta_assert(!isAlreadyBound(in),
                        "Port: '" << getLocation()
                        << "' is already bound to '" << in->getLocation() << "' ");
 
            InPort * inp = nullptr;
            if((inp = dynamic_cast<InPort *>(in)) == 0) {
                throw SpartaException("ERROR: Could not cast '" +
                                    in->getName() + "' to an InPort for some reason...");
            }
 
            // This outport precedes the newly binded in port if the
            // delay of the inport is zero and the modeler intends to
            // use the OutPort as zero delay.
            //
            // The precedence that's established is the following, but
            // only if the producer, the inport's internal events, and
            // the consumer event are all in the same phase.
            //
            //          ,-----------------------------------------------.
            //          |                                               V
            // producer -> [      inport internal delivery      ]* -> consumer
            //             [ inport handler delivery (optional) ]
            //
            //
            // * The inport -> consumer precedence is established
            //   during the consumer registration from a call to
            //   InPort::registerConsumerEvent()
            //
            if((inp->getPortDelay() == 0) && presume_zero_delay_) {
                for(auto & pd : port_producers_)
                {
                    for(auto & cons : inp->port_consumers_) {
                        sparta_assert(pd != cons,
                                    "Somehow, someway, '" << pd->getLabel() << "' is registered "
                                    << "as a producer of Port: '" << getLocation()
                                    << "' and, at the same time, a consumer of Port: '"
                                    << inp->getLocation() << "'");
                        if(pd->getSchedulingPhase() == cons->getSchedulingPhase()) {
                            std::string reason = "Port::bind(" + getLocation() + "->" + inp->getLocation() + ")";
                            pd->precedes(cons, reason);
                        }
                    }
                    inp->setProducerPrecedence_(pd);
                }
            }
            bound_ports_.push_back(inp);
            inp->setContinuing(continuing_);
            inp->bind_(this);
        }
 
    protected:
 
        virtual void registerProducingEvent_(Scheduleable &) {}
 
        ScheduleableList port_producers_;
 
        bool presume_zero_delay_ = true;
 
        bool sync_port_ = false;
    };
 
    // Binding methods
 
    inline void bind(Port * p1, Port * p2) {
        sparta_assert(p1 != nullptr);
        sparta_assert(p2 != nullptr);
        p1->bind(p2);
    }
 
    inline void bind(Port & p1, Port & p2) {
        bind(&p1, &p2);
    }
 
    inline void bind(Port * p1, Port & p2) {
        sparta_assert(p1 != nullptr);
        bind(p1, &p2);
    }
 
    inline void bind(Port & p1, Port * p2) {
        sparta_assert(p2 != nullptr);
        bind(&p1, p2);
    }
}