====== Design of Waveform Transition Graph for basic buck controller ======

In this tutorial we are going to learn how to design a [[:overview:wtg|Waveform Transition Graph (WTG)]] by means of an example: the buck controller. You can find a description of the buck controller in [[tutorial:design:basic_buck:start| Design of basic buck controller]]. Check the first section and try to understand its behaviour before continuing.

===== Modelling =====

The buck controller presents three distinct scenarios that need to be modeled:
  * **no ZC** -- UV happens without ZC;
  * **late ZC** -- UV is followed by ZC;
  * **early ZC** -- UV happens after ZC.

WTGs use a structured way of modelling different modes or scenarios, by defining a waveform, or set of waveforms, for each scenario. Our first step is then going to be defining the general structure by creating one initial state and three empty waveforms, named after each scenario. Don't forget connecting the initial state to the waveforms, but for now don't add connections from the waveforms.

++++ Detailed instructions|
  * Place a state and double click on it to set it as initial.
  * Create three waveforms.
  * Rename them by clicking once on them and editing the name field in the property editor:
      * //no_zc//
      * //late_zc//
      * //early_zc//
  * Add an connection from the initial state to each of the waveforms.
++++

The resulting WTG is shown in the following figure. 

{{ wtg_buck-basic_structure.svg?45%,nolink }}


Adding a connection between the waveforms and the initial state would be a correct step. In that design, every scenario would play out and return to the initial state, where it would wait for ''<color red>uv</color>'' or ''<color red>zc</color>'' to be triggered. But a careful observation of the behaviour of the buck controller tells us that every scenario has an identical behaviour after ''<color red>uv</color>'' is triggered for low. We can model this as a different, common scenario, in which signal ''<color red>oc</color>'' is handled and the PMOS and NMOS transistors are returned to their initial states.

Add a new state and a new waveform, named //oc_handling//. Connect the previous waveforms to the new state and the new state to the waveform //oc_handling//. Finally, connect the new waveform to the initial state.

++++ Detailed instructions|
  * Place a new state.
  * Create a new waveform and rename it to //oc_handling//.
  * Add a connection from each of the previous waveforms to the new state.
  * Connect the new state to the new waveform.
  * Finally, add a connection from the last waveform to the initial state. 
++++

You can see the resulting model in the following figure.

{{ wtg_buck-basic_structure2.svg?45%,nolink }}


Now that the basic structure is defined, you can model the behaviour of every scenario. Double click on the first scenario, //no_zc//, and draw its waveform. Remember stopping after the falling edge of ''<color red>uv</color>'', since this will be modeled in a different waveform.

++++ Detailed instructions|
  * This scenario uses the signals ''<color red>uv</color>'', ''<color blue>gn</color>'', ''<color red>gn_ack</color>'', ''<color blue>gp</color>'' and ''<color red>gp_ack</color>''. Click on the signal tool:
     * Hold <key>Shift</key> while clicking in the waveform to create an input signal. Rename it to ''<color red>uv</color>''.
     * Click in the waveform to create an output signal and rename it to ''<color blue>gn</color>''.
     * Create the rest of the signals, holding <key>Shift</key> for inputs, and rename them to ''<color red>gn_ack</color>'', ''<color blue>gp</color>'' and ''<color red>gp_ack</color>''.
  * Initially the NMOS transistor is ON: 
     * In the property editor, set the initial state for ''<color blue>gn</color>'' and ''<color red>gn_ack</color>'' to ''high''.
  * When UV is detected the NMOS transistor needs to be switched OFF: 
     * Double click on signal ''<color red>uv</color>'' to add a rising transition.
     * Double click on signal  ''<color blue>gn</color>'' to add a falling transition.
     * Connect the transition of ''<color red>uv</color>'' to the transition of ''<color blue>gn</color>''.
  * Wait for indication of NMOS transistor being OFF: 
     * Double click on ''<color red>gn_ack</color>'' to create a falling transition.
     * Connect the transition of ''<color blue>gn</color>'' to the transition of ''<color red>gn_ack</color>''.
  * When the OFF state of NMOS is confirmed the PMOS transistor can be switched ON to charge the buck: 
     * Double click on ''<color blue>gp</color>'' and on ''<color red>gn_ack</color>'' to create two rising transitions.
     * Connect the transition of ''<color red>gn_ack</color>'' to the transition of ''<color blue>gp</color>'' and the transition of ''<color blue>gp</color>'' to the transition of ''<color red>gp_ack</color>''. If you hold <key>Ctrl</key> while adding connections, the destination transition will become the source transition for the next connection. 
  * Eventually the buck will saturate leading to reset of UV and OC conditions. Since the OC condition will be handled in a separate waveform, we can finish with the reset of UV:
     * Double click on signal ''<color red>uv</color>'' to add a falling transition.
     * Connect the transition of ''<color red>gp_ack</color>'' to the last transition of ''<color red>uv</color>''.
++++

The WTG now should look similar to this.

{{ wtg_buck-no_zc.svg?45%,nolink }}

We can complete the remaining scenarios in any order, but lets first work on //oc_handling//. In the previous waveform, signals had to be created with the default name and then renamed. Now that those signals are in the WTG, we can reuse them by just checking a box in the property editor. Furthermore, since we have already defined the structure of the WTG, the initial state will be automatically set (see [[help:wtg:start#initial_state_inference| Initial state inference]]).

++++ Detailed instructions|
  * This waveform uses the signals ''<color red>oc</color>'', ''<color blue>gp</color>'', ''<color red>gp_ack</color>'', ''<color blue>gn</color>'' and ''<color red>gn_ack</color>'':
     * Use the signal tool to create a new signal. Remember to hold <key>Shift</key> to make it an input. Rename it to ''<color red>oc</color>''.
     * Use the property editor to declare the rest of the signals by clicking in their //declared// checkbox.
  * OC starts the reset cycle by prompting the PMOS transistor to switch to OFF:
     * Double click on ''<color red>oc</color>'' to add a rising transition.
     * Double click on ''<color blue>gp</color>'' and ''<color red>gp_ack</color>'' to add falling transitions.
     * Connect the transition of ''<color red>oc</color>'' to the transition of ''<color blue>gp</color>'' and the transition of ''<color blue>gp</color>'' to the transition of ''<color red>gp_ack</color>''.
  * After the OFF state of the PMOS transistor is confirmed the NMOS transistor is switched ON state: 
     * Double click on ''<color blue>gn</color>'' and ''<color red>gn_ack</color>'' to add rising transitions.
     * Connect the transition of ''<color red>gp_ack</color>'' to the transition of ''<color blue>gn</color>'' and the transition of ''<color blue>gn</color>'' to the transition of ''<color red>gn_ack</color>''.
  * This leads to the release of OC and brings the controller to the initial state: 
     * Double click on ''<color red>oc</color>'' to add a falling transition.
     * Connect the transition of ''<color red>gn_ack</color>'' to the transition of ''<color red>oc</color>''.
++++


Check that your WTG looks like the following figure.

{{ wtg_buck-oc_handling.svg?45%,nolink }}

You can now work on the remaining scenarios in any order. Thanks to the last step, the initial states will be inferred, and most of the signals, except for ''<color red>zc</color>'', can be declared with one click. 

The //late ZC// scenario is very similar to //no ZC//. The switching of ZC happens concurrently with that of the NMOS and PMOS transistors. Complete this scenario.

++++ Detailed instructions|
  * Create all the transitions and signals form the //no ZC// scenario .
  * Use the signal tool to create a new input signal and rename it to ''<color red>zc</color>''.
  * Double click on signal ''<color red>zc</color>'' twice, to create a rising and a falling transition.
  * Connect the raising transition for signal ''<color red>uv</color>'' with the raising transition for signal ''<color red>zc</color>''.
  * Connect the falling transition for signal ''<color red>zc</color>'' with the failling transition for signal ''<color red>uv</color>''.
++++

The WTG should now look like this.

{{ wtg_buck-late_zc.svg?45%,nolink }}

Finally, only the scenario for early arrival of ZC remains. In this case, ZC arrives before UV and the NMOS transistor has to be switched OFF without waiting for UV. However, switching the PMOS transistor ON is still delayed until UV condition.

++++ Detailed instructions|
  * This scenario uses all the signals except for ''<color red>oc</color>'':
     * Use the property panel to declare ''<color red>zc</color>'', ''<color red>uv</color>'', ''<color blue>gn</color>'', ''<color red>gn_ack</color>'', ''<color blue>gp</color>'' and ''<color red>gp_ack</color>''.
  * An early arrival of ZC prompts this scenario. This triggers the NMOS and UV:
     * Double click on ''<color red>zc</color>'' and ''<color red>uv</color>'' to add rising transitions.
     * Double click on ''<color blue>gn</color>'' and ''<color red>gn_ack</color>'' to add falling transitions.
     * Connect the transition of ''<color red>zc</color>'' to the transitions of ''<color blue>gn</color>'' and ''<color red>uv</color>''.
     * Connect the transition of ''<color blue>gn</color>'' to the transition of ''<color red>gn_ack</color>''.
  * The PMOS transistor waits for UV and for the NMOS transistor before switching to ON:
     * Double click on ''<color blue>gp</color>'' to add a rising transition.
     * Connect the transitions of ''<color red>uv</color>'' and ''<color red>gn_ack</color>'' to the transition of ''<color blue>gp</color>''.
  * The switching of the PMOS transistor has to be acknowledged. After that and after ZC is disabled, UV can be reseted:
     * Double click on ''<color red>gp_ack</color>'' to add a rising transition.
     * Double click on ''<color red>zc</color>'' and ''<color red>uv</color>'' to add falling transitions.
     * Connect the transition of ''<color blue>gp</color>'' to the transition of ''<color red>gp_ack</color>'' and to the fall transition of ''<color red>zc</color>''.
     * Connect the transition of ''<color red>gp_ack</color>'' and the fall transition of ''<color red>zc</color>'' to the fall transition of ''<color red>uv</color>''.
++++

The finished WTG should be similar to the following figure.

{{ wtg_buck-early_zc.svg?45%,nolink }}

===== Simplification =====
The WTG that you designed is already complete and valid, but WTG models allow simplifying some behaviours. Consider the scenarios //no_zc// and //late_zc//. They only differ in the triggers for signal ''<color red>zc</color>''. Yet this signal is triggered by an input signals and only triggers another trigger signal. This tells us that ''<color red>zc</color>'' has no bearing in the output signals that we have to generate. In fact, the only reason we even have these two different scenarios is because the resulting circuit should expect ''<color red>zc</color>'' to rise and fall... and ignore it. WTG allows us to explicitly model that a certain signal should be ignored between specific input transitions. 

Rename the waveform //late_zc// into //late_or_not_zc// and edit it. Click on the raise transition for ''<color red>zc</color>'' and set the direction to ''unstable''. This specifies that ''<color red>zc</color>'' might be triggered zero or more times and it should be ignored. The last transition of ''<color red>zc</color>'', and the connection to ''<color red>uv</color>'', guarantees that ''<color red>zc</color>'' will be set at ''low'' before the falling transition of ''<color red>uv</color>''. With this change, //late_or_not_zc// already models the behaviour of //no_zc//, so delete the waveform //no_zc//.

The final and simplified WTG should be similar to the following figure.

{{ wtg_buck-simplified.svg?45%,nolink }}
===== Validation =====

This section discusses two ways in which you can validate that your design is correct. In particular, verification that the model is correctly formed and simulation to ensure that it works as expected.

==== Verification ====
Workcraft includes three verification tools that check different properties of a WTG that should be satisfied by any model. You can access them in the //Verification// menu.

=== Input properness ===
An internal signal cannot trigger an input. This restriction is important when the model we design is going to be implemented as a circuit, because internal signals are not observed by the environment. As such, an input signal cannot react (be triggered) by an internal signal. Note that this restriction cannot be violated in this example, since no internal signals are used.

Nonetheless, this restriction can be violated in WTGs in two ways:
  * A connection between a transition of an internal signal and a transition of an input signal.
  * When there is an internal signal transition without any connection to other transitions in a waveform. If this waveform is connected to a state, that at the same time is connected to a waveform in which an input signal can be fired first. In this case, the internal signal is effectively triggering this input.

=== Reachability ===
Checks that there are no states, waveforms or transitions that cannot be reached by the initial state. The existence of unreachable elements often indicates a mistake in the design.

=== Soundness and consistency ===
Checks that a WTG is consistent and has a sound structure. 

Consistency refers to the states of signals having correct values at any point. In WTGs, this is often violated in the initial states of signals. For example, when the initial state of a signal does not match the state at the end of the previous waveform.

Soundness checks ensure that the structure of the WTG is correctly form. It has numerous checks, such as making sure the initial state is defined or that there are no unconnected transitions. 

==== Simulation ====
You can use the simulation tool {{help:core:editor_tools-simulate.png?nolink|[M] Simulate}} to ensure the WTG performs as you expect. At any moment, transitions that can be fired are highlighted in orange. Clicking on them will fire them and show the which transitions can be fired afterwards. You can compare the simulation traces to the buck controller specification.


===== Conversion into STG =====

A correctly formed WTG (one that passes the Soundness checks from the //Verification// menu) can be converted into an STG. This allows you to perform more advanced verification checks that are available for STGs. More importantly, this also allows you to synthesize the circuit derived from the WTG (see [[help:stg:start#synthesis| Synthesis of STG]]).

In order to convert a WTG into a STG, go to the //Conversion// menu and click //Signal Transition Graph//. This will prompt a soundness check and, if satisfied, a new window will open with the derived STG.

===== Solutions =====

Download the final version of the WTG specification that was captured throughout the tutorial here:

<wrap download>{{wtg_buck.work|}}</wrap>