@c "hacprsim/commands.texi"
@c $Id: commands.texi,v 1.20 2009/02/11 02:35:03 fang Exp $

@node Commands
@chapter Commands

This chapter documents the various commands available in
the interpreter.  
Commands are organized into categories.  

@strong{FYI:} the command documentation has been extracted from 
source file @file{sim/prsim/Command-prsim.cc}.  

@menu
* Built-in Commands::
* General Commands::
* Simulation Commands::
* Channel Commands::
* Info Commands::
* View Commands::
* Modes Commands::
* Tracing Commands::
* Debug Commands::
@end menu

@c ----------------------------------------------------------------------------
@node Built-in Commands
@section Built-in Commands

The following commands are listed in the @t{builtin} category.  

@include cmd/help.texi
@include cmd/echo.texi
@include cmd/comment.texi
@include cmd/exit.texi
@include cmd/abort.texi
@include cmd/repeat.texi
@include cmd/interpret.texi

The following command is useful for showing each executed command.

@include cmd/echo-commands.texi

The following commands pertain to command aliases.

@include cmd/alias.texi
@include cmd/unalias.texi
@include cmd/unaliasall.texi
@include cmd/aliases.texi

Shell commands may be executed by prefixing a line with '!'.  
For example, @samp{!whoami}.  

@strong{New}:
Block comments are pseudo C-style, using @t{/*} and @t{*/} to enclose comments.
It is recommended to start use block-comment delimiters on their own lines
to avoid confusion.  
The line parser is very crude.
Nested comments are supported.  
Files with unterminated comments will be reported as errors.  
@t{#}-comments are allowed within block comments.  

@c ----------------------------------------------------------------------------
@node General Commands
@section General Commands

The following commands are listed in the @t{general} category.  

@include cmd/source.texi
@include cmd/addpath.texi
@include cmd/paths.texi

@c ----------------------------------------------------------------------------
@node Simulation Commands
@section @t{simulation} Commands

@include cmd/initialize.texi
@include cmd/reset.texi

Running the simulation.  

@include cmd/step.texi
@include cmd/step-event.texi
@include cmd/advance.texi
@include cmd/cycle.texi

Coercively setting values.

@include cmd/set.texi
@include cmd/setr.texi
@include cmd/setf.texi
@include cmd/setrf.texi
@include cmd/unset.texi
@include cmd/unsetall.texi

Breakpoints.  

@include cmd/breakpt.texi
@include cmd/breaks.texi
@include cmd/nobreakpt.texi
@include cmd/nobreakptall.texi

Rescheduling events.

@include cmd/reschedule.texi
@include cmd/execute.texi

@c ----------------------------------------------------------------------------
@node Channel Commands
@section @t{channel} Commands

The simulator currently provides some limited features for
interacting with channels and environments at run-time.  
The @i{channel} features allow a user to connect arbitrary 
sources and sinks to channels, as well as perform assertion checks
and value logging.  
For consistency, all @t{channels} commands are prefixed with 
@t{channel-}.  

@include cmd/channel.texi

The channel names used in the simulator must correspond to an
actual channel (or process) in the input description.  
(The name used for registration actually resides in the simulator's
own namespace, separate from the compiled circuits.)
Upon registering a channel name, the simulator locates all
relevant subnodes of the channel by appending @t{.e} or @t{.a}
(or @t{.v} or @t{.n})
and @t{.d[i]} (or however the rails are named) to the end of 
the channel's name.  The following are examples of @command{channel} commands.  

@example
channel A e:0 :0 d:2
channel B e:1 :0 d:2
channel C e:1 :0 r:2
channel D e:1 :0 d:0
channel E a:1 :0 r:4
channel F e:1 d:4 r:4
channel G ev:0 :0 d:2
channel H : :0 d:2
@end example

@noindent
Respectively the channel declarations are: 
(A) an @t{e1of2} channel with @t{.e} initially low (if coming 
from the environment), 
(B) an @t{e1of2} with @t{.e} initially high, 
(C) an @t{e1of2} with array data rails named @t{r}, 
(D) an @t{e1of2} with one non-array data rail @t{r}, 
(E) an @t{a1of4} with @t{.a} initially high, 
(F) an @t{e4x1of4} channel, 
(G) an @t{ev1of2} (enable-valid protocol), 
and (H) an acknowledgeless @t{1of2} channel (just data-rails).  

A channel can be declared without an acknowledge by omitting
the @t{a} or @t{e} desginator and the initial value after the colon, 
as in example H, above.  
Acknowledgeless channels cannot be used as sources or sinks, 
however, they can still be watched, logged, and checked against 
expected values.  
(Watching, logging, and checking values on channels does not
use the acknowledge signal of channels.)

The shared-valid protocols use a additional validity (or neutrality) signal
in the channel to perform the handshake.  
For example, the validity signal can be generated by the completion 
tree from the sender, and sent to the receiver so the receiver can reuse
the completion signal without recomputing it.  
Shared-validity channels operate slightly differently than other channels.
Data is considered valid when the validity is true, not necessarily when
the data rails are in a valid state.  
(Of course, in the cases of properly constructed and connected completion 
trees, the data will be valid.)
Thus, data is logged, printed, checked only when the validity signal 
becomes active, which is usually after the data rails are valid.  
(More on sourcing and sinking of shared-validity channels below.)

@include cmd/channel-show.texi
@include cmd/channel-show-all.texi

To control which channels should report values to the console, 
the simulator provides basic watch commands.  

@include cmd/channel-watch.texi
@include cmd/channel-unwatch.texi
@include cmd/channel-watchall.texi
@include cmd/channel-unwatchall.texi

Channel values can also be logged to a file or compared against
expected values.  

@include cmd/channel-log.texi
@include cmd/channel-close.texi
@include cmd/channel-close-all.texi
@include cmd/channel-expect.texi
@include cmd/channel-expect-loop.texi
@include cmd/channel-expect-args.texi

@noindent
It is legal to log and expect values on the same channel.  

The following commands can further control when channels
log or check values.  
Ignoring can be useful for masking out atypical phases of behavior
or turning off checking.  
Ignoring channels is independent of the stopped/released state 
of a channel. 

@include cmd/channel-ignore.texi
@include cmd/channel-heed.texi
@include cmd/channel-ignore-all.texi
@include cmd/channel-heed-all.texi

@b{Value files}: The files referenced by @command{channel-expect} and 
@command{channel-source} may contain @t{#} comments and blank lines, 
which are skipped.  
Only the first value on each line is used, so value sequences
should be newline-separated.
For now, the remained of each line is simply ignored, 
so you may use them for comments, but this may change in the future.  
The other legal value in the file is @t{X}, which is interpreted as
@i{don't care} for expected values, and @i{random} for source values.  

Channels can be configured to operate as environments
when they are not already connected to inputs or outputs.  
The only conflicting (illegal) configuration combination is that 
a channel cannot act as source while expecting values.  
(Why would you want to do that anyways?)
Channels configured as sources or sinks can be controlled through
the following commands.  

@include cmd/channel-source.texi
@include cmd/channel-source-loop.texi
@include cmd/channel-source-args.texi
@include cmd/channel-rsource.texi
@include cmd/channel-sink.texi

@noindent
It is legal to source and sink on the same channel.  

It is often useful to query the status of a channel
that is sourcing or expecting values.

@include cmd/channel-assert-value-queue.texi

Channel sources and sinks can be configured to respond with 
a different timing from the global policy.

@include cmd/channel-timing.texi

@b{Shared-validity environments}:
Shared-validity sources operate slightly differently from the
other standard channels.  
Sources of such channels will drive both the data-rails and the validity 
signal.  The validity-signal will automatically react when the data-rails
enter a valid state, thus it is treated as both an input and output
to the source.  However, the validity signal should not be driven
by any other circuit, i.e. it should have no fanin.  
Shared-validity sinks do not respond to data-rails at all, they only respond
to the validity signal with the acknowledge.  
Thus it is the responsibility of the circuit under test to provide
the validity signal.  

After configuring channels as sourcing or sinking environments, 
there is one more additional step to enabling them.  
Channels startup in the @emph{stopped} state, in which they
do no respond to any changes in the circuit, data-rails or acknowledges.
Resetting a channel forces a channel into its initial state.
For sources, the data rails are always neutral.
For sinks, the acknowledge is in the initial state that was
specified when the channel was declared.
A channel will begin to respond to the circuit only after 
it has been @emph{released}.
Channels may be individually stopped or released, 
and reset-all and release-all are also provided for convenience.  

@include cmd/channel-reset.texi
@include cmd/channel-reset-all.texi
@include cmd/channel-stop.texi
@include cmd/channel-stop-all.texi
@include cmd/channel-release.texi
@include cmd/channel-release-all.texi

@b{Timing}: delays are given some default value, 
except in random timing mode, where delays are randomized.  
TODO: configure after delays on sources and sinks.

@b{Re-initialization}:
The @command{initialize} and @command{reset} also affect the state
of channels.  
@command{initialize} retains the configuration (source, sink, watch, expect)
of all channels, however, the data rail tracking is reset to
account for all nodes being set to X.  
All output log streams are closed.  
Value sequences for sourcing and expecting are retained, but the 
position index is reset to 0, the beginning.  
(Rationale: it is uncommon to start at different offsets in
the value sequences.)
@command{reset} will completely wipe all registered channels, 
as if the simulator had just started up.  

@c ----------------------------------------------------------------------------
@node Info Commands
@section @t{info} Commands

The first subset of commands give information about the properties of the 
simulated production rules and contain no stateful information.  

@include cmd/attributes.texi
@include cmd/fanin.texi
@include cmd/fanin-get.texi
@include cmd/fanout.texi
@include cmd/fanout-get.texi
@include cmd/rules.texi
@include cmd/allrules.texi
@include cmd/rings-mk.texi
@include cmd/allrings-mk.texi
@include cmd/rings-chk.texi
@include cmd/allrings-chk.texi
@include cmd/what.texi
@include cmd/who.texi
@include cmd/ls.texi

The following commands give information about the state of the 
simulator and the simulated production rules.  

@include cmd/get.texi
@include cmd/getall.texi
@include cmd/assert.texi
@include cmd/assertn.texi
@include cmd/assert-pending.texi
@include cmd/assertn-pending.texi
@include cmd/queue.texi
@include cmd/assert-queue.texi
@include cmd/assertn-queue.texi
@include cmd/check-invariants.texi
@include cmd/backtrace.texi
@include cmd/why-x.texi
@include cmd/why.texi
@include cmd/why-not.texi
@include cmd/status.texi
@include cmd/time.texi
@include cmd/unknown-inputs.texi
@include cmd/unknown-inputs-fanout.texi
@include cmd/unknown-outputs.texi

@c ----------------------------------------------------------------------------
@node View Commands
@section @t{view} Commands

View commands affect what is displayed while the simulation is running.  

@include cmd/confirm.texi
@include cmd/watch.texi
@include cmd/unwatch.texi
@include cmd/watches.texi
@include cmd/watchall.texi
@include cmd/cause.texi
@include cmd/tcounts.texi
@include cmd/zerotcounts.texi
@include cmd/watch-queue.texi
@include cmd/watchall-queue.texi

@c ----------------------------------------------------------------------------
@node Modes Commands
@section @t{modes} Commands

This section lists commands that affect the execution of the simulation.  

@include cmd/checkexcl.texi
@include cmd/eval-order.texi

Timing mode.

@include cmd/timing.texi
@include cmd/random.texi
@include cmd/norandom.texi
@include cmd/seed48.texi

The simulator now supports @emph{weak rules} which can drive un-pulled nodes
but always yield to normal rules. 
Weak rules are marked with the @code{[weak=1]} production rule attribute.  
The use of weak-rules can be globally enabled or disabled.  

@include cmd/weak-rules.texi

@include cmd/diagnostics.texi
@include cmd/unstable.texi
@include cmd/weak-unstable.texi
@include cmd/interference.texi
@include cmd/weak-interference.texi
@include cmd/invariant-fail.texi
@include cmd/invariant-unknown.texi
@include cmd/assert-fail.texi
@include cmd/channel-expect-fail.texi
@include cmd/checkexcl-fail.texi
@include cmd/mode.texi

Two additional commands control the behavior of unstable rules.  
These are particularly useful for simulating circuits that expect to
glitch, such as synchronous (clocked) circuits.  

@include cmd/unstable-unknown.texi
@include cmd/unstable-dequeue.texi

@c ----------------------------------------------------------------------------
@node Tracing Commands
@section @t{tracing} Commands
@cindex checkpoint
@cindex trace file

Checkpointing is useful for saving the state of the simulator, 
which allows one to interrupt and resume long simulations, 
and also examine points of failure in detail.  

@include cmd/save.texi
@include cmd/load.texi
@include cmd/autosave.texi

The simulator supports trace file recording.
Unlike checkpoints, trace files contain information for 
the entire history of execution, not just the state at one point in time.  

@include cmd/trace.texi
@include cmd/trace-file.texi
@include cmd/trace-close.texi
@include cmd/trace-flush-notify.texi
@include cmd/trace-flush-interval.texi
@include cmd/trace-dump.texi

@c ----------------------------------------------------------------------------
@node Debug Commands
@section @t{debug} Commands

This section is reserved for commands that are only useful for debugging
the simulator.  
Some commands that end in @t{-debug} have already been mentioned
in the other sections.  

@include cmd/check-structure.texi
@include cmd/check-queue.texi
@include cmd/memstats.texi

