Home /Modules/cpu/SLMemoryInterface.sleela

SLMemoryInterface.sleela

lib/cpu/components/SLMemoryInterface.sleela · 191 line(s) · sleela

<< lib/cpu/components/SLMemoryInterface.sleela
   SLeeLa Standard Library Definition.
   Definition: Defines SLMemoryInterface — an OOD interface/adapter layer that
     sits between the system and a real SLMemoryModule and imposes a REFRESH
     DUTY CYCLE borrowed from a chosen target memory technology. It lets the
     actual RAM (e.g. a DDR5-6400 module) be operated so that it *refreshes as
     though it were* an older/newer tech (e.g. DDR2), for special-purpose runs —
     compatibility testing, legacy-cadence workloads, deterministic timing.
   
     Scope is deliberate and important: the cadence is addressed ENTIRELY in the
     Sleela software layer. This class models how the Sleela stack (the modeled
     memory controller / the VM's view of memory availability) treats refresh
     timing; it does NOT reach the actual host operating system's memory
     management, and it does NOT re-drive the underlying data rate. The wrapped
     module keeps its native identity and its real backing store untouched —
     only the observed refresh duty (fraction of time lost to refresh) changes.
   
     Pattern: Decorator/Adapter over SLMemoryModule. You compose BOTH the
     interface AND the module in the build's OOD slot: install a real module,
     then install an interface that wraps it and declares the target cadence.
   
     The cadence itself is filled by a Dynamite Connector (SLCadenceConnector),
     not by setters: connect() plugs a named, resolve-then-load cadence binding
     into the interface's slot and reads back its refresh timings.
   
   Family: cpu.components. Wraps SLMemoryModule; fills its cadence slot with an
     SLCadenceConnector; installed in SLExecutorBuild; selected via
     SLComponentCatalog. >>
#sleela 2.5
material;
class SLMemoryInterface {
  < ---- 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 = 11267;
  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-16";
  < 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; }
  < Target-cadence technology ids mirror SLMemoryModule.TECH_* so the interface >
  < can present any tier's refresh discipline over any real module. >
  static final int TECH_SRAM  = 0;
  static final int TECH_DRAM  = 1;
  static final int TECH_SDRAM = 2;
  static final int TECH_DDR   = 3;
  static final int TECH_DDR2  = 4;
  static final int TECH_DDR3  = 5;
  static final int TECH_DDR4  = 6;
  static final int TECH_DDR5  = 7;

  < nameful: "DDR2-cadence interface", ... >
  String partName;
  < the REAL module in the system (e.g. DDR5-6400) >
  SLMemoryModule actual;
  < the cadence presented (mirrors the slot connector) >
  int targetTech;

  < The cadence SLOT is filled by a Dynamite Connector, not by setters. The >
  < connector resolves a named generation (or a custom profile) into the >
  < refresh timings this interface reads back once the connector is loaded. >
  SLCadenceConnector slot;

  < Refresh model, in nanoseconds (the Sleela-layer cadence, not host timers): >
  < tREFI = average refresh interval (how often a refresh is issued) >
  < tRFC  = refresh command time (how long the array is busy per refresh) >
  < The duty the system sees available is (tREFI - tRFC) / tREFI. These are >
  < populated from the connected cadence connector, never set directly. >
  int tREFI_ns;
  int tRFC_ns;
  < 1 = the cadence overlay is active >
  int engaged;

  < Wrap a real module and present the given target technology's refresh >
  < cadence by building and connecting a Dynamite cadence connector for it. >
  void configure(String name, SLMemoryModule realModule, int cadenceTech) {
    partName = name; actual = realModule; engaged = 1;
    SLCadenceConnector c = new SLCadenceConnector();
    c.initialize(cadenceTech, name);
    c.resolve();
    connect(c);
  }

  < Plug a cadence connector into the slot: resolve-then-load it (if the caller >
  < has not already), then read its resolved timings. Fail-closed — a connector >
  < that will not load leaves the overlay disengaged with a refresh-free duty. >
  boolean connect(SLCadenceConnector connector) {
    slot = connector;
    if (connector == null) { targetTech = -1; tREFI_ns = 0; tRFC_ns = 0; return false; }
    boolean ok = connector.load();
    if (ok == false) {
      < not resolved/loadable: leave cadence inert (100% duty), overlay off. >
      targetTech = connector.cadenceTech(); tREFI_ns = 0; tRFC_ns = 0;
      return false;
    }
    targetTech = connector.cadenceTech();
    tREFI_ns = connector.refreshIntervalNs();
    tRFC_ns = connector.refreshTimeNs();
    return true;
  }

  < The connector currently filling the cadence slot (null if none). >
  SLCadenceConnector cadenceSlot() { return slot; }

  void engage()    { engaged = 1; }
  < pass the real module through untouched >
  void disengage() { engaged = 0; }

  < Available duty as a percentage: the share of time NOT spent refreshing. >
  < 100% when the overlay is off or the cadence is refresh-free. >
  int availableDutyPct() {
    if (engaged == 0 || tREFI_ns <= 0) { return 100; }
    int lost = (tRFC_ns * 100) / tREFI_ns;
    int avail = 100 - lost;
    if (avail < 0) { avail = 0; }
    return avail;
  }

  < Refresh overhead the cadence costs, as a percentage of time. >
  int refreshOverheadPct() { return 100 - availableDutyPct(); }

  < The module's REAL peak bandwidth, unscaled (native data rate preserved). >
  int nativeBandwidthMBs() { return (actual != null) ? actual.peakBandwidthMBs() : 0; }

  < Effective bandwidth the system observes: real peak scaled by the available >
  < duty of the presented cadence. The data rate is unchanged; availability is >
  < what the refresh duty cycle shapes. >
  int effectiveBandwidthMBs() {
    if (actual == null) { return 0; }
    if (engaged == 0) { return actual.peakBandwidthMBs(); }
    return (actual.peakBandwidthMBs() * availableDutyPct()) / 100;
  }

  < Pass-through identity of the REAL module (never masked by the overlay). >
  SLMemoryModule module()     { return actual; }
  int nativeTech()            { return (actual != null) ? actual.tech() : -1; }
  String nativeTechName()     { return (actual != null) ? actual.technologyName() : "none"; }
  int capacityMiB()           { return (actual != null) ? actual.totalCapacityMiB() : 0; }
  int channelCount()          { return (actual != null) ? actual.channelCount() : 0; }

  String name()               { return partName; }
  boolean active()            { return engaged == 1; }
  int cadenceTech()           { return targetTech; }
  int refreshIntervalNs()     { return tREFI_ns; }
  int refreshTimeNs()         { return tRFC_ns; }

  String refreshesAsName() {
    if (targetTech == TECH_SRAM)  { return "SRAM"; }
    if (targetTech == TECH_DRAM)  { return "DRAM"; }
    if (targetTech == TECH_SDRAM) { return "SDRAM"; }
    if (targetTech == TECH_DDR)   { return "DDR"; }
    if (targetTech == TECH_DDR2)  { return "DDR2"; }
    if (targetTech == TECH_DDR3)  { return "DDR3"; }
    if (targetTech == TECH_DDR4)  { return "DDR4"; }
    if (targetTech == TECH_DDR5)  { return "DDR5"; }
    return "custom";
  }
}