sid/component/sched/sid-sched.txt

   1 * Name
   2   sid-sched-sim sid-sched-host sid-sched-host-accurate
   3
   4 * Synopsis
   5   These components manage multiple signal schedules.
   6
   7   Attributes: enabled? num-clients step-cycle-limit time yield-host-time?
   8               advance-count N-regular? N-time N-control N-event N-scale
   9   Pins: advance yield time-query time-high time-low N-control N-event
  10
  11   Shared library: libsched.la
  12   Symbol: sched_component_library
  13
  14 * Functionality
  15
  16   - Modelling
  17
  18     * These components function as general purpose signal schedulers.
  19       They approximately correspond to a collection of programmable clock
  20       dividers.
  21
  22     * The number of controllable outputs ("subscriptions") is a matter
  23       of configuration.
  24
  25     * The three component types are identical, except in their notions
  26       of "time".  See the Timing section below.
  27
  28   - Behaviors
  29
  30     * Configuration
  31
  32       When the "num-clients" is written-to, this component adjusts its
  33       list of scheduler clients.  Each "client" corresponds to a set of
  34       "N-" pins and attributes, with its own signalling schedule.
  35
  36     * Timing
  37
  38       There is no global concept of simulation time in sid.  Instead,
  39       each scheduler instance maintains its own notion of "time".
  40
  41       A "sid-sched-sim" scheduler maintains a 64-bit integer as a time
  42       counter.  When advancing, this "time" counter is set to jump
  43       forward to the earliest of the upcoming subscribed signals.
  44       This way, it represents the clock of a traditional event-driven
  45       simulator.
  46
  47       The "sid-sched-host" and "sid-sched-host-accurate" schedulers use
  48       a millisecond-precision timer of the host operating system.  Its
  49       "time" is simply that of the operating system.  When
  50       advancing, there may be no scheduled events due, even though
  51       there may be scheduled events.  In such a case, if the
  52       "yield-host-time?"  attribute is set to "1", a host-time
  53       scheduler will yield some amount of time to the host operating
  54       system using a function like usleep().
  55
  56       The "time-query" pin, when driven, causes a scheduler to signal
  57       its current 64-bit "time" back, in two 32-bit halves, on the
  58       "time-high", then "time-low" pins.  Similarly, the "time"
  59       attribute may be accessed to get/set the scheduler's time.
  60
  61     * Subscription
  62
  63       The scheduler maintains a number of "subscriptions".  Each
  64       subscription represents a request to provide a series of
  65       recurring "regular" signals, or a single-shot "irregular"
  66       signal, some time in the simulation's future.  Each subscription
  67       has an associated set of pins and attributes to control it.
  68
  69       Each subscription is defined by an index, a regular-vs-irregular
  70       flag, and a time quantity.  The index is a number between 0 and
  71       "num-clients" -1, and is represented as "N" in the pin/attribute
  72       list templates in this document.  The regular-vs-irregular flag
  73       is accessible as the "N-regular?" attribute.  The time
  74       quantity is accessible as the "N-time" attribute.  If the
  75       value is zero, it is interpreted as a request to cancel all pending
  76       events for this subscription.  Otherwise, the value is taken to
  77       be a delta until the "time" of the requested event.
  78
  79       You can also set these controls by driving encoded values into
  80       the "N-control" pin.  The top bit is interpreted as the
  81       regular-vs-irregular flag (1: regular, 0:irregular), and the
  82       remaining bits as the delta "time" value.  If the delta is zero,
  83       events for this subscription are cancelled.
  84
  85       In each case, the time value sent is multiplied by a scale before
  86       being merged into the master schedule.  The scaling value is
  87       available on the "N-scale" attribute, and may be specified as
  88       a plain number, or as a fraction of two numbers (e.g., "1/5").
  89
  90     * Advancing
  91
  92       When you have disabled the scheduler by setting the "enabled?"
  93       attribute to 0, advancing as described below, does not occur.
  94
  95       Whenever the "advance" input pin is driven, the scheduler may
  96       dispatch one or more signals by driving the "N-event" output
  97       pins with some value.  A counter accessed by the "advance-count"
  98       attribute is incremented.
  99
 100       Whether any particular "N-event" pin is driven depends on the
 101       subscription associated with that pin, and the passage of that
 102       scheduler's "time".  All events that are due "now", or that are
 103       overdue are dispatched.
 104
 105       If there are multiple due or overdue events, the scheduler may
 106       loop over the pending event up to "step-cycle-limit" number of
 107       times, as an optimization.  This loop may be aborted early if
 108       the "yield" input pin is driven.
 109
 110   - SID conventions
 111     * This is a functional component.
 112     * It supports state save/restore.
 113     * It does not support triggerpoints.
 114     * It prevents harmful recursion on the "advance" input pin.
 115     * It presents attributes in the "pin", "register" and "setting" categories.
 116
 117 * Environment
 118   - Related components
 119
 120     * Schedulers may be nested, though normally they are advanced via the
 121       top level event source (sid-control-cfgroot).
 122
 123         new sid-sched-sim target-sched
 124         new sid-sched-host host-sched
 125         new SOME_KIND_OF_CPU cpu
 126         set target-sched num-clients 1
 127         connect-pin main perform-activity -> target-sched advance
 128         connect-pin main perform-activity -> host-sched advance
 129         connect-pin target-sched 0-event -> cpu step!
 130         set target-sched 0-regular? 1
 131         set target-sched 0-time 50
 132
 133   - Performance
 134
 135     * These schedulers use data structures and algorithms that attempt
 136       to be efficient for large number of event subscriptions.
 137
 138     * The "sid-sched-host-accurate" variety attempts to be accurate to
 139       1 ms, but this requires many more host OS system calls and
 140       therefore slows down the simulation.  The basic "sid-sched-host"
 141       type of scheduler attempt to be accurate to only 25 ms.  It does
 142       this by frequently estimating the host time by adaptive extrapolation.
 143
 144 * SID interface reference
 145
 146
 147   - low level:
 148
 149     * pins
 150
 151       - advance | input | any | advancing
 152       - yield | input | any | advancing
 153       - N-event | output | no value | advancing
 154       - N-control | input | coded value | subscription
 155       - time-query | input | any | timing
 156       - time-high | output | high order 32 bits of 64-bit value | timing
 157       - time-low | output | low order 32 bits of 64-bit value | timing
 158
 159     * attributes
 160
 161       - state-snapshot | no category | opaque string | n/a | state save/restore
 162       - num-clients | setting | numeric | "0" | configuration
 163       - N-regular? | setting | boolean | "0" | subscription
 164       - N-time | setting | numeric | "0" | subscription
 165       - N-scale | setting | numeric fraction | "1" | subscription
 166       - N-event | pin | n/a | n/a | advancing
 167       - N-control | pin | n/a | n/a | subscription
 168       - advance | pin | n/a | n/a | advancing
 169       - yield | pin | n/a | n/a | advancing
 170       - enabled? | setting | boolean | "1" | advancing
 171       - yield-host-time? | setting | boolean | "0" | timing
 172       - step-cycle-limit | setting | numeric | advancing
 173       - time | register | numeric | timing
 174       - advance-count | register | numeric | advancing
 175