WaveformSimulator.cpp

Go to the documentation of this file.

// Copyright 2015 - 2026, GIBIS-UNIFESP and the wiRedPanda contributors
// SPDX-License-Identifier: GPL-3.0-or-later
 
#include "App/BeWavedDolphin/WaveformSimulator.h"
 
#include <utility>
 
#include <QScopeGuard>
 
#include "App/Core/Common.h"
#include "App/Element/GraphicElement.h"
#include "App/Element/GraphicElementInput.h"
#include "App/Scene/Scene.h"
#include "App/Simulation/Simulation.h"
#include "App/Simulation/SimulationBlocker.h"
#include "App/Simulation/SimulationThrottleDisabler.h"
#include "App/Wiring/Port.h"
 
WaveformSimulator::WaveformSimulator(Scene *externalScene, Simulation *simulation)
    : m_externalScene(externalScene)
    , m_simulation(simulation)
{
}
 
QVector<Status> WaveformSimulator::captureInputs(const QVector<GraphicElementInput *> &inputs, const int inputPorts)
{
    QVector<Status> oldValues(inputPorts);
    int oldIndex = 0;
 
    for (auto *input : std::as_const(inputs)) {
        for (int port = 0; port < input->outputSize(); ++port) {
            // Snapshot the live port state before the simulation sweep overwrites it
            oldValues[oldIndex] = input->outputPort(port)->status();
            ++oldIndex;
        }
    }
 
    return oldValues;
} // LCOV_EXCL_LINE -- compiler-generated QVector cleanup for an exception path captureInputs() never takes
 
void WaveformSimulator::restoreInputs(const QVector<GraphicElementInput *> &inputs, const QVector<Status> &saved)
{
    qCDebug(zero) << "Restoring old values to inputs, prior to simulation.";
 
    // `saved` is indexed by PORT (one entry per output port of each input element),
    // not by element. A separate port-level index is required to avoid reading the wrong
    // saved value for multi-port inputs (e.g. InputRotary).
    int portIndex = 0;
    for (auto *input : std::as_const(inputs)) {
        for (int port = 0; port < input->outputSize(); ++port) {
            const Status savedStatus = saved.at(portIndex++);
 
            // A captured Status is four-state, and setOn() only speaks two: Status::Unknown is
            // -1 and Status::Error is 2, so `static_cast<bool>` would make BOTH true and restore
            // an undefined port ON -- a sweep turning an undriven input into a driven-high one in
            // the live circuit. Put a non-definite capture back on the port directly, which is
            // exactly what captureInputs() read, and leave the element's own on/off state alone:
            // it was never meaningfully on or off.
            if (savedStatus != Status::Active && savedStatus != Status::Inactive) {
                if (auto *outPort = input->outputPort(port)) {
                    outPort->setStatus(savedStatus);
                }
                continue;
            }
 
            const bool oldValue = (savedStatus == Status::Active);
            if (input->outputSize() > 1) {
                // Multi-port inputs (e.g. InputRotary) are one-hot: selecting any port
                // deselects the others, so calling setOn() for every port in sequence would
                // just leave the last one selected regardless of what was captured. Only the
                // port that was actually active needs to be (re-)selected.
                if (oldValue) {
                    input->setOn(oldValue, port);
                }
            } else {
                input->setOn(oldValue);
            }
        }
    }
}
 
void WaveformSimulator::sweep(const QVector<DolphinModelBuilder::Row> &rows, const int columns,
                              const std::function<bool(int row, int col)> &readInput,
                              const std::function<void(int row, int col, int value)> &writeOutput) const
{
    // Block the live simulation timer while we drive the circuit manually column by column
    qCDebug(zero) << "Creating class to pause main window simulator while creating waveform.";
    SimulationBlocker simulationBlocker(m_simulation);
    // Disable the visual refresh throttle so phases 3–4 (port-status updates) run on every
    // update() call. Without this, output port statuses are stale for most columns and the
    // waveform shows incorrect values.
    SimulationThrottleDisabler throttleDisabler(m_simulation);
 
    // Snapshot the live circuit before the reset below, and put it back on the way out. The
    // sweep resets everything so its own results are reproducible, but it is a read-only
    // QUESTION about the circuit -- without this the canvas would be left holding whatever the
    // last column produced, so a read-only-looking create_waveform would mutate the user's
    // flip-flops. Symmetrical with the reset, and it covers the state resetSimState() clears:
    // outputs plus each sequential element's edge-detection history, recursing through ICs.
    QVector<Status> liveState;
    for (auto *elm : m_externalScene->elements()) {
        if (elm && elm->type() == GraphicElement::Type) {
            elm->saveSimState(liveState);
        }
    }
    auto restoreLiveState = qScopeGuard([this, &liveState] {
        int cursor = 0;
        for (auto *elm : m_externalScene->elements()) {
            if (elm && elm->type() == GraphicElement::Type) {
                elm->restoreSimState(liveState, cursor);
            }
        }
    });
 
    // Reset every element's sequential state (Q/~Q outputs, edge-detection variables) to
    // power-on defaults before the sweep so results are reproducible regardless of any
    // prior simulation run that may have left flip-flops in a different state.
    qCDebug(zero) << "Resetting simulation state of all elements.";
    for (auto *elm : m_externalScene->elements()) {
        if (elm && elm->type() == GraphicElement::Type) {
            elm->resetSimState();
        }
    }
 
    // --- Step through each time column and compute circuit outputs ---
    // A row's index IS its position in `rows`, so the input rows and the output rows are
    // walked by the same index the model and snapshot() use; there is no separately-computed
    // offset that could disagree with them.
    for (int column = 0; column < columns; ++column) {
        qCDebug(four) << "Itr: " << column << ", rows: " << rows.size();
 
        for (int row = 0; row < rows.size(); ++row) {
            const auto &descriptor = rows.at(row);
            if (descriptor.kind != DolphinModelBuilder::RowKind::Input) {
                continue;
            }
            // Each input applies the cell value its own way (e.g. a rotary ignores lows).
            auto *input = qobject_cast<GraphicElementInput *>(descriptor.element);
            if (input) {
                input->setWaveformValue(readInput(row, column), descriptor.port);
            }
        }
 
        qCDebug(four) << "Updating the values of the circuit logic based on current input values.";
        m_simulation->update();
 
        // Write computed output port states back into the model's output rows
        qCDebug(four) << "Setting the computed output values to the waveform results.";
        for (int row = 0; row < rows.size(); ++row) {
            const auto &descriptor = rows.at(row);
            if (descriptor.kind != DolphinModelBuilder::RowKind::Output || !descriptor.element) {
                continue;
            }
            const int value = static_cast<int>(descriptor.element->inputPort(descriptor.port)->status());
            writeOutput(row, column, value);
        }
    }
}