Channel Commands - HACKT PRSIM Manual
Description: HACKT PRSIM Manual

Next: Info Commands, Previous: Simulation Commands, Up: Commands

### 3.4 `channel` Commands

The simulator currently provides some limited features for interacting with channels and environments at run-time. The 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 `channels` commands are prefixed with `channel-`.

— Command: channel name type bundle rails

> Registers a named channel (with constituents) in a separate namespace in the simulator, typically used to drive or log the environment. The name of the channel should match that of an instance (process or channel) in the source file.

> - name is the name of the new channel in the simulator's namespace
> - type is a regular expression of the form `[ae]?[nv]?:[01]?`, where
>   - `a` means active-high acknowledge
>   - `e` means active-low acknowledge (a.k.a. enable)
>   - `n` means active-low validity (a.k.a. neutrality)
>   - `v` means active-high validity. These are also the names of the channel signals.
>   - `[01]` is the initial value of the acknowledge during reset, which is only relevant to channel sinks.
> - bundle is the name of the data bundle (rail group) of the channel in the form `[name]:size`, where size is the number of rail bundles (M in Mx1ofN). If there are no bundles, then leave the name blank, i.e. just write `:0` If there is only one bundle (1x1ofN), use size 0 to indicate that named bundle is not an array.
> - rails (`[~]rname:radix`) is the name and size of each bundle's data rails, rname is the name of the data rail of the channel. radix is the number of data rails per bundle (N in Mx1ofN). Use radix 0 to indicate that rail is not an array (1of1). If rails is prefixed with a `~`, then the data rails will be interpreted as active low.
> For example, `channel e:0 :0 d:4` is a conventional e1of4 channel with active-high data rails `d[0..3]`, and an active-low acknowledge (enable) reset to 0, no bundles.

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 `.e` or `.a` (or `.v` or `.n`) and `.d[i]` (or however the rails are named) to the end of the channel's name. The data rails' name may be prefixed with `~` to indicate that the rails are active-low. The following are examples of channel commands.

         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
         channel J e:0 :0 ~d:2
         channel H : :0 ~d:2

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

A channel can be declared without an acknowledge by omitting the `a` or `e` desginator and the initial value after the colon, as in examples H and K, 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.)

— Command: channel-show chan

> Print the current configuration and state of channel chan. This also shows the sequence of values associated with sources and expectations with sequence position, if applicable. Looping values are indicated with `*`. This also shows the origin of the value sequence and the name of the current log file to which values are dumped, if enabled.

— Command: channel-show-all

> Print the current configuration for all registered channels.

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

— Command: channel-watch chan

> Report value of data rails when channel chan has valid data. Data validity is only determined by the state of the data rails, and not the acknowledge signal. An unstable channel (that can transiently take valid states) will report every transient value. Channels in the stopped state will still be reported, make sure that they are resumed by channel-release.

— Command: channel-unwatch chan

> Remove channel chan from watch list.

— Command: channel-watchall

> Report values on all channels when data rails become valid.

— Command: channel-unwatchall

> Silence value-reporting on all channels.

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

— Command: channel-log chan file

> Record all valid data values on channel chan to output file. File stream automatically closes upon end of simulation, or with an explicit channel-close. Channels in the stopped state will NOT be reported, make sure that they are resumed by channel-release.

— Command: channel-close chan

> Close any output file streams associated with channel chan. This flush the current log file, closes the file, and stops logging. This does not affect source nor expect value sequences since those files are read in their entirety upon configuration.

— Command: channel-close-all

> Apply channel-close to all channels.

— Command: channel-expect-file chan file
— Command: channel-expect chan file

> Compare data values seen on channel chan against a sequence of values from file. Error out as soon as there is a value mismatch. In this variant, once value sequence is exhausted, no more comparisons are done, and channel values go unchecked. See also channel-expect-file-loop.

— Command: channel-expect-file-loop chan file
— Command: channel-expect-loop chan file

> Like channel-expect-file but repeats value sequence infintely.

— Command: channel-expect-args chan values...

> Tells a channel chan to expect values on data rails. Stops checking values after last value is used.

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.

— Command: channel-ignore chan

> Stop logging and checking expected values on channel chan. This can be useful for momentarily ignoring a sequence of values. An ignored channel will continue to respond to changes until it is stopped, by a stop command.

— Command: channel-heed chan

> Take channel chan out of the ignored state.

— Command: channel-ignore-all

> Stop logging and checking all channel values.

— Command: channel-heed-all

> Continue logging and checking all channel values.

Value files: The files referenced by channel-expect and channel-source may contain `#` 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 `X`, which is interpreted as don't care for expected values, and 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.

— Command: channel-source-file chan file
— Command: channel-source chan file

> Configure channel chan to source values from the environment. Values are take from file and read into an internal array. Once values are exhausted, the channel stops sourcing. To repeat values, use channel-source-file-loop. A channel configured as a source should have the production rules drive the acknowledge signal and no other rules driving the data rails (otherwise the simulator will issue a warning).

— Command: channel-source-file-loop chan file
— Command: channel-source-loop chan file

> Like channel-source-file except that value sequence is repeated infintely.

— Command: channel-source-args chan [values...]

> Source values on channel chan using the values passed on the command. Sourcing stops after last value is used. Legal values are integers and 'X' for random. If no values are given, then the channel will not source any values, but it will still reset the data rails to neutral state.

— Command: channel-rsource chan

> Configures a channel to source random data values. This is useful for tests that do not depend on data values.

— Command: channel-sink chan

> Configure a channel to consume all data values (infinitely). A sink-configured channel should have data rails driven by the production rules and nothing else driving the acknowledge signal (simulator will issue warning otherwise). A sink-configured channel can also log and expect values. Mmmmm... tokens! Nom-nom-nom...

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.

— Command: channel-assert-value-queue chan val

> For channels that are sourcing or expecting values, assert the state of the channel value array being used. val is 1 to assert that values are still remaining, 0 to assert that values are empty (channel is finished). Looped sources and expects will never be empty. This is useful for checking that finite sequence tests have actually completed. Exits fatally if assertion fails.

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

— Command: channel-timing chan [mode [args]]

> With no additional arguments, report the timing mode of channel chan. Timing only applies to channels that are configured as a source or a sink. Modes:

> - `global` : use the global simulation-wide timing policy.
> - `after [delay]` : use a fixed delay.
> - `random [max]` : if max is specified, use a uniform distribution delay bounded by max, otherwise return an exponential variate delay.

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 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 released. Channels may be individually stopped or released, and reset-all and release-all are also provided for convenience.

— Command: channel-reset chan

> Force a environment-configured channel into its reset state, i.e. a source will reset its data rails to neutral (ignoring state of acknowledge), and a sink will set the acknowledge to the initial value (from configuration) regardless of the data rails (and validity). IMPORTANT: This command also freezes a channel in the stopped state, like channel-stop and will not respond to signal changes until resumed by channel-release.

— Command: channel-reset-all

> Force all source- or sink- configured channels into their reset state, as done by channel-reset. This is typically done at the same time as global reset initalization.

— Command: channel-stop chan

> Freeze a source- or sink-configured channel so that it stops responding to signal transitions from the circuit. Stopped channels will not log data nor assert expected values because they may be in a transient state. A channel can be unfrozen by channel-release.

— Command: channel-stop-all

> Applies channel-stop to all channels.

— Command: channel-release chan

> Releases a source- or sink-configured channel from the stopped state, so that it begins to respond to circuit signal transitions (and continue logging and expecting). Upon resuming, the channel evaluates its inputs and adds events to the event queue as deemed appropriate.

— Command: channel-release-all

> Applies channel-release to all channels. This is typically used at the end of a reset initialization sequence as the circuit is brought out of the reset state.

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

Re-initialization: The initialize and reset also affect the state of channels. 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.) reset will completely wipe all registered channels, as if the simulator had just started up.