Home /Modules/cpu/SLIOTiming.sleela

SLIOTiming.sleela

lib/cpu/SLIOTiming.sleela · 156 line(s) · sleela

<< lib/cpu/SLIOTiming.sleela
   SLeeLa Standard Library Definition.
   Definition: Defines SLIOTiming — the expert timing settings for CONTROL of
     I/O: the handshake and transfer timing of a peripheral/port link. I/O is
     given the same careful, nameful treatment buses get, because an I/O link
     mixes an asynchronous device clock domain with the CPU's: the class states
     the link clock (variable), the setup/hold of the request/acknowledge
     handshake, the turnaround (bus direction reversal) time, and a recovery gap
     between transactions — each a named SLTiming budget. It also models the
     synchronizer latency crossing the device clock domain into the CPU domain,
     so I/O control timing is accounted honestly rather than assumed instant.
   
   The thesis "expert timings for control of I/O shall be careful and nameful"
   lives here: handshake, turnaround, and recovery each carry a name and reason,
   and the link reports whether a transaction is honored at the dialed speed.
   
   Family: cpu. Composes SLTiming and SLVoltageRail; partners SLIOBus/SLIOPort. >>
#sleela 2.5
material;
class SLIOTiming {
  < ---- Descriptive metadata (version 1.11 nested-friendly accessors) ---- >
  << Eleven catalogued attributes with getter/setter pairs, so a GUI, loader,
     or catalog can read and (where appropriate) override this record.
     Values are faithful to the subject's real origin where publicly known. >>
  String metaVersion = "1.0.0";
  int metaId = 11055;
  String metaAuthor = "Kiro Agent";
  String metaDate = "2026-10-16";
  String metaCopyright = "SLeeLa project";
  String metaTrademark = "none";
  String metaCorporation = "none";
  < metaOrigin: National | <nation> | International | Galactic >
  String metaOrigin = "International";
  String metaBirthDate = "2026-10-13";
  < metaScienceRating: maturity/robustness on a 1..10 scale >
  int metaScienceRating = 9;
  < metaNationalSchedule: a real, citable instrument or "none" >
  String metaNationalSchedule = "none";

  String getMetaVersion() { return metaVersion; }
  void setMetaVersion(String v) { metaVersion = v; }
  int getMetaId() { return metaId; }
  void setMetaId(int v) { metaId = v; }
  String getAuthor() { return metaAuthor; }
  void setAuthor(String v) { metaAuthor = v; }
  String getDate() { return metaDate; }
  void setDate(String v) { metaDate = v; }
  String getCopyright() { return metaCopyright; }
  void setCopyright(String v) { metaCopyright = v; }
  String getTrademark() { return metaTrademark; }
  void setTrademark(String v) { metaTrademark = v; }
  String getCorporation() { return metaCorporation; }
  void setCorporation(String v) { metaCorporation = v; }
  String getOrigin() { return metaOrigin; }
  void setOrigin(String v) { metaOrigin = v; }
  String getBirthDate() { return metaBirthDate; }
  void setBirthDate(String v) { metaBirthDate = v; }
  int getScienceRating() { return metaScienceRating; }
  void setScienceRating(int v) { metaScienceRating = v; }
  String getNationalSchedule() { return metaNationalSchedule; }
  void setNationalSchedule(String v) { metaNationalSchedule = v; }
  < nameful link: "console-port", "disk-link", ... >
  String name;
  < lowest link clock the operator may dial >
  int minMHz;
  < highest validated link clock >
  int maxMHz;
  < the variable link clock presently selected >
  int currentMHz;
  < flip-flops in the clock-domain-crossing synchronizer >
  int syncStages;

  < the I/O ring supply rail >
  SLVoltageRail vio;
  < settled Vio each extra MHz of ceiling needs >
  int mvPerMHz;

  < req -> ack named budget >
  SLTiming handshake;
  < bus direction reversal named budget >
  SLTiming turnaround;
  < inter-transaction recovery gap named budget >
  SLTiming recovery;

  void configure(String linkName, int floorMHz, int ceilingMHz, int synchronizerStages) {
    name = linkName; minMHz = floorMHz; maxMHz = ceilingMHz; currentMHz = floorMHz;
    syncStages = synchronizerStages; if (syncStages < 0) { syncStages = 0; }
    mvPerMHz = 0;
    int p = periodPsAt(currentMHz);
    handshake = new SLTiming(); handshake.configure("req->ack", p, 60);
    handshake.describe("device must acknowledge a request within one link clock of asserting it");
    turnaround = new SLTiming(); turnaround.configure("bus-turnaround", p, 70);
    turnaround.describe("the shared data lines must fully reverse direction before the reader drives");
    recovery = new SLTiming(); recovery.configure("recovery", p, 50);
    recovery.describe("the device needs a quiet gap after a transaction before the next command");
  }

  void attachVio(SLVoltageRail rail, int millivoltsPerMHz) { vio = rail; mvPerMHz = millivoltsPerMHz; }

  int periodPsAt(int mhz) { if (mhz <= 0) { return 0; } return 1000000 / mhz; }

  < State the measured path (propagation + setup, with hold) of each phase. >
  void setHandshake(int propPs, int setupPs, int holdPs) { handshake.setPropagation(propPs); handshake.setSetup(setupPs); handshake.setHold(holdPs); }
  void setTurnaround(int propPs, int setupPs, int holdPs) { turnaround.setPropagation(propPs); turnaround.setSetup(setupPs); turnaround.setHold(holdPs); }
  void setRecovery(int propPs, int setupPs, int holdPs) { recovery.setPropagation(propPs); recovery.setSetup(setupPs); recovery.setHold(holdPs); }

  void setJitter(int jitterPs) { handshake.setJitter(jitterPs); turnaround.setJitter(jitterPs); recovery.setJitter(jitterPs); }

  < Dial the variable link clock, clamped into [min,max] and the voltage ceiling. >
  int setClock(int mhz) {
    int target = mhz;
    if (target < minMHz) { target = minMHz; }
    if (target > maxMHz) { target = maxMHz; }
    int ceiling = voltageCeilingMHz();
    if (ceiling > 0 && target > ceiling) { target = ceiling; }
    currentMHz = target;
    retime();
    return currentMHz;
  }

  int voltageCeilingMHz() {
    if (vio == null || mvPerMHz <= 0) { return maxMHz; }
    return vio.effectiveMv() / mvPerMHz;
  }

  void retime() {
    int p = periodPsAt(currentMHz);
    handshake.setPeriod(p); turnaround.setPeriod(p); recovery.setPeriod(p);
  }

  < Latency (ps) to cross the device clock domain into the CPU domain: each >
  < synchronizer stage costs up to one link period. I/O control is not instant. >
  int synchronizerLatencyPs() { return syncStages * periodPsAt(currentMHz); }

  < Total control latency of one transaction in ps: synchronizer + handshake + >
  < turnaround + recovery consumed times. >
  int transactionLatencyPs() {
    return synchronizerLatencyPs()
         + handshake.consumedPs()
         + turnaround.consumedPs()
         + recovery.consumedPs();
  }

  < Every phase honored at the dialed clock AND Vio in limits. >
  boolean honored() {
    boolean phases = handshake.honored() && turnaround.honored() && recovery.honored();
    boolean power = (vio == null) || vio.withinLimits();
    return phases && power;
  }

  String linkName() { return name; }
  int clock() { return currentMHz; }
  int synchronizerStages() { return syncStages; }
  SLTiming handshakeBudget() { return handshake; }
}