Autres pages › why

Autres pages

Cette page n’est pas encore traduite : voici la version anglaise.

Why did it do that?

A model says what a system should do. A run says what it did. archec why puts the two together and answers three questions about any run, simulated or on the board: what happens when, why did this happen, and why did that never happen. You don't need to read the model's code to follow the answers. Each step of an answer points at the line of the model it comes from.

A small thermostat#

Here is the part of a greenhouse that matters. A sensor sends a reading every 100 ms. A thermostat starts the fan above 28 °C and stops it below 26 °C.

message READING { celsius: float32 unit °C }
message FAN_CMD { on: bool }

requirement REQ-FAN "Fan in time" {
  ears "when ctl enters Cooling, fan shall be in Running within 1s"
}

component Sensor {
  out air:         data sends READING
  var temperature: float32 = 25.0
  fn sample ```arche
    send air READING { celsius: temperature }
  ```
}

component Thermostat {
  in air:  data receives READING
  out fan: data sends FAN_CMD
  states {
    state Idle
    state Cooling {
      on-enter ```arche
        send fan FAN_CMD { on: true }
      ```
    }
    Idle -> Cooling on READING [celsius > 28.0]
    Cooling -> Idle on READING [celsius < 26.0]
  }
}

The sensor's sample runs on a thread with period 100ms, and a test case warms the air: at 1s do air.temperature = 29.5. The whole model is in test/fixtures/why/main.arche of the arche-lang repository.

What happens when…?#

Give archec why a run and no question. It prints the run's timeline:

$ archec why main.arche --test TC-HOT
TP TC-HOT "Hot afternoon": pass, the simulator, 4.000 s
   0.000 ms  ctl starts in Idle
   0.000 ms  fan starts in Stopped
 100.000 ms  air.air → ctl.air  READING celsius: 25
               … 8 more time(s), the same, to 900.000 ms
    1.000 s  air.temperature = 29.5 (the test)                main.arche:101
    1.000 s  air.air → ctl.air  READING celsius: 29.5
    1.002 s  ctl Idle → Cooling on READING [celsius > 28.0]   main.arche:49
               celsius = 29.5
    1.002 s  ctl.fan → fan.cmd  FAN_CMD on: true
    1.012 s  fan Stopped → Running on FAN_CMD [on]            main.arche:65
    …
Requirements on this run
  ✓ REQ-FAN  When ctl enters Cooling, the fan shall be in Running within 1s. — 1 time(s)

Each line is one thing that happened, in time order:

  • a message, from which port to which, with its values;
  • a state change, with the transition taken, its line in the model and the values its guard read;
  • a variable that changed, and who changed it;
  • each expect of the test case, when it was decided;
  • at the end, each requirement checked on the run.

The same message again and again, such as a reading every period, is shown once with how many times it came. --all adds the guards that did not hold and the threads' activations.

Why did this happen?#

Name an event after the run. archec why follows it back to where it started:

$ archec why main.arche --test TC-HOT "fan Running"
fan Running                Stopped → Running on FAN_CMD [on]           main.arche:65    1.012 s
                             on = true
 ← FAN_CMD on: true        ctl.fan → fan.cmd, on entering Cooling      main.arche:45    1.002 s  (10 ms before)
 ← ctl Cooling             Idle → Cooling on READING [celsius > 28.0]  main.arche:49    1.002 s
                             celsius = 29.5
 ← READING celsius: 29.5   air.air → ctl.air, air.sample               main.arche:32    1.000 s  (2 ms before)
 ← air.sample              thread sample, every 100 ms                 main.arche:92    1.000 s
 ← air.temperature = 29.5  set by the test (it was 25)                 main.arche:101   1.000 s
took 12 ms from the reading at 1.000 s
✓ REQ-FAN: from ctl entering Cooling to fan Running took 10 ms; it allows 1 s

Read it from the top. The fan started because a FAN_CMD came. The thermostat sent that command on entering Cooling. It entered Cooling because a reading of 29.5 °C made [celsius > 28.0] true. The sensor's thread sent that reading, and the test had just warmed the air.

The last lines say how long it took from the reading. They also check each requirement that limits that delay: an EARS sentence with within, or a within in the text of a requirement that a part of the chain satisfies.

You can name an event in several ways:

You write It means
"fan Running" the fan entering Running (the first time)
"ctl sends FAN_CMD #2" the second FAN_CMD that ctl sent
"ctl.fan last" the last message out of ctl's fan port
"fan receives FAN_CMD" a FAN_CMD arriving at the fan
"air.temperature at 1s" the variable's change at 1 s, or the first one after it

Why did that never happen?#

archec why-not takes a transition, a state or a message that never happened. It says which of three things stopped it:

$ archec why-not main.arche --test TC-HOT "Cooling -> Idle"
ctl: Cooling -> Idle on READING [celsius < 26.0]  main.arche:50
  the guard [celsius < 26.0] was never true while ctl was in Cooling: the lowest celsius was 27 °C (29 READING checked)
  • The guard was never true. It says how close the values came: the lowest value for a <, the highest for a >.
  • The trigger never came while the part was in the right state. It says who should have sent it, and whether they ever did. It also catches a port that is linked to nothing.
  • The source state was never active. It then asks the same question about each way into that state.
$ archec why-not main.arche --test TC-HOT "Cooling -> Service"
ctl: Cooling -> Service on SERVICE [on]  main.arche:55
  SERVICE never came to ctl while it was in Cooling (1.002 s to 4.000 s): nothing sends SERVICE to it — ctl.service is linked to nothing

Which run#

Three kinds of run can be explained. Each one is explained the same way.

Option The run
--test TC-HOT a test case, run on archec's own simulator (as archec sim --test)
--trace board.trace a trace of the real system, written by archec gen --target c --trace or --target embassy --trace: the text lines or the Chrome JSON
--trace sim.json a trace of archec sim --json
--for 10s a plain run of the simulator, for that long (10 s when nothing is given)

A simulated run records what caused each event, so its answers are exact. A trace of the board only has what the firmware wrote: the states entered, the messages sent and received, and the threads' activations. There, archec finds each cause from the model: the latest message or state in the trace that the model says could have caused the next step. The answer says so in a note.

The answer on the board looks just like the one above:

$ archec why main.arche --trace board.trace "fan Running"
fan Running               Stopped → Running on FAN_CMD [on]           main.arche:65    210.212 ms
 ← FAN_CMD on: true       received by fan                                              210.212 ms
 ← FAN_CMD                sent by ctl, on entering Cooling            main.arche:45    200.003 ms  (10.21 ms before)
 ← ctl Cooling            Idle → Cooling on READING [celsius > 28.0]  main.arche:49    200.002 ms
                            celsius = 28.4
 ← READING celsius: 28.4  received by ctl                                              200.002 ms
 ← READING                sent by air, air.sample                     main.arche:32    200.000 ms
 ← air.sample             thread sample, every 100 ms                 main.arche:92    200.000 ms
took 10.21 ms from the reading at 200.000 ms

A trace's times start at its first record.

The values in a trace#

A guard reads values, and a state change alone does not show them. So with --trace, the generated C and Rust also write a value record. They write one for each field of a received message that a guard of the receiving part reads:

arche-trace 5200002000 recv READING 4
arche-trace 5200002000 value ctl.READING.celsius 28400

The value is in thousandths: 28400 is 28.4. A negative value is written as the unsigned bits of a signed 32-bit number. Values past ±2 147 483 are cut there.

Without value records, archec why-not says it cannot tell whether a guard held. It also says so when a guard reads a part's own variable, which a trace does not carry.

When the values say a guard was false and the transition was taken anyway, archec why says that the code's guard is not the model's. For example, a guard left as a TODO in a USER CODE region of the Embassy crate returns true.

In VS Code#

  • In the simulation debugger, stopped at an event, press Why? in the debug toolbar. It is also in the call stack's menu. The chain opens as a list, and picking a line opens it in the model.
  • Arche: Why Did This Happen? without the debugger asks for a run (a test case or a trace file), then an event of its timeline.
  • Arche: Why Did This Not Happen? works on the transition under the cursor, or one you pick. It is also in the editor's context menu.

See editor.md for the debugger itself.

Limits#

  • A trace from the board does not say which part sent a message, only its name. archec takes the part whose model sends it. When two parts send the same message, a link may name neither.
  • On a trace, a cause is the latest event that could have caused the next step. Two messages of the same name close together can be mixed up.
  • Values come only from the fields of a received message that a guard reads. A guard on a part's variable, or on a call such as air.temperature(), cannot be explained from a board's trace. In the simulator, all three are recorded.
  • Only ```arche bodies are read for where a message is sent. A send written in Python or TypeScript is not found, and that link has no model line.
  • A time is given from the start of the run, not as a time of day.
  • --test runs on archec's own simulator, not on Arche's (archec test). The simulation debugger's runs come from Arche's and are explained from their messages and states.
  • An expect … within is shown when the test decided it, at the start of the 10 ms period it was checked in. That can be a little before the event it waited for.