Games / Command flash cards / TCL for physical design / Errors and robustness

Errors and robustness

Each card shows a command to explain. A missed card returns later in the round and starts the schedule over. A card answered correctly moves up the schedule and next appears after 1, 3, 7, then 21 days. Keys 1 to 4 choose an option, h shows a hint, and Enter moves on. A hint keeps the card where it is on the schedule. An ordering card is answered by clicking its items in order, and one wrong click ends it. Time values are in nanoseconds. Progress is stored in this browser.

SourceTCL (Tool Command Language) is the scripting language every place-and-route and timing tool embeds, so the same skills carry between them. These cards follow the official Tcl manual pages, and each answer links to the page for that command. The examples are in the style the OpenROAD-flow-scripts scripts use, since that is Tcl written for a real flow. Reference: the Tcl manual (Tcl on GitHub).
All 6 cards in this section, with answers
  • if { [catch { read_spef $spef } err] } { puts "no parasitics: $err" }
    Runs the script and returns non-zero if it failed, with err set.

    Hint: Ask what catch returns, and what the second variable receives.

    The message goes into the named variable. catch returns 0 on success, so the if above reads as "if this failed". Wrapping a whole stage in catch hides real failures, so it is used narrowly, around the step whose failure is expected and handled. Tcl reference

  • if { ![file exists $lib] } { error "missing library: $lib" }
    Raises an error that stops the script unless a caller catches it.

    Hint: Ask what happens to the script after this line runs.

    Failing early with a clear message is far better than continuing on missing input and failing later in a stage that cannot explain why. Flow scripts use this to check their inputs before spending an hour on a run that cannot succeed. Tcl reference

  • if { [info exists ::env(CTS_ARGS)] } { set args $::env(CTS_ARGS) }
    Tests whether the variable is set, since reading an unset one is an error.

    Hint: Ask what reading an unset variable does.

    An optional setting is exactly this shape: use it if it exists, otherwise keep the default. info also answers questions about procedures, commands, and the call stack, which is how a script reports where it is. Tcl reference

  • try { set fh [open $f r] process $fh } finally { close $fh }
    The last block runs either way, error or not.

    Hint: Ask what runs if the middle line raises an error.

    The error still propagates; the block only guarantees the cleanup. There is also trap for handling a particular kind of error. In a tool script this is how a report file, a redirect, or a changed setting is restored whatever happens. Tcl reference

  • set code [catch { risky } result opts]
    The status, the result or message, and an error dictionary.

    Hint: Three things come back. Ask what the third one is for.

    The options hold the error code, the stack trace, and the return code, which is what a wrapper needs to re-raise an error faithfully with return -options $opts $result. Catching and reporting only the message throws away everything that makes the failure findable. Tcl reference

  • puts $::errorInfo
    The stack trace of the last error.

    Hint: Ask what more this holds than the message the error carried.

    A tool that prints only a one-line message leaves this behind, and it usually names the procedure and the line. A script that catches errors should record it, since the trace is gone as soon as the next error replaces it. Tcl reference