Help understanding when to use which SchedulingPhase for InPort

[timsnyder]

I see in sparta/example/CoreModel/ different ports use different sparta::SchedulingPhase. Phases I see used are:

• sparta::SchedulingPhase::PortUpdate <- the default
• sparta::SchedulingPhase::Tick
• sparta::SchedulingPhase::Flush <- a phase defined specifically for flush signaling in the sparta/example/CoreModel

sparta::SchedulingPhase::Flush is easy to understand, we add a special-case phase for flushing to happen. I'm more confused about when to use PortUpdate and when to use Tick. Can someone help me understand?

Rereading https://sparcians.github.io/map/best_practices.html#discrete_event, is the answer to my question as simple as:

• 0-cycle delay should use sparta::SchedulingPhase::Tick
• N-cycle delay should use sparta::SchedulingPhase::PortUpdate

If so, is the 0-cycle or N-cycle referring to the delay of the InPort or to the OutPort driving the InPort or to the aggregate delay of the two?

[klingaard]

The URL to the SchedulingPhases you provided above is a good reference for this discussion.

Use Case 1

The main intention of the ports is to deliver data from one unit to another with at least 1 cycle of delay. The idea was to mimic a Present-State, Next State (PSNS) paradigm where one unit produces on one cycle and the other unit receives/consumes the data in the next cycle. To simulate that behavior using Sparta Phases, the Tick phase is where you operate on Present State data and the Update/PortUpdate phase is where the Next State data is moved to Present State. The timing looks like this:

Phase	Cycle 1	Cycle 2
PortUpdate		Ports Move Data
Tick	Producer Drives	Receiver Consumes

Use Case 2

With that background, there was a use case where two units needed to communicate to each other in Present State, meaning data driven this cycle is available to consumer this cycle. The use case was almost always (if not always) a producer in the Tick phase, already past the UpdatePhase. Since there's "no turning back" in time, the Ports needed to be able to support this 0-cycle data delivery.

Phase	Cycle 1	Cycle 2
PortUpdate		Nothing to be moved
Tick	Producer Drives
	Ports Move Data
	Receiver Consumes

No, on to your question/point...

The decision on the data/signal delivery from one unit to another using Sparta Ports is always made by the receiver (i.e. InPort derivatives) not the producer. For example, for DataPorts, the DataInPort<DataT> is the decision maker on when data is to be delivered to the Consumer.

Since Sparta is designed to allow a modeler to build a runtime configurable simulation platform, a modeler can start by assuming the first use case: each port is 1 cycle or more. In that use case, the receiving Port will operate (shift data) in PortUpdate phase when data was written in the Tick phase (or any other phase) from the previous cycle. In this case, the expected delivery phase passed to InPort class derivatives should be sparta::SchedulingPhase::PortUpdate.

If, however, the communication is 0 cycles, expected delivery phase pass to InPort class derivative construction should be sparta::SchedulingPhase::Tick to facilitate the second use case above (both the producer and consumer are most likely in the Tick phase).

To make this "easier" for the modeler, DataInPort and SignalInPort (both derivative classes of InPort) have a simplified constructor that make this distinction automatically based on the expected receiving delay:

<PortType>(TreeNode* portset, const std::string & name, sparta::Clock::Cycle delay = 0) :
    <PortType>(portset, name, (delay == 0 ? 
                               sparta::SchedulingPhase::Tick : 
                               sparta::SchedulingPhase::PortUpdate), 
                delay)
    {}

This way, a modeler can do something like this in his/her receiving unit and not have to make a decision on the phase:

 MyConsumer(sparta::TreeNode * my_node, sparta::Parameters * my_params) :
    my_data_in_port_(getPortSet(), "my_data_in_port", my_params->data_port_delay)
{}

However, if the modeler chooses be explicit on providing the phase (i.e. using the other constructor), the modeler will run the risk of the hitting an "out of phase" exception condition when the delay is 0. Specifically, if the delay is 0, but the port was programmed to deliver data in a phase less than the current phase (maintained by the sparta::Scheduler), the framework will stop simulation with an error message detailing the issue it found (and recommended fixes).

Note that SyncPorts do not support this behavior (they are designed for asymmetric clocking, so 0 cycle delivery is ... weird).

I have some diagrams (in the precedence section) of how this looks in my Sparta Overview presentation.