dinotrace.texi

\input texinfo.tex @c -*-texinfo-*-
@c %**start of header
@setfilename dinotrace
@settitle Dinotrace @value{VERSION}
@c Put everything in one index
@syncodeindex fn cp
@syncodeindex vr cp
@syncodeindex ky cp
@synindex pg cp
@syncodeindex tp cp
@c For double-sided printing, uncomment:
@c @setchapternewpage odd
@footnotestyle separate
@paragraphindent 2
@finalout
@c %**end of header

@c Before release, run C-u C-c C-u C-a (texinfo-all-menus-update with a
@c prefix arg).  This updates the node pointers, which texinfmt.el needs.
@c Also update the master menu, created with texinfo-master-menu

@set VERSION 9.4g
@set UPDATED March 2021
@set ID @value{VERSION}

@c DESCRIPTION: TexInfo: DOCUMENT source run through texinfo to produce documentation file
@c Use 'make dinotrace.txt' to produce the output file

@c All functions use these for searching ease
@macro dmenu{f}
@code{\f\}
@end macro

@macro widget{f}
@emph{\f\}
@end macro

@macro resource{f}
@code{\f\}
@end macro

@macro config{f}
@code{\f\}
@end macro

@macro switch{f}
@code{\f\}
@end macro

@macro prog{f}
@strong{\f\}
@end macro

@iftex
@finalout
@end iftex

@dircategory Signal waveform tracing tool
@direntry
* Dinotrace: (dinotrace).         Signal waveform tracing tool.
@end direntry

@ifinfo
This file documents the Dinotrace package for viewing signal waveforms.

Copyright 1998-2021 by Wilson Snyder. @email{wsnyder@@wsnyder.org}

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by the author.
@end ifinfo

@c @setchapternewpage odd   <- when manual gets bigger

@c @finalout
@titlepage
@title Dinotrace
@subtitle Signal Waveform Tracing
@subtitle for Dinotrace @value{VERSION}
@subtitle @value{UPDATED}
@author Wilson Snyder, @email{wsnyder@@wsnyder.org}

@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1998-2021 Wilson Snyder

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by the author.
@end titlepage

@node Top, Summary, (dir), (dir)
@cindex Introduction
@comment  node-name,  next,  previous,  up

@ifinfo
This file documents the Dinotrace package for signal waveform tracing.
This is edition @value{ID}, for Dinotrace version @value{VERSION}.

For the latest version, please see
@uref{https://www.veripool.org/dinotrace
}

Please feel free to send comments and suggestions to
@email{wsnyder@@wsnyder.org}.  If you install this
tool, please also send mail so that I can inform you of new
releases.

@end ifinfo

@c The master menu, created with texinfo-master-menu, goes here.

@menu
* Summary::                     
* History::                     
* Invoking Dinotrace::          
* Screen Description::          
* Keyboard Shortcuts::          
* Customization Files::         
* X Resources::                 
* Remote Control::              
* Dinotrace and Emacs::         
* File Formats::                
* Bugs::                        
* Index::                       
@end menu

@c ======================================================================

@node Summary, History, Top, Top
@chapter Summary

Dinotrace is a tool designed to aid in viewing Verilog Value Change
Dump, ASCII, Verilator, Tempest CCLI, COSMOS, Chango and Decsim Binary
simulation traces.  It is optimized for rapid design debugging using
X-Windows Mosaic.  A special interface allows signal information to be
annotated into source code using Emacs.

Please see the file @file{README.rst} in the distribution directory
for installation instructions.

@menu
* Copying::                     
@end menu

@node Copying,  , Summary, Summary
@section Copying
@cindex Copying, Dinotrace

Dinotrace is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 3, or (at your option) any
later version.

Dinotrace is distributed in the hope that it will be useful, but
@strong{without any warranty}; without even the implied warranty of
@strong{merchantability} or @strong{fitness for a particular purpose}.
See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along
with Dinotrace; see the file @file{COPYING}.  If not, write to the Free
Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
02111-1307, USA.

@c ======================================================================
@node History, Invoking Dinotrace, Summary, Top
@chapter History
@cindex History

Dinotrace was conceived in the early 1980's by Allen Gallotta at Digital
Equipment Corporation, who wrote the code and supported it through
version 4.2.  When created, it was the first graphical display tool for
the simulators being designed at Digital.

@pindex Verilator

In 1992 I joined Digital Semiconductor (a division of Digital Equipment
Corporation) and took over the support of Dinotrace.  I converted it
from Digital's X toolkit to Motif, added color, highlighting, searching,
and other features.  Several formats were added to Dinotrace to support
Verilator, our group's own Verilog to C translator, written by Paul
Wasson.  As the years went on, other groups started using the typical
industry standard Verilog simulators.  Although programs like vwaves
were available, they had some silly limitations.  Besides, we were
hooked on Dinotrace, so I added Verilog format, and Dinotrace lived on.

In 1998 I moved to Maker Communications, where I am currently employed.
Life, however, was sad and incomplete without Dinotrace.  Through the
efforts of existing DECies, mainly Duane Galbi, Digital graciously
agreed to release the source code.  (Subject to the code not being
resold, which is compatible with the GNU Public License.)

Still at Maker Communications, life is now complete as Dinotrace can be
shared by all.  This release is based upon the Digital version, with
many enhancements, most notably portability improvements and true 4-state
signal support.

@menu
* Contributors::                
@end menu

@node Contributors,  , History, History
@section Contributors
@cindex Contributors

Many people have provided ideas and other assistance with Dinotrace.

The major corporate sponsors of Dinotrace, by providing funds or
equipment grants, are Compaq Corporation, Digital Equipment Corporation,
Intel Corporation, and Maker Communications.

The people who have contributed code or other major functionality are
Allen Gallotta, Steve Hoover, Nathan Hughes, and Craig Ziegler.

Some of the people who have provided ideas and feedback for Dinotrace
include Edward Arthur, Sally Barry, Josh Belkin, Yifat Ben-Shachar,
Lee Bradshaw, Rachel Berman, Sass Berman, Mike Blake, Serge Bogdanov,
Ronen Boneh, Gregg Bouchard, Derek Bosch, Bill Bruce, Lauren Carlson,
Paul Chan, Ta-Chung Chang, David Chen, Dave Colson, Derrick Dacosta,
Erik Debriae, Paul Dormitzer, Duane Galbi, Allen Gallotta, Steve
Glaser, Mike Goulet, Larry Gust, Larry Herman, Dave Horan, Steve
Hoover, Nathan Hughes, Tom Hunt, Tracey Jones, Mike Kagen, Dan Katz,
Sol Katzman, Steve Kolecki, Steve Lang, Charlie Lind, Greg Loxtercamp,
Dan Lussier, Ben Marshall, Bob McNamara, Harunobu Miyashita, John
Murphy, Aki Niimura, Lisa Noack, Mitch Norcross, Michael Quadri,
Reinhard Schumann, Simcha, Jai Singh, Dean Sovie, Julie Staraitis,
Dominik Strasser, Bob Walsh, Paul Wasson, Steve Wilson, Bob Yodlowski,
and Craig Ziegler.

@c ======================================================================
@node Invoking Dinotrace, Screen Description, History, Top
@chapter Invoking Dinotrace
@cindex Invoking Dinotrace

Dinotrace accepts switches and filenames on the command line.  Any
filenames on the command line will be read in before Dinotrace gives
control to the user.

@pindex gunzip
@pindex uncompress
@cindex .gz
@cindex .Z
Dinotrace accepts switches with leading @code{-}, and everything else is
a trace filename.  Filenames are in standard Unix format, with a
optional @file{.gz} or @file{.Z} extension to indicate the trace should
be piped before opening through @prog{gunzip} or @prog{uncompress}
respectively.

These switches are supported, in addition to the standard @prog{X-11}
switches, like @switch{-display}.

@c @table @switch
@table @code
@item -verilog
@findex -verilog

Read following trace filenames using Verilog format.  This is the
default format.

@item -vpd
@findex -vpd

Read following trace filenames using Verilog Plus Dump format.

@item -decsim
@findex -decsim

Read following trace filenames using Decsim format.  If running on
a VMS system, Decsim Binary format is also supported.

@item -tempest
@findex -tempest
@cindex File Format, Switch

Read following trace filenames using Tempest/CCLI format.

@item -noconfig
@findex -noconfig
@findex Configuration Files, Disabling

Skip reading the standard global, user, and directory .dino files.
Do read any trace-specific .dino files.

@item -geometry @var{geometry}
@findex -geometry
@cindex Geometry, Switch

Specifies the window size and position in standard
X format (@var{width}X@var{height}+@var{xpos}+@var{ypos}).

@item -res @var{resolution}
@findex -res

Specify the trace resolution.

@end table

@c ======================================================================
@node Screen Description, Keyboard Shortcuts, Invoking Dinotrace, Top
@chapter Screen Description

This chapter describes the layout of the screen, and the function of the
various widget and menu items.

@menu
* Window Widgets::              
* Trace Menu::                  
* Customize Menu::              
* Cursor Menu::                 
* Signal Menu::                 
* Value Menu::                  
@end menu

@node Window Widgets, Trace Menu, Screen Description, Screen Description
@section Window Widgets

The main window is broken into the display area, with signal names on
the left and values stretching to the vertical scroll bar.  

The state of each signal across time is indicated by the way the line is
drawn.  As usual, low, tristate, and high are low, middle, and high
strait lines.  The high value has a bolder line to aid in discriminating
it from a low.  Unknowns are filled areas.

Busses are drawn in one of four ways; if zero they are low, if all bits
are one it it is two parallel lines with the upper one bolded.  If the
bus is some mix of zeros and ones it is two narrow parallel lines.  If
there is space the value of the bus will be shown based on the
@dmenu{Signal Radix} menu option.  Finally, the @dmenu{Signal Waveform}
allows analog waveforms, or signed waveforms (two's complement with 0 making
a centered trace.)

Gadgets surround the main area.  The vertical scroll bar on the right is
the @widget{Signal Slider} used to scroll signals, if they all cannot
fit on the screen at once.  At the bottom of the screen is the
@widget{Time Slider} on the right, and the @widget{Name Slider} on the
left.

@menu
* Time Slider::                 
* Name Slider::                 
* Signal Slider::               
* Buttons::                     
@end menu

@node Time Slider, Name Slider, Window Widgets, Window Widgets
@subsection Time Slider
@cindex Time Slider

On the left bottom of the main window is the @widget{Time Slider}.

@c @table @widget
@table @emph
@item Drag

Dragging the @widget{Time Slider} will scroll the time across the
screen.  Lines are printed in the scroll area to indicate where cursors
are located.

@item Unit Dec
@kindex @key{left}

Clicking the <- arrow at the left of the @widget{Time Slider}, or
pressing @kbd{@key{left}} will move the time one grid #0 (or the first
visible grid) resolution earlier.

@item Unit Inc
@kindex @key{right}

Clicking the -> arrow at the right of the @widget{Time Slider}, or pressing
@kbd{@key{right}} will move the time one grid #0 resolution (usually one
clock) later.

@item Page Dec
@kindex S-@key{left}

Clicking the blank area at the left of the @widget{Time Slider}, or pressing
@kbd{S-@key{right}} will move the time one screen width earlier, so the
time at the left of the screen is now at the right.  (Or 1/2 or 1/4
screen width, depending on the @config{page_inc} customization setting.)

@item Page Inc
@kindex S-@key{right}

Clicking the blank area at the right of the @widget{Time Slider}, or pressing
@kbd{S-@key{right}} will move the time one screen width later, so the
time at the right of the screen is now at the left. (Or 1/2 or 1/4
screen width, depending on the @config{page_inc} customization setting.)
@end table

@node Name Slider, Signal Slider, Time Slider, Window Widgets
@subsection Name Slider
@cindex Name Slider
@cindex Signal Names, Scrolling

The @widget{Name Slider} is the horizontal scroll bar left of the
@widget{Time Slider}.

@c @table @widget
@table @emph
@item Drag
@cindex Name Slider
@cindex Signal Names, Scrolling

Dragging the @widget{Name Slider} will scroll the signal names left and
right so that they may be completely seen.  Dinotrace aligns the signals
on the last dot (hierarchy character).

@end table

@node Signal Slider, Buttons, Name Slider, Window Widgets
@subsection Signal Slider
@cindex Signal Slider
@cindex Signals, Scrolling

The @widget{Signal Slider} is the vertical scroll bar to the right of
the window.

@c @table @widget
@table @emph
@item Drag
@cindex Signal Slider

Dragging the @widget{Signal Slider} will scroll the signals so that new
signals can be seen.  Lines are printed in the scroll area to indicate
where highlighted signals are located.

@item Unit Dec
@kindex @key{up}

Clicking the <- arrow at the top of the @widget{Signal Slider}, or
pressing @kbd{@key{up}} will move the signals down one, displaying a new
signal at the top.

@item Unit Inc
@kindex @key{down}

Clicking the -> arrow at the bottom of the @widget{Signal Slider}, or
pressing @kbd{@key{down}} will move the Moves signals up one, displaying
a new signal at the bottom.

@item Page Dec
@kindex S-@key{up}
@kindex @key{pageup}

Clicking the blank area above the @widget{Signal Slider}, or pressing
@kbd{@key{pageup}} will move the signals up one screen full, so the
previous top signal is now at the bottom.

@item Page Inc
@kindex S-@key{down}
@kindex @key{pagedown}

Clicking the blank area below the @widget{Signal Slider}, or pressing
@kbd{@key{pagedown}} will move the signals down one screen full, so the
previous bottom signal is now at the top.

@end table

@node Buttons,  , Signal Slider, Window Widgets
@subsection Buttons

The buttons below the lower sliders perform common functions that affect
the display.

@c @table @widget
@table @emph
@item Begin
@cindex Begin Button
@cindex Time, Moving to Beginning
@kindex @key{begin}

Clicking the @widget{Begin} button below the @widget{Time Slider}, or
pressing @kbd{@key{begin}} will move to the earliest time in the trace.

@item End
@cindex End Button
@cindex Time, Moving to End
@kindex @key{end}

Clicking the @widget{End} button below the @widget{Time Slider}, or pressing
@kbd{@key{end}} will move to the earliest time in the trace.

@item Goto
@cindex Goto Button
@cindex Time, Goto
@kindex g

Clicking the @widget{Goto} button below the @widget{Time Slider}, or
pressing @kbd{g} will make a popup that prompts for a time.  The window
will scroll horizontally so that the entered time is centered on the
screen.  A option menu will place a cursor of the selected color at the
time entered.  A note may be attached to the cursor, and seen with
@dmenu{Value Examine}.

@item Refresh
@cindex Refresh Button

Clicking the @widget{Refresh} button below the scroll bar will refresh
the screen.  Normally this is automatic.  When using Dinotrace over slow
links, it may be desirable to refresh manually, @xref{refreshing}.

@item Resolution
@cindex Resolution Button

Clicking the @widget{Resolution} number button at the middle bottom will
make a popup that can change the resolution to the number specified.

@item Inc Res
@cindex Resolution, Incrementing
@cindex Increment Resolution Button

Clicking the arrow button to the right of the @widget{Resolution} button
expands the trace so the same amount of time takes more space.

@item Dec Res
@cindex Resolution, Decrementing
@cindex Decrement Resolution Button

Clicking the arrow button to the left of the @widget{Resolution} button
expands the trace so the same amount of time takes less space.

@item Zoom
@cindex Time, Zooming
@cindex Zoom Button

Clicking the @widget{Zoom} button, then clicking @kbd{@key{MB1}} on two
times expands the trace so that the time between the clicks occupies the
entire screen.

@item Full
@cindex Full
@cindex Time, Full Window

Clicking the @widget{Full} button shrinks the resolution so that the
entire trace fits onto the screen.  It is often quicker to press
@widget{Full} then zoom to the desired location rather than scrolling.

@end table

@node Trace Menu, Customize Menu, Window Widgets, Screen Description
@section Trace Menu

@menu
* Trace Read...::               
* Trace ReRead::                
* Trace ReRead All::            
* Trace Open...::               
* Trace Close::                 
* Trace Clear::                 
* Trace Print...::              
* Trace Print::                 
* Trace Exit::                  
@end menu

@node Trace Read..., Trace ReRead, Trace Menu, Trace Menu
@subsection Trace Read...
@cindex Trace Read...
@cindex Reading, Traces
@kindex C-o

Selecting the @dmenu{Trace Read...} menu option, or pressing @kbd{C-o}
pops up a file requester to read a trace.  If a file ends in a @file{.Z}
or @file{.gz} extension, it will be piped through uncompress or gunzip
respectively before being read.  The type of trace may be set with the
option box; the default is set by the @config{file_format} configuration
command.  If @widget{Preserve Signal Ordering} is checked, the signals
in the new trace will be reorganized to attempt to match the ordering of
the current trace in the window.

@node Trace ReRead, Trace ReRead All, Trace Read..., Trace Menu
@subsection Trace ReRead
@cindex Trace ReRead
@cindex Rereading, Traces

Selecting @dmenu{Trace ReRead} checks if there is a new version of the
file currently begin displayed and reads it.  The file will only be read
if a new one exists.  If no file is displayed, it is the same as the
@dmenu{Trace Read} option.

This is useful for rereading a trace after it has changed due to a new
simulation run.

@node Trace ReRead All, Trace Open..., Trace ReRead, Trace Menu
@subsection Trace ReRead All
@cindex Trace ReRead All
@kindex C-r

Selecting @dmenu{Trace ReRead All}, or pressing @kbd{C-r}, checks every
window to see if that window's file has been updated, and rereads if it
has.

@node Trace Open..., Trace Close, Trace ReRead All, Trace Menu
@subsection Trace Open...
@cindex Trace Open...
@cindex Opening, Traces

Selecting @dmenu{Trace Open...} shrinks the current window in half, and
opens another Dinotrace window, linked in time to the original.  The two
traces will then pan together and share cursors, etc.  Multiple window
support is intended for traces that have the same time lengths.
See @ref{open_geometry} for how to change the default window sizes, such as
to not shrink the original window when opening.

@node Trace Close, Trace Clear, Trace Open..., Trace Menu
@subsection Trace Close
@cindex Trace Close
@cindex Closing, Traces

Selecting @dmenu{Trace Close} closes the current window if more than one
is open.  If this is the only one remaining open, use @dmenu{Trace Exit}
instead.

@node Trace Clear, Trace Print..., Trace Close, Trace Menu
@subsection Trace Clear
@cindex Trace Clear
@cindex Clearing, Traces

Selecting @dmenu{Trace Clear} closes all other windows and resets
Dinotrace as if Dinotrace was exited and ran again.

@node Trace Print..., Trace Print, Trace Clear, Trace Menu
@subsection Trace Print...
@cindex Trace Print...
@cindex Print...
@cindex Printing

Selecting @dmenu{Trace Print...} pops up a file requester allowing the
current screen to be printed to a file.  The amount of time, and number
of signals on the screen will match the time and signals put onto one
page of paper.

The @widget{Filename} and @widget{Note} specify where to put the output,
and a note to be placed on the bottom of each page.

@cindex Page Size, Print
@cindex Print, Page Size

The @widget{Layout} option selects the size of the page.  @widget{EPS}
will make a Encapsulated Postscript file that does not include all of
the headers.  This is suitable for making figures for inclusion in other
documents.

The @widget{Include off-screen times} button will print multiple
@dfn{horizontal} pages of paper, so that all times in the trace is
printed.  The @widget{Include off-screen signals} button will print
multiple @dfn{vertical} pages, so that all signals are printed.  Both
may be checked and taped together to get a nice wall hanging.

The @widget{Begin printing at} and @widget{End printing at} select the
region to be printed.  This may be based on the whole trace, what is
displayed on the screen, or the cursors.

@node Trace Print, Trace Exit, Trace Print..., Trace Menu
@subsection Trace Print
@cindex Trace Print

Selecting @dmenu{Trace Print} performs a print using the last @dmenu{Trace
Print...} settings.

@node Trace Exit,  , Trace Print, Trace Menu
@subsection Trace Exit
@cindex Trace Exit
@cindex Exiting

Selecting @dmenu{Trace Exit} will exit Dinotrace.


@node Customize Menu, Cursor Menu, Trace Menu, Screen Description
@section Customize Menu

@menu
* Customize Change...::         
* Customize Grid...::           
* Customize Read...::           
* Customize ReRead::            
* Customize Save As...::        
* Customize Restore::           
@end menu

@node Customize Change..., Customize Grid..., Customize Menu, Customize Menu
@subsection Customize Change...
@cindex Customize Change...

Selecting @dmenu{Customize Change} pops up a requester that allows the
configuration to be customized.  See @ref{Customization Files} for
permanent configuration, and additional options that are not selectable
here.

@cindex Page Increment

The @widget{Page Increment} option selects how much of a screen clicking
on the @widget{Page Inc} space on the @widget{Time Slider} will
increment.

@cindex Time, Representation
@cindex Representation, Time

The @widget{Time Representation} option selects how times are displayed
and entered in the @widget{Goto} popup.  Selecting @widget{Grid #0
Cycles} will put all times in the period defined by Grid #0.

@cindex Height, Signals
@cindex Signals, Height

The @widget{Signal Height} option controls how many signals can fit on
the screen and printout.  Small sizes have more information, but may
cause the values to be hard to read.

@cindex Edge, Clicking to
@cindex Click to Edge

The @widget{Click To Edge} button enables @dmenu{Cursor Add} and other
menu items that require mouse clicks to find the closest transition and add
it at that point.  The search will be only within 20 pixels; if there is no
edge within that distance, the cursor is added right where the cursor is.

@cindex Signal, Rise-fall time
@cindex Rise-fall time

The @widget{Rise/Fall Time} slider controls how fast signals transition.

@cindex Signal, Prefix, Drawing
@cindex Prefix, Drawing

Thw @widget{Draw Prefix} enables displaying the entire signal name,
instead of the default where a prefix common to every signal in the
design is not shown.

@cindex Refreshing, Mode
@cindex Manual Refreshing

Thw @widget{Manual Refreshing} button disables automatic refreshing, for
dialup lines.  The @widget{Refresh} button must be pressed to refresh
the screen.

@node Customize Grid..., Customize Read..., Customize Change..., Customize Menu
@subsection Customize Grid...
@cindex Customize Grid...
@cindex Grid...
@cindex Grid, Customization

Selecting @dmenu{Customize Grid} pops up a requester that allows the
configuration to be customized.  See @ref{Customization Files} for
permanent configuration.  Note that the lowest numbered grid that is
visible is used for moving one increment, stepping cursors forward and
back, and for counting cycles.

@node Customize Read..., Customize ReRead, Customize Grid..., Customize Menu
@subsection Customize Read...
@cindex Customize Read...
@cindex Reading, Customization

Selecting @dmenu{Customize Read} pops up a requester that reads the
specified @file{.dino} file.  The requester also allows enabling and
disabling of which @file{.dino} files will be read when a new trace is
read.

@node Customize ReRead, Customize Save As..., Customize Read..., Customize Menu
@subsection Customize ReRead
@cindex Customize ReRead

Selecting @dmenu{Customize ReRead} will reread the customize
@file{.dino} files.  This is useful for applying changes to Dinotrace
after a @file{.dino} file has been edited outside Dinotrace.

@node Customize Save As..., Customize Restore, Customize ReRead, Customize Menu
@subsection Customize Save As...
@cindex Customize Save As...
@cindex Saving, Customization

Selecting @dmenu{Customize Save As...} will create a popup.  A filename
may then be entered to save the current customization settings.  Buttons
allow different portions of the configuration to be written.  Note that
many of the settings that will be saved can be applied only to one
window, and should be edited out before being included in any global
@file{dinotrace.dino} files.

@node Customize Restore,  , Customize Save As..., Customize Menu
@subsection Customize Restore
@cindex Customize Restore
@cindex Restoring, Customization

Selecting @dmenu{Customize Restore} will restore the customization
options to their program defaults.  It will not read any @file{.dino}
files.

@c ------------------------------

@node Cursor Menu, Signal Menu, Customize Menu, Screen Description
@section Cursor Menu

@menu
* Cursor Add::                  
* Cursor Highlight::            
* Cursor Move::                 
* Cursor Delete::               
* Cursor Note::                 
* Cursor Step Forward::         
* Cursor Step Backward::        
* Cursor Clear::                
* Cursor Cancel::               
@end menu

@node Cursor Add, Cursor Highlight, Cursor Menu, Cursor Menu
@subsection Cursor Add
@cindex Cursor Add
@cindex Adding, Cursors
@kindex c
@kindex C

Selecting @dmenu{Cursor Add}, or pressing @kbd{c}, then clicking
@kbd{@key{MB1}} will insert cursors at the clicked on times.  The
@dmenu{Next} color button, or pressing @kbd{C} will select the next
color down in the menu from the last color selected.  See @ref{cursor_add}
for the equivalent configuration file command.

@node Cursor Highlight, Cursor Move, Cursor Add, Cursor Menu
@subsection Cursor Highlight
@cindex Cursor Highlight
@cindex Highlighting, Cursors

Selecting @dmenu{Cursor Delete} then clicking @kbd{@key{MB1}} on cursors
will change the color of those cursors.

@node Cursor Move, Cursor Delete, Cursor Highlight, Cursor Menu
@subsection Cursor Move
@cindex Cursor Move
@cindex Moving, Cursors

Selecting @dmenu{Cursor Move} then Dragging @kbd{@key{MB1}} on a cursor
will move that cursor.  Press and hold mouse button one and release when
the cursor is at the new time desired.  Moving a cursor that was created
with @dmenu{Signal Search} will make that cursor permanent; the cursor
will not go away if the search is changed.

@node Cursor Delete, Cursor Note, Cursor Move, Cursor Menu
@subsection Cursor Delete
@cindex Cursor Delete
@cindex Deleting, Cursors

Selecting @dmenu{Cursor Delete} then clicking @kbd{@key{MB1}} on cursors
will delete those cursors.  To delete cursors that were created by
@dmenu{Value Search} (those with dotted lines), turn off the second
button on the @dmenu{Value Search} requester.

@node Cursor Note, Cursor Step Forward, Cursor Delete, Cursor Menu
@subsection Cursor Note
@cindex Cursor Note
@cindex Notes, Cursors

Selecting @dmenu{Cursor Note} then clicking @kbd{@key{MB1}} on a cursor
will pop up a dialog box to change the note attached to that cursor.

@node Cursor Step Forward, Cursor Step Backward, Cursor Note, Cursor Menu
@subsection Cursor Step Forward
@cindex Cursor Step Foward
@cindex Moving, Cursors by Grid
@cindex Grids, Stepping Cursors by

Selecting @dmenu{Cursor Step Forward} or pressing @kbd{>} will move all
user cursors forward the by grid #0's (or the first visible grid's)
period.

@node Cursor Step Backward, Cursor Clear, Cursor Step Forward, Cursor Menu
@subsection Cursor Step Backward
@cindex Cursor Step Backward
@cindex Moving, Cursors by Grid
@cindex Grids, Stepping Cursors by

Selecting @dmenu{Cursor Step Back} or pressing @kbd{<} will move all
user cursors backward the by grid #0's (or the first visible grid's)
period.

@node Cursor Clear, Cursor Cancel, Cursor Step Backward, Cursor Menu
@subsection Cursor Clear
@cindex Cursor Clear
@cindex Clearing, Cursors

Selecting @dmenu{Cursor Clear} will delete all cursors.

@node Cursor Cancel,  , Cursor Clear, Cursor Menu
@subsection Cursor Cancel
@cindex Cursor Cancel
@kindex @key{esc}

Selecting @dmenu{Cursor Cancel}, or pressing @kbd{@key{esc}} will stop
@kbd{@key{MB1}} mouse clicks from having any affect.

@c ------------------------------
@node Signal Menu, Value Menu, Cursor Menu, Screen Description
@section Signal Menu

@menu
* Signal Add...::               
* Signal Highlight::            
* Signal Move::                 
* Signal Copy::                 
* Signal Delete::               
* Signal Note::                 
* Signal Radix::                
* Signal Waveform::             
* Signal Search...::            
* Signal Select...::            
* Signal Clear Highlight::      
* Signal Keep Highlight::       
* Signal Cancel::               
@end menu

@node Signal Add..., Signal Highlight, Signal Menu, Signal Menu
@subsection Signal Add...
@cindex Signal Add
@cindex Adding, Signals

Selecting @dmenu{Signal Add} will pop up a popup allowing a signal to be
selected then added at the point where @kbd{@key{MB1}} is clicked.
See @ref{signal_add} for the equivalent configuration file command.

@node Signal Highlight, Signal Move, Signal Add..., Signal Menu
@subsection Signal Highlight
@cindex Signal Highlight
@cindex Highlighting, Signals
@kindex s
@kindex S

Selecting @dmenu{Signal Highlight}, or pressing @kbd{s}, then clicking
@kbd{@key{MB1}} on signals changes the color of those signals.
See @ref{signal_highlight} for the equivalent configuration file command.

@node Signal Move, Signal Copy, Signal Highlight, Signal Menu
@subsection Signal Move
@cindex Signal Move
@cindex Moving, Signals

Selecting @dmenu{Signal Move} then clicking @kbd{@key{MB1}} on a signal
and clicking @kbd{@key{MB1}} again on a new position moves a signal.
Signals may be moved between traces, but closing a trace eliminates all
signals that were originally from that trace.  See @ref{signal_move} for
the equivalent configuration file command.

@node Signal Copy, Signal Delete, Signal Move, Signal Menu
@subsection Signal Copy
@cindex Signal Copy
@cindex Copying, Signals

Selecting @dmenu{Signal Copy} then clicking @kbd{@key{MB1}} on a signal
and clicking @kbd{@key{MB1}} again on a new position copies a signal.
Signals may be copied between traces, but closing a trace eliminates all
signals that were originally from that trace.  See @ref{signal_copy} for
the equivalent configuration file command.


@node Signal Delete, Signal Note, Signal Copy, Signal Menu
@subsection Signal Delete
@cindex Signal Delete
@cindex Deleting, Signals

Selecting @dmenu{Signal Delete} then clicking @kbd{@key{MB1}} on signals
deletes those signals.  @dmenu{Signal Select} may be used to recover the
deleted signals.  See @ref{signal_delete} for the equivalent configuration
file command.

@node Signal Note, Signal Radix, Signal Delete, Signal Menu
@subsection Signal Note
@cindex Signal Note
@cindex Notes, Signals

Selecting @dmenu{Signal Note} then clicking @kbd{@key{MB1}} on a signal
will pop up a dialog box to change the note attached to that signal.

@node Signal Radix, Signal Waveform, Signal Note, Signal Menu
@subsection Signal Radix
@cindex Signal Radix
@cindex Radix, Signals

Selecting @dmenu{Signal Radix} then clicking @kbd{@key{MB1}} on signals
changes the radix of the signals to the one selected.  Note that the
@code{real} radix is detected for Verilog automatically, and changing
other non-real signals to a real format probably won't display the
values you wish.  See @ref{signal_radix} for the equivalent configuration
file command.

@node Signal Waveform, Signal Search..., Signal Radix, Signal Menu
@subsection Signal Waveform
@cindex Signal Waveform
@cindex Waveform, Signals

Selecting @dmenu{Signal Waveform} then clicking @kbd{@key{MB1}} on
signals changes the signal to be displayed as either analog or digital.
See @ref{signal_waveform} for the equivalent configuration file command.

@node Signal Search..., Signal Select..., Signal Waveform, Signal Menu
@subsection Signal Search...
@cindex Signal Search...
@cindex Searching, Signals
@cindex Finding, Signals

Selecting @dmenu{Signal Search} opens a popup for highlighting signal
names.  Nine signal names which will be searched for in the trace are
specified.  Any signal name which matches the signal name pattern will
be highlighted using the color of the toggle button, just as if
@dmenu{Signal Highlight} was used to color it.  Unlike @dmenu{Signal
Search}, highlighting a signal with @dmenu{Signal Highlight} makes it
permanent; it will not go away when the search that found that signal
changes.

The @widget{Signal name pattern} indicates which signal names to
highlight, potentially containing @kbd{*} to match any number of
characters, or @kbd{?} to match any single character.  Case never
matters when matching signal names.

The @widget{Enable} button enables the search, and shows the color to be
used for highlighting when the signal is found.

@node Signal Select..., Signal Clear Highlight, Signal Search..., Signal Menu
@subsection Signal Select...
@cindex Signal Select...
@cindex Selecting, Signal
@kindex C-f

Selecting @dmenu{Signal Select}, or pressing @kbd{C-f}, presents a
requester which lists the names of the signals which are being
displayed, and those which are deleted.  Both lists have a pattern at
the top which a signal must match to be displayed.  Clicking on a signal
will add it to the bottom of the other list.  Clicking on the
@widget{Add All} or @widget{Delete All} will affect all of those in the
list.  By specifying a pattern then @widget{Add All} or @widget{Delete
All}, signals which match a pattern can be added or deleted.

The @widget{Delete Constants} button will delete only those signals
which have a single constant value for all times in the trace.  Likewise
the @widget{Delete Const or X/Z} button will delete only those signals
which have a constant value, or are unknown or tristated.  This is
useful for deleting those signals which have uninitialized values before
reset then later in the trace are initalized to constants.

The @widget{Sort Wholename} and @widget{Sort Basename} buttons will sort
the selected signals and place them at the bottom of the trace.  The
former uses the entire signal name, while the latter sorts by the
basename, ignoring the hierarchy portion of the signal name.

@node Signal Clear Highlight, Signal Keep Highlight, Signal Select..., Signal Menu
@subsection Clear Highlight
@cindex Clear Highlight
@cindex Highlighting, Signals
@cindex Signals, Highlighting

Selecting @dmenu{Signal Clear Highlight} will remove all highlighting
from signals.

@node Signal Keep Highlight, Signal Cancel, Signal Clear Highlight, Signal Menu
@subsection Keep Highlight
@cindex Keep Highlight
@cindex Deleting, Signals
@cindex Signals, Deleting

Selecting @dmenu{Signal Keep Highlighted} will delete signals from the
trace which are not highlighted.  This allows signals to be highlighed
that match a given pattern using @widget{Signal Select...}, then all
others deleted using this selection.

@node Signal Cancel,  , Signal Keep Highlight, Signal Menu
@subsection Signal Cancel
@cindex Signal Cancel

Selecting @dmenu{Signal Cancel}, or pressing @kbd{@key{esc}} will stop
@kbd{@key{MB1}} mouse clicks from having any affect.

@c ------------------------------

@node Value Menu,  , Signal Menu, Screen Description
@section Value Menu

@menu
* Value Annotate...::           
* Value Annotate::              
* Value Highlight::             
* Value Examine::               
* Value Search...::             
* Value Cancel::                
@end menu

@node Value Annotate..., Value Annotate, Value Menu, Value Menu
@subsection Value Annotate...
@cindex Value Annotate...
@cindex Annotate...
@cindex Annotation
@cindex Emacs, Annotation

Selecting @dmenu{Value Annotate...} makes a file with the highlighted
signals, and values under every cursor.  Behavioral code can then be
highlighted with the values by @file{dinotrace.el}'s reading the written
file.  Cursors which are exactly on a edge of a signal will get the
value that the signal is changing @emph{to}, not from.

Buttons specify which cursor and signal colors are included in the file.
If a button is on, the color is included, else it is as if the cursor
did not exist, or the signal was not highlighted.

User cursors are those placed using the @dmenu{Cursor Add} menu.
Automatic cursors are from searching for values or cursors placed by
@file{.dino} files.

See @ref{Dinotrace and Emacs}

@node Value Annotate, Value Highlight, Value Annotate..., Value Menu
@subsection Value Annotate
@cindex Value Annotate
@kindex a

Selecting @dmenu{Value Annotate}, or pressing @kbd{a} annotates code
using the last Annotate... settings.  See @ref{annotate} for the equivalent
configuration file command.

@node Value Highlight, Value Examine, Value Annotate, Value Menu
@subsection Value Highlight
@cindex Value Highlight
@cindex Highlighting, Values
@kindex v
@kindex V

Selecting @dmenu{Value Highlight}, or pressing @kbd{v}, then clicking
@kbd{@key{MB1}} on a value loads that value into one of the 9 search
values, and highlights it where it occurs in the trace.  The search
value can then be seen and modified with the @dmenu{Value Search} popup.
See @ref{value_highlight} for the equivalent configuration file command.

@node Value Examine, Value Search..., Value Highlight, Value Menu
@subsection Value Examine
@cindex Value Examine
@cindex Examining, Values

Selecting @dmenu{Value Examine} then holding @kbd{@key{MB1}}
will show the state of the entity under the mouse.  @kbd{@key{MB2}} can
always be used for this feature.

Signal transitions can be examined when over the transition lines.
Signal names and base information can be seen when over the signal
names.  Cursors can be examined when at the bottom of the screen, and
grids when at the top.

@node Value Search..., Value Cancel, Value Examine, Value Menu
@subsection Value Search...
@cindex Value Search...
@cindex Searching, Values

Selecting @dmenu{Value Search...} allows specification of 9 values to be
searched for in the trace.  Each value is entered into a text widget and
one or two toggle buttons to the left are activated.  The @dmenu{Value
Highlight} menu can be used to load a search automatically.
See @ref{value_highlight} for the equivalent configuration file command.

The @widget{Highlight value} button will make anywhere that the value
appears in a trace to be printed using the color of the toggle button.

The @widget{Add cursor} button will add a cursor at the time where the
value begins.  Cursors that are placed in this fashion are displayed as
dotted lines, and will go away if the search value is changed.
Highlighting or moving a cursor makes it permanent; it will not go away
when the search changes.

The @widget{Signal name pattern} indicates which signals names to search
for the value, potentially containing @kbd{*} to match any number of
characters, or @kbd{?} to match any single character.  Often a single
@kbd{*} is useful to search all signals.

The @widget{Value} indicates the value to be found.  Unfortunately wildcards
are not supported.  A standard verilog or VHDL prefix may be added to specify
the radix of the number being entered.  (The radix of the signal found does
not have to match the radix entered; @samp{'h10} will match @samp{'d16}.

@cindex Radix, Values
@cindex Values, indicating Radix

@table @code
@item  'h<num> 
@itemx X"<num>"
Hex           	
@item  'o<num> 
@itemx O"<num>"
Octal
@item  'b<num> 
@itemx B"<num>"
Binary            
@item  'd<num> 
@itemx D"<num>"
Decimal		
@item  'r<num>	
@itemx R"<num>"
Real		
@item  's<strg>
@item  S"<strg>"
@item  "<strg>"
Ascii (String)
@end table

@node Value Cancel,  , Value Search..., Value Menu
@subsection Value Cancel
@cindex Value Cancel

Selecting @dmenu{Value Cancel}, or pressing @kbd{@key{esc}} will stop
@kbd{@key{MB1}} mouse clicks from having any affect.

@c ======================================================================
@node Keyboard Shortcuts, Customization Files, Screen Description, Top
@chapter Keyboard Shortcuts
@cindex Keyboard Shortcuts

This chapter describes the keyboard shortcuts for Dinotrace.

Any menu function may be invoked with the standard Motif accelerators;
hold down @kbd{@key{ALT}} then press the first letter of the menu name.
Release @kbd{@key{ALT}} and press the underlined letter of the sub menu
item, and so on.

The following keys are also hard-coded: Function keys have the identical
function when using GNU Emacs's Verilog, C, Merlin, or CCLI modes.

@table @kbd
@item @key{MB2}
@dmenu{Value Examine}.

@item @key{up}
Signal scroll up one signal.
@item S-@key{up}
Signal scroll up a screen full.
@item @key{down}
Signal scroll down one signal.
@item S-@key{down}
Signal scroll down a screen full.
@item @key{pageup}
Signal scroll up a screen full.
@item @key{pagedown}
Signal scroll down a screen full.
@item @key{left}
Time scroll left a grid #0 increment.
@item S-@key{left}
Time scroll left a screen full.
@item @key{right}
Time scroll left a grid #0 increment.
@item S-@key{right}
Time scroll left a screen full.
@item @key{begin}
Beginning of time.
@item @key{end}
End of time.

@item @key{esc}
@dmenu{Signal Cancel}.

@item >
@dmenu{Cursor Step Forward}.
@item <
@dmenu{Cursor Step Backward}.

@item a
@dmenu{Value Annotate}.
@item c
@dmenu{Cursor Add} with current color.
@item C
@dmenu{Cursor Add} with next color.
@item g
@widget{Goto} time.
@item s
@dmenu{Signal Highlight} with current color.
@item S
@dmenu{Signal Highlight} with next color.
@item v
@dmenu{Value Highlight} with current color.
@item V
@dmenu{Value Highlight} with next color.

@item C-f
@dmenu{Signal Search...}.
@item C-o
@dmenu{Trace Read...}.
@item C-r
@dmenu{Trace ReRead All}.

@end table

@c ======================================================================
@node Customization Files, X Resources, Keyboard Shortcuts, Top
@chapter Customization Files

This chapter describes customization files, and the commands that
may be used in them.

Customization files allow the options and display in Dinotrace to
be customized to suit a specific site, user, directory, and trace.

@menu
* Automatically Read Files::    
* Configuration Commands::      
@end menu

@node Automatically Read Files, Configuration Commands, Customization Files, Customization Files
@section Automatically Read Files

When a trace file is read using the @dmenu{Trace Read} menu option,
several configuration files are read automatically:

@table @file

@item $DINODISK:dinotrace.dino
@cindex DINODISK
@cindex Environment Variables, DINODISK

The @file{$DINODISK:dinotrace.dino} file is intended to have site wide
defaults.  This will probably contain a @config{file_format verilog} or
similar commands.  (On Unix, @file{$DINODISK} represents the contents of
the @file{DINODISK} environment variable.  On VMS, it represents the
value of the system define.)

@item $DINOCONFIG
@cindex DINOCONFIG
@cindex Environment Variables, DINOCONFIG

The @file{$DINOCONFIG} file is intended to be used for session specific
start-up, like setting screen size depending on what type of system you
are using.  Users will probably point this to several possible sources
using their @file{.login}.

@item ~/dinotrace.dino

The @file{~/dinotrace.dino} file is for user defaults.  The author for
example has a @config{signal_height 15} and
@config{signal_delete_constant *}, which are both personal preference
items.  (On VMS, @file{SYS$LOGIN:} is used instead of @file{~/}.)

@item @{current/trace/directory@}/dinotrace.dino

The @file{@{current/trace/directory@}/dinotrace.dino} is for signal_states
and other information on a per-simulation setup basis.  This probably
includes @config{signal_state} commands (unless they are in the global
dinotrace.dino).

@item @{current/trace/directory@}/CURRENT_TRACE_NAME.dino

The @file{@{current/trace/directory@}/CURRENT_TRACE_NAME.dino} is for
highlighting and such that only apply to the current file.  See the
enclosed example @prog{Perl} script that will parse a log file for times
that errors occurred and write a dino that places a cursor at every such
time.

@end table

@node Configuration Commands,  , Automatically Read Files, Customization Files
@section Configuration Commands

Configuration files are organized with one command per line, with the
exception of @config{signal_states}, which may be multiple lines.  Case
is ignored in all but state names.  The commands are:

@menu
* #::                           
* page_inc::                    
* rise_fall_time::              
* signal_height::               
* grid::                        
* grid_resolution::             
* grid_align::                  
* grid_signal::                 
* grid_type::                   
* grid_color::                  
* refreshing::                  
* refresh::                     
* draw_prefix::                 
* annotate::                    
* resolution::                  
* save_enables::                
* save_duplicates::             
* save_ordering::               
* signal_goto::                 
* time_goto::                   
* time_rep::                    
* time_precision::              
* time_format::                 
* time_divisor::                
* time_multiplier::             
* file_format::                 
* cursor::                      
* cursor_add::                  
* click_to_edge::               
* debug::                       
* print::                       
* print_size::                  
* vector_separator::            
* start_geometry::              
* open_geometry::               
* shrink_geometry::             
* value_highlight::             
* signal_highlight::            
* signal_add::                  
* signal_delete::               
* signal_delete_constant::      
* signal_copy::                 
* signal_move::                 
* signal_note::                 
* signal_rename::               
* signal_radix::                
* signal_waveform::             
* signal_states::               
@end menu

@node #, page_inc, Configuration Commands, Configuration Commands
@subsection #
@findex # (configuration comment)
@cindex Comments
@config{#}	@var{comment}

Comments out the remainder of the line.

@node page_inc, rise_fall_time, #, Configuration Commands
@subsection page_inc
@findex page_inc
@cindex Page Increment
@config{page_inc}		@var{4 | 2 | 1}

Changes the increment used during @widget{Page Inc} and @widget{Page
Dec} clicks on the horizontal scroll-bar.  1=full page, 2=half,
4=quarter.  Same as the page option menu in @dmenu{Customize Change}.

@node rise_fall_time, signal_height, page_inc, Configuration Commands
@subsection rise_fall_time
@findex rise_fall_time
@cindex Signal, Rise-fall time
@cindex Rise-fall time
@config{rise_fall_time}	@var{number}

Changes the slope used when drawing signal assertions and deassertion.
Use 0 to minimize the @config{rise_fall_time}.

@node signal_height, grid, rise_fall_time, Configuration Commands
@subsection signal_height
@findex signal_height
@cindex Height, Signals
@config{signal_height}	@var{number}

Changes the vertical spacing between signals on the screen.  Same as the
slider in @dmenu{Customize Change}.

@node grid, grid_resolution, signal_height, Configuration Commands
@subsection grid
@findex grid
@config{grid}		@var{grid_number}       ON | OFF

Enables or disables the grid.  Same as the visible toggle buttons in
@dmenu{Customize Grid}.

@node grid_resolution, grid_align, grid, Configuration Commands
@subsection grid_resolution
@findex grid_resolution
@cindex Resolution, Grids
@config{grid_resolution}	@var{grid_number}       @var{number} | AUTO | EDGE

Changes the horizontal space between grids, normally the period of a
clock.  Specify a number in nanoseconds, or @code{AUTO} to compute the
grid based on the @config{grid_signal}.  Use @code{EDGE} to place a grid
on each change of the @config{grid_signal}.

@node grid_align, grid_signal, grid_resolution, Configuration Commands
@subsection grid_align
@findex grid_align
@cindex Aligning, Grids
@config{grid_align}	@var{grid_number}       @var{number} | ASSERTION | DEASSERTION | BOTH

Changes the horizontal location of the first grid mark.  Specify a
number in nanoseconds, @samp{ASSERTION} to align with the asserting edge
of the @config{grid_signal}, or @samp{DEASSERTION} to align with the
deasserting edge of the @config{grid_signal}, or @samp{BOTH} to align
with both edges of the @config{grid_signal}.  The grid may also align
with changes in a bus, although in that case @samp{ASSERTION} and
@samp{DEASSERTION} have the same effect.

@node grid_signal, grid_type, grid_align, Configuration Commands
@subsection grid_signal
@findex grid_signal
@cindex Signal, Grids
@config{grid_signal}	@var{grid_number}	@var{pattern}

Specifies which signal is to be used when calculating the period and
alignment with grid_resolution and grid_alignment respectively.  The
first signal that matches the pattern is used, it defaults to
@samp{"*"}, which is the first signal in the trace.  If no signal is
found that matches the pattern, that grid will be disabled.

@node grid_type, grid_color, grid_signal, Configuration Commands
@subsection grid_type
@findex grid_type
@config{grid_type}	@var{pattern}	NORMAL | WIDE

Specifies normal grids, or extra wide grids.  Wide grids are plotted 2
pixels wide, and help low-contrast colors show up better.

@node grid_color, refreshing, grid_type, Configuration Commands
@subsection grid_color
@cindex Color, Grids
@findex grid_color
@config{grid_color}	@var{grid_number}	@var{color}

Changes the color used to display the grid.

@node refreshing, refresh, grid_color, Configuration Commands
@subsection refreshing
@findex refreshing
@cindex Refreshing, Mode
@cindex Manual Refreshing
@config{refreshing}		AUTO | MANUAL

In automatic refresh mode, any change in the screen such as zooming,
Dragging, or exposing refreshes (redraws) the screen.  When set to manual
the screen will only redraw when the refresh gadget is pressed.  Note
that when in manual mode, it is just as if the display @emph{was}
refreshed, so for example clicking on the display is relative to the
@emph{new} display. Useful when using slow network links, such as dialup
@pindex eXcursion
@pindex exceed
@prog{eXcursion} or @prog{exceed}.

@node refresh, draw_prefix, refreshing, Configuration Commands
@subsection refresh
@findex refresh
@cindex Refreshing, Doing
@config{refresh}

Refresh the screen, even if in manual refresh mode.  When a @file{.dino}
file is being read, the screen will not be refreshed until the entire file
is completely read, unless a @config{refresh} command is used.

@node draw_prefix, annotate, refresh, Configuration Commands
@subsection draw_prefix
@findex draw_prefix
@cindex Signal, Prefix, Drawing
@cindex Prefix, Drawing
@config{draw_prefix}

By default, a prefix common to every signal in the design is not shown
in the main window.  With this setting, the signal name will be shown in
it's entirety.

@node annotate, resolution, draw_prefix, Configuration Commands
@subsection annotate
@findex annotate
@cindex Annotation
@config{annotate}

Makes the annotation file, like the @dmenu{Value Annotate} menu.

@node resolution, save_enables, annotate, Configuration Commands
@subsection resolution
@findex resolution
@cindex Resolution
@config{resolution}		@var{number}

Sets the screen resolution, like the @widget{Resolution} Button on the
bottom of the screen.

@node save_enables, save_duplicates, resolution, Configuration Commands
@subsection save_enables
@findex save_enables
@cindex Enables, Saving
@cindex Tristates, Saving
@config{save_enables}	ON | OFF

When reading in verilator CCLI traces, Dinotrace converts two-state
enables and data signals into a single four-state signal, then deletes
the original signals.  When @config{save_enables} is on, the original
signals are not deleted.  This is useful for debugging problems related
to tristating.

@node save_duplicates, save_ordering, save_enables, Configuration Commands
@subsection save_duplicates
@findex save_duplicates
@cindex Signals, Duplicates, Saving
@cindex Duplicate Signals, Saving
@cindex Verilog, Duplicate Signals
@config{save_duplicates}	ON | OFF

When reading in verilog traces, Dinotrace by default drops signals that
connect to a signal higher in the hierarchy.  This saves space and
reduces clutter.  When @config{save_duplicates} is on, the duplicate
signals are not deleted, except under rare situations.

@node save_ordering, signal_goto, save_duplicates, Configuration Commands
@subsection save_ordering
@findex save_ordering
@config{save_ordering}	ON | OFF

When set, Dinotrace will attempt to preserve signal colors, ordering,
and deletions between the trace that existed before and the new trace
being read in.  Signals that were deleted because they were constants
are not preserved, they will be recalculated.  When clear, the new trace
does not preserve any ordering information.

@node signal_goto, time_goto, save_ordering, Configuration Commands
@subsection signal_goto
@findex signal_goto
@cindex Goto, Signal
@config{signal_goto}		@var{signal}

Move the window so that signal is in the center of the window.  If the
signal was already on the screen, do nothing.

@node time_goto, time_rep, signal_goto, Configuration Commands
@subsection time_goto
@findex time_goto
@cindex Goto, Time
@config{time_goto}		@var{time}

Move the window so that time is in the center of the window.  If time
was already on the screen, do nothing.

@node time_rep, time_precision, time_goto, Configuration Commands
@subsection time_rep
@cindex Representation, Time
@cindex Time, Representation
@findex time_rep
@config{time_rep}		@var{number} | FS | PS | NS | US | CYCLE

Changes the time representation to be in picoseconds, nanoseconds,
microseconds or in number of grid #0 cycles.  Cycle based timing is good
for performance estimates.  Same as the buttons in @dmenu{Customize
Change}.  If a number, then that number is the baseline in picoseconds.
For example, @samp{2000} will make one unit on the screen be equal to 2
ns in the trace file.  Default is nanoseconds.

@node time_precision, time_format, time_rep, Configuration Commands
@subsection time_precision
@cindex Precision, Time
@findex time_precision
@config{time_precision}	FS | PS | NS | US

Changes the internal precision to be in picoseconds, nanoseconds, or
microseconds.  Traces that are read in will have all times rounded to
this number.  Setting to higher units requires less memory and speeds up
execution.  This parameter must only be changed in the global or user
@file{dinotrace.dino} files, as it should not change between reading
different traces.  Default is nanoseconds.

Only Decsim Binary and Verilog formats contain absolute time periods,
and these will be scaled by the precision.  Decsim Ascii traces are
always assumed to be in nanoseconds.  The Tempest format will be assumed
to be in the same units as the @config{time_precision}, and will not be
scaled.

@node time_format, time_divisor, time_precision, Configuration Commands
@subsection time_format
@cindex Format, Time
@findex time_format
@config{time_format}		%0.6lf | %0.6lg | %lg | ""

Changes the number of decimal places used to print times.  This format
string is the same as that used by the C-Language printf command.  (See
@cite{man printf} or @cite{HELP CC RUN PRINTF}.) Some of the useful
choices are @samp{%0.6lf} which will print 6 decimal places with
trailing zeros (123.450000), @samp{%0.6lg} which will print up to 6
decimal places (123.45), and @samp{%lg} which will print the number of
decimal places required to fully show the number.
	
The default is null ("").  When null time_precision and time_rep will
set the preferred format for time stamps.  For example, setting
@config{time_precision PS} and @config{time_rep NS} will make times
display as "nn.ppp ns" where n is the nanoseconds, and p is the
picoseconds.

@node time_divisor, time_multiplier, time_format, Configuration Commands
@subsection time_divisor
@findex time_divisor
@cindex Divisor, Time
@config{time_divisor}	@var{number}

When reading Ascii traces, all times are divided by this number.
Generally the time_precision is what is wanted instead, as
time_precision doesn't change the internal times but instead the
display. Time_divisor changes the value that is read in from the file,
and is most useful for Ascii traces which do not specify any time
units in the file itself.

@node time_multiplier, file_format, time_divisor, Configuration Commands
@subsection time_multiplier
@findex time_multiplier
@cindex Multiplier, Time
@cindex Tempest Traces
@config{time_multiplier}	@var{number}

When reading Tempest traces, the multiplier will be used to convert the
phase counter to the time.  Defaults to 2.

@node file_format, cursor, time_multiplier, Configuration Commands
@subsection file_format
@cindex Format, File
@findex file_format
@config{file_format}		DECSIM | TEMPEST | VERILOG | VPD

Changes the file format to be read.  Same as the buttons in the
@dmenu{Trace Open} menu.

@node cursor, cursor_add, file_format, Configuration Commands
@subsection cursor
@findex cursor
@cindex Cursor, Enables
@config{cursor}		ON | OFF

Enables or disables the cursors.  Same as the toggle buttons in
@dmenu{Customize Change}.

@node cursor_add, click_to_edge, cursor, Configuration Commands
@subsection cursor_add
@findex cursor_add
@cindex Cursor, Add
@cindex Adding, Cursors
@config{cursor_add}	@var{time} @var{color} [-USER] [@var{comment}]

Adds a cursor of color number @var{color} (0 to 9) at the specified
time.  If specified, add @var{comment} that may be seen with
@dmenu{Value Examine}.  The cursor will be dotted, and will disappear
the next time a file is read in.  The @code{-USER} flag makes the cursor
like a manual cursor; it will be a solid line and will not disappear on
rereads.

@node click_to_edge, debug, cursor_add, Configuration Commands
@subsection click_to_edge
@findex click_to_edge
@cindex Edge, Clicking to
@cindex Click to Edge
@config{click_to_edge}	ON | OFF

Enables or disables whether adding a cursor or grid close to a signal
edge will place the cursor on that edge.

@node debug, print, click_to_edge, Configuration Commands
@subsection debug
@findex debug
@cindex Debugging, Mode
@config{debug}		ON | OFF

Enables or disables debugging mode.

@node print, print_size, debug, Configuration Commands
@subsection print
@findex print
@cindex Debugging, Print
@config{print}		@var{number} | ON | OFF

Enables or disables debugging print mode at the specified
informational level.

@node print_size, vector_separator, print, Configuration Commands
@subsection print_size
@findex print_size
@cindex Page Size, Print
@cindex Print, Page Size
@config{print_size}		A | B | EPSPORT | EPSLAND

Selects the paper size, A (8 1/2" by 11") or B (11" by 17").
@code{EPSPORT} and @code{EPSLAND} make an Encapsulated Postscript file
without headers, in portrait or landscape layout, suitable for inclusion
in other documents.

Same as the buttons in the @dmenu{Trace Print} popup.

@node vector_separator, start_geometry, print_size, Configuration Commands
@subsection vector_separator
@findex vector_separator
@cindex Separator, Vector
@config{vector_separator}	"@var{character}"

Sets the character that separates the base signal name from vector
numbers.  The default is @samp{[}, which means that the signal
@samp{alpha[1]} consists of vector number 1 in the signal named alpha.
Three other useful combinations are @samp{_} for spider signals
@samp{alpha_1}, @samp{<} for Decsim signals @samp{alpha<1>}, and null
("") for no separator @samp{alpha1}.  If the separator is null ("") then
@samp{<} will still be accepted.  Tempest traces are assumed to use the
@samp{<} separator, and setting it otherwise will split up all of the
bits into individual entries.

@node start_geometry, open_geometry, vector_separator, Configuration Commands
@subsection start_geometry
@findex start_geometry
@cindex Geometry, Start
@config{start_geometry}	@var{width}x@var{height}+@var{xoffset}+@var{yoffset}

Specifies the geometry to be used when the first window is opened by
Dinotrace.  Specified in standard X-Windows format, for example
@config{start_geometry 1200x900+20+95} specifies a window at position
20, 95 of width 1200 and height 900.

@node open_geometry, shrink_geometry, start_geometry, Configuration Commands
@subsection open_geometry
@findex open_geometry
@cindex Geometry, Open
@config{open_geometry}	@var{width}[%]x@var{height}[%]+@var{xoffset}[%]+@var{yoff}[%]

Specifies the geometry to be used when a new trace window is created
with @dmenu{Trace Open} menu.  The format may be the same as
@config{start_geometry}, in which case the exact dimensions specified
will be used for the new window.  Percentage may be used to specify a
position and size relative to the old window.  For example the default
is @samp{open_geometry 100%x50%+0%+50%} which means that the new
window will have the same width and half the height of the old window.
The position will be the same in the x direction and 50% more (not 50%
of the value) in the y direction.

@node shrink_geometry, value_highlight, open_geometry, Configuration Commands
@subsection shrink_geometry
@findex shrink_geometry
@cindex Geometry, Shrink
@config{shrink_geometry}	@var{width}%x@var{height}%+@var{xoffset}%+@var{yoff}%

Specifies the geometry to be used when a old trace window is being
shrunk with @dmenu{Trace Open} menu option.  Absolute positions should
not be used, instead percentages should be used to specify a position
and size relative to the original window size.  For example the default
is @samp{shrink_geometry 100%x50%+0%+0%} which means that when the new
opened window is created the old window will have the same width, X, and
Y position, but half the height of the old window.

@node value_highlight, signal_highlight, shrink_geometry, Configuration Commands
@subsection value_highlight
@findex value_highlight
@cindex Highlighting, Values
@config{value_highlight} @var{value} @var{color} [@var{signal_pattern}] -COLOR -CURSOR

Searches for the value in signals matching the pattern.  If the
@code{-COLOR} flag is set, changes the color of the value to @var{color}
(0 to 9).  If the @code{-CURSOR} flag is set, adds a cursor of the
specified @var{color}. The signal_pattern is the name of the signal
inside the trace, with @key{*} being a wild card that matches any number
of characters.

@node signal_highlight, signal_add, value_highlight, Configuration Commands
@subsection signal_highlight
@findex signal_highlight
@cindex Highlighting, Signals
@config{signal_highlight}       @var{signal_pattern}   @var{color} 

Changes the color of any signals matching @var{signal_pattern} to the
given color number @var{color} (0 to 9).  The signal_pattern is the name
of the signal inside the trace, with @key{*} being a wild card that
matches any number of characters.

@node signal_add, signal_delete, signal_highlight, Configuration Commands
@subsection signal_add
@findex signal_add
@cindex Adding, Signals
@config{signal_add}		@var{signal_pattern} [@var{after_signal}] [@var{color}]

Adds signals matching @var{signal_pattern} from the trace, if the signal was
deleted.  If the signal hasn't been deleted, nothing happens.  If the
@var{after_signal} is provided, the signal is added after the first
signal that matches the @var{after_signal} pattern.  If
@var{after_signal} is not provided, the new signal is added to the end
of the trace.

@node signal_delete, signal_delete_constant, signal_add, Configuration Commands
@subsection signal_delete
@findex signal_delete
@cindex Deleting, Signals
@config{signal_delete}	@var{signal_pattern}

Deletes signals matching @var{signal_pattern} from the trace.

@node signal_delete_constant, signal_copy, signal_delete, Configuration Commands
@subsection signal_delete_constant
@findex signal_delete_constant
@config{signal_delete_constant}	@var{signal_pattern} [-IGNOREXZ]

Deletes signals matching the pattern, which have a constant value, from
the trace.  If @code{-IGNOREXZ} is specified, don't consider transitions
to/from unknown or tristate as making a signal non-constant.  Useful for
reducing a large number of signals down to only those which change.

@node signal_copy, signal_move, signal_delete_constant, Configuration Commands
@subsection signal_copy
@findex signal_copy
@cindex Copying, Signals
@config{signal_copy}		@var{signal_pattern} [@var{after_signal}] [@var{color}]

Copies signals matching @var{signal_pattern} from the trace to a new
position.  If the @var{after_signal} is provided, the signal is added
after the first signal that matches the @var{after_signal} pattern.  If
@var{after_signal} is not provided or is not found, the new signal is
added to the end of the trace.

@node signal_move, signal_note, signal_copy, Configuration Commands
@subsection signal_move
@findex signal_move
@cindex Moving, Signals
@config{signal_move}		@var{signal_pattern} [@var{after_signal}] [@var{color}]

Move signals matching @var{signal_pattern} to a new position.  If the
@var{after_signal} is provided, the signal is moved after the first
signal that matches the @var{after_signal} pattern.  If
@var{after_signal} is not provided, the new signal is added to the end
of the trace.

@node signal_note, signal_rename, signal_move, Configuration Commands
@subsection signal_note
@findex signal_note
@cindex Notes, Signals
@config{signal_note}		@var{signal_pattern} @var{note}

Add the specified note to signals matching @var{signal_pattern}.  The
signal note may be viewed by pressing with the Examine button over the
signal name.

@node signal_rename, signal_radix, signal_note, Configuration Commands
@subsection signal_rename
@findex signal_rename
@cindex Renaming, Signals
@config{signal_rename}	@var{signal_pattern} @var{new_signal_name} [@var{color}]

Changes the @strong{first} signal matching @var{signal_pattern} to have
the name @var{new_signal_name} This can be used to make a alias copy of
a signal by copying a signal, then renaming it.

@node signal_radix, signal_waveform, signal_rename, Configuration Commands
@subsection signal_radix
@findex signal_radix
@cindex Radix, Signals
@config{signal_radix}	@var{signal_pattern} @var{radix}

Changes signals matching @var{signal_pattern} to have the specified
radix.  Note that the @code{real} radix is detected for Verilog
automatically, and changing other non-real signals to a real format
probably won't display the values you wish.

@node signal_waveform, signal_states, signal_radix, Configuration Commands
@subsection signal_waveform
@findex signal_waveform
@cindex Waveform, Signals
@config{signal_waveform}	@var{signal_pattern} ANALOG | ANALOG_SIGNED | DIGITAL

Changes signals matching @var{signal_pattern} to have the specified
waveform representation on the display.

@node signal_states,  , signal_waveform, Configuration Commands
@subsection signal_states
@findex signal_states
@cindex States, Signals
@config{signal_states}	@var{signal_pattern} = @{@var{State}, @var{State}...@};

Allows the value of a bus to be translated to a text string.  The
@var{signal_pattern} is the name of the signal inside the trace, with
@kbd{*} being a wild card that matches any number of characters.  Each
state is the text to be displayed, using the characters
@kbd{0-9A-Z%._/}.  States are assigned in numerical order starting with
zero, unless a @code{##=} proceeds a state name: If a state name is of the
form @code{##=name}, for example in @code{7=Read} the Read name is
assigned to the bus value seven.  (The number is always in decimal.)
The next assignment will be to 8 if no number is specified.

Example:

@example
signal_states *cpucreq[2:0] = @{
   1=Barrier, Fetch, FetchM, Read, Write, LDx_L, STx_C@};
@end example

In this example, any signal ending in @samp{cpucreq[2:0]} (any case)
will convert 1 to Barrier, 2 to Fetch, etc.  Unspecified values, such as
0 and 8 will be displayed as a number.  If the state does not fit on the
screen, the number will be printed instead.  Text strings may only be
defined for state numbers 0-255.

@c ======================================================================
@node X Resources, Remote Control, Customization Files, Top
@chapter X Resources

This chapter describes the X-Windows resources that Dinotrace supports.

Dinotrace uses the X resource database for color and font selection.

To use a resource, put in your ~/.Xdefaults file
@example
Dinotrace*Foreground: Black
Dinotrace*Background: #cacaaaaa9191
Dinotrace*color1: DarkOliveGreen
@end example

Then type at the shell @samp{xrdb ~/.Xdefaults} to reread the database.

Dinotrace adds the following resources over and above the core X Toolkit
resource names and classes (such as foreground and background):

@c @table @resource
@table @code
@cindex Color, Searching
@item color@var{#}
@findex color#

@resource{color#}, where @var{#} is 1-9, specifies the colors for
searches, highlighting, and cursors.  color0 is fixed to the foreground
color.

@item barcolor
@findex barcolor
@cindex Color, Bars

@resource{barcolor} specifies the color to be used for the background of
alternate signals.  Defaults to 7% greener than the background color.
Those that remember green bar tractor-feed paper should feel comfortable
with this default.

@item signalfont
@findex signalfont

@resource{signalfont} specifies the font to be used for signal names
along the sides of the trace window.  Defaults to
@code{-*-Fixed-Medium-R-Normal--*-120-*-*-*-*-*-1}

@item timefont
@findex timefont
@cindex Font, Time

@resource{timefont} specifies the font to be used for time values along
the top of the trace window.  Defaults to
@code{-*-Courier-Medium-R-Normal--*-120-*-*-*-*-*-1}

@item valuefont
@findex valuefont
@cindex Font, Value

@resource{valuefont} specifies the font to be used for values inside
buses.  Defaults to @code{-*-Fixed-Medium-R-Normal--*-100-*-*-*-*-*-1}

@end table

@c ======================================================================
@node Remote Control, Dinotrace and Emacs, X Resources, Top
@chapter Remote Control
@cindex Signals, SIGUSR

Dinotrace can be triggered to reread traces by sending a USR1 signal
to it.  This allows build environments to automatically refresh dinotrace
when a new waves file is available.  See the kill manpage for details on
sending a signal, usually it's @code{kill -USR1 %?dino}.

After annotation, Emacs creates a socket that can be used to send commands
into it.  See the Emacs chapter and internal code for details.

@c ======================================================================
@node Dinotrace and Emacs, File Formats, Remote Control, Top
@chapter Dinotrace and Emacs
@cindex Emacs, Annotation

This chapter describes the interaction between Dinotrace and Emacs.

Dinotrace provides the means for back-annotating highlighting and values
into Emacs buffers, and from Emacs, highlighting signals, values, and
the like.  This is what separates Dinotrace from the rest.

@menu
* Installation::                
* Annotation::                  
* Signal Matching::             
* Entering Dinotrace-Mode::     
* Exiting Dinotrace Mode::      
* Configuring Dinotrace-Mode::  
* Keys in Dinotrace Mode::      
@end menu

@node Installation, Annotation, Dinotrace and Emacs, Dinotrace and Emacs
@section Installation
@cindex verilog-mode.el

The appropriate Emacs code should have been installed along with the
rest of Dinotrace.  If you encounter problems, you should return to this
section.

You'll probably also need @file{verilog-mode.el} from
@uref{https://www.veripool.org/verilog-mode}.  Make sure that file,
and the distribution's files @file{lisp/dinotrace.el} and
@file{lisp/sim-mode.el} are installed in your Emacs @code{site-lisp}
directory. (In Emacs @kbd{C-h v load-path @key{RET}} should list the
name of that directory.)  Check that in your @file{.emacs} file, or
better yet, the site's @file{site-start.el} file there are the lines:

@example
(autoload 'sim-log-mode "sim-log" "Mode for Simulation Log files." t)
(setq auto-mode-alist (append (list '("\\.log$" . sim-log-mode)) auto-mode-alist))
(autoload 'dinotrace-update "dinotrace" "Update dinotrace annotations in this buffer" t)
(autoload 'dinotrace-mode   "dinotrace" "Toggle dinotrace annotations in this buffer" t)
(global-set-key "\C-x\C-aa" 'dinotrace-update)
(global-set-key "\C-x\C-ad" 'dinotrace-mode)
@end example

@node Annotation, Signal Matching, Installation, Dinotrace and Emacs
@section Annotation

With a trace up in Dinotrace, select the @dmenu{Value Annotate...} menu
item.  This will create a magic file in your home directory.

In Emacs, visit a Verilog or C file which has some signals that are in
the trace.  Press @kbd{C-x C-a a}.  Emacs will read the annotation file
and add highlighting to your buffer.  A new menu will appear on the
screen, and the mode line will indicate @samp{Dinotrace}.

In a simulation log file (ending in @file{.log}), Pressing @kbd{C-x C-a
a} will likewise add annotations of where cursors exist.

@node Signal Matching, Entering Dinotrace-Mode, Annotation, Dinotrace and Emacs
@section Signal Matching

Emacs chooses what to highlight based upon only the base part of the
signal name; all hierarchy and bus descriptors are stripped.  If multiple
signals exist with the same basename, all signals other than those with
the desired hierarchy should be deleted so they won't participate in the
annotation.

@node Entering Dinotrace-Mode, Exiting Dinotrace Mode, Signal Matching, Dinotrace and Emacs
@section Entering Dinotrace-Mode

There are two keys used to enter Dinotrace Mode:

@table @kbd
@item C-x C-a a
@itemx M-x dinotrace-update
@kindex C-x C-a a

@kbd{C-x C-a a} will enter dinotrace-mode in this buffer.
If there is a new annotation file, read it, update all annotations in all
visible widows, and remove outdated annotations from invisible buffers.

@item C-x C-a d
@itemx M-x dinotrace-mode
@kindex C-x C-a d

@kbd{C-x C-a d} will toggle Dinotrace Mode in this buffer.
With arg, turn Dinotrace mode on if and only if arg is positive.

It will not read a new annotation file if one has already been read in.

@end table

@node Exiting Dinotrace Mode, Configuring Dinotrace-Mode, Entering Dinotrace-Mode, Dinotrace and Emacs
@section Exiting Dinotrace Mode

There are two ways to exit Dinotrace Mode:

@table @kbd
@item C-x C-a d
@itemx M-x dinotrace-mode
@kindex C-x C-a d

@kbd{C-x C-a d} will toggle Dinotrace Mode in this buffer.  With zero or
negative arg, turn off Dinotrace mode.

@item C-x C-q
@itemx M-x dinotrace-toggle-read-only
@kindex C-x C-q

@kbd{C-x C-q} will toggle read-only status.  Dinotrace traps this key
and will remove annotations and make the buffer writable.

@end table

@node Configuring Dinotrace-Mode, Keys in Dinotrace Mode, Exiting Dinotrace Mode, Dinotrace and Emacs
@section Configuring Dinotrace-Mode

These keys configure Dinotrace Mode:

@table @kbd
@item C-x C-a a
@itemx M-x dinotrace-hierarchy-set
@kindex C-x C-a a

@kbd{C-x C-a a} will specify the hierarchy as a regular expression.  Any
signals must match this regular expression in order to be annotated.
This is useful if the same signal name appears in many modules with
different values; you can thus choose which modules the signals will
come from.

@end table

@node Keys in Dinotrace Mode,  , Configuring Dinotrace-Mode, Dinotrace and Emacs
@section Keys in Dinotrace Mode

When inside a Dinotrace Mode buffer, many keys are defined to affect
both Emacs and also Dinotrace.  All begin with @kbd{C-x C-a}, and are
also selectable from the Emacs menubar.  Most match the keyboard
accelerator keys for Dinotrace itself.

@table @kbd
@item C-x C-a c
@itemx M-x dinotrace-goto-and-cursor-time
@kindex C-x C-a c

Take the time that the point is over, and scroll Dinotrace so time is
visible.  Add a cursor using the current color.

@item C-x C-a C
@itemx M-x dinotrace-goto-and-cursor-time-next-color
@kindex C-x C-a C

Take the time that the point is over, and scroll Dinotrace so time is
visible.  Add a cursor using the next color.

@item C-x C-a s
@itemx M-x dinotrace-goto-and-highlight-signal
@kindex C-x C-a s

@kbd{C-x C-a s} will take the signal name the point is over, and scroll
Dinotrace so the signal is visible.  The signal is highlighted using the
current color.

@item C-x C-a S
@itemx M-x dinotrace-goto-and-highlight-signal-next-color
@kindex C-x C-a S

@kbd{C-x C-a S} will take the signal name the point is over, and scroll
Dinotrace so the signal is visible.  The signal is highlighted using the
next color.

@item C-x C-a v
@itemx M-x dinotrace-highlight-value
@kindex C-x C-a v

@kbd{C-x C-a v} will take the value the point is over, and highlight it
using the current color.  With a prefix-arg, cursors will also be put
where the value occurs.

@item C-x C-a V
@itemx M-x dinotrace-highlight-value-next-color
@kindex C-x C-a V

@kbd{C-x C-a S} will take the value the point is over, and highlight it
using the next color.  With a prefix-arg, cursors will also be put where
the value occurs.

@item C-x C-a >
@itemx M-x dinotrace-cursor-step-forward
@kindex C-x C-a >

@kbd{C-x C-a >} will move all cursors forward one grid #0 period and
reannotate the buffer.  If the grid is set correctly, this will change
the values to represent one clock period later.

@item C-x C-a <
@itemx M-x dinotrace-cursor-step-backward
@kindex C-x C-a <

@kbd{C-x C-a <} will move all cursors back one grid #0 period and
reannotate the buffer.  If the grid is set correctly, this will change
the values to represent one clock period earlier.

@end table

@c ======================================================================
@node File Formats, Bugs, Dinotrace and Emacs, Top
@chapter File Formats

This chapter describes the file formats supported by Dinotrace, and how
to produce them with various simulators.

If you're making a quick trace that is small, the ASCII format is
probably quickest and dirtiest.  If you're making a real 4-state
simulator, Tempest XOR format is very compact and fast.  A example
reader for this format is included with the Dinotrace distribution.

@c ----------------------------------------------------------------------
@menu
* Verilog Value Change Dumps::  
* Verilog Value Plus Dumps::    
* ASCII Traces::                
* Tempest Traces::              
* Making Verilator Traces::     
* Making Cosmos Traces::        
* Tempest Trace Format::        
* Tempest XOR Traces::          
* Making Verilator XOR Traces::  
* Tempest XOR Format::          
* Decsim Binary::               
@end menu

@node Verilog Value Change Dumps, Verilog Value Plus Dumps, File Formats, File Formats
@section Verilog Value Change Dumps

Dinotrace can read the Value Change Dump format, common with
simulators such as Verilog-XL, VCS, and many others.

VCD files have a @file{.vcd} extension.  Under the @dmenu{Trace Read}
menu, select Verilog Format.  Select @dmenu{Trace Read} to read the file.
If this is your standard format, you can set it permanently by placing
in the @file{$DINODISK:dinotrace.dino} file:

@example
file_format verilog
vector_separator "["
@end example

VCD files can contain a great number of signals, potentially every net
in the design.  To cut down on the clutter, Dinotrace removes any signal
that is identical to a signal higher up in the design hierarchy.  For
example, if the signal @samp{top.cpu.cache.index_addr[7:0]} is the same
net as @samp{top.cpu.addr[27:20]}, then only the latter will be shown in
Dinotrace.  This can be disabled with @config{save_duplicates}.

To save disk space you may wish to store files as gziped.  This will
result in about a 10 times space savings, and Dinotrace will uncompress
them automatically.  (By detecting the @file{.gz} extension and piping
through gunzip.  Gunzip must exist in your @code{$PATH} for this to
work.)

@menu
* Making VCDs in Verilog::      
* VCD File Format::             
@end menu

@node Making VCDs in Verilog, VCD File Format, Verilog Value Change Dumps, Verilog Value Change Dumps
@subsection Making VCDs in Verilog
@cindex Verilog-XL, Making Traces
@cindex VCS, Making Traces

To create a value change dump file inside of Verilog, add the code
somewhere in a module:

@example
// Create a dump file
initial begin
        $dumpfile ("|gzip --fast --stdout >trace_top.vcd.gz");
        $dumpvars (12, top);
end
@end example

Where top is the name of the module to be traced, trace_top.vcd.gz is the
output file, and 12 is the number of levels of hierarchy underneath top
to be traced.  Dinotrace expects the @file{.vcd} extension.  This
command will dump all signals in the module top.  For more information
on dump files, see @cite{Chapter 18 of the Verilog-XL reference manual}.

@node VCD File Format,  , Making VCDs in Verilog, Verilog Value Change Dumps
@subsection VCD File Format

For a description of the VCD file format, see @cite{Chapter 18 of the
Verilog-XL reference manual}.

@c ----------------------------------------------------------------------
@node Verilog Value Plus Dumps, ASCII Traces, Verilog Value Change Dumps, File Formats
@section Verilog Value Plus Dumps

Dinotrace can read the Value Plus Dump format, common with VCS.

VPD files have a @file{.vpd} extension.  Under the @dmenu{Trace Read}
menu, select Verilog VPD Format.  Select @dmenu{Trace Read} to read the file.
If this is your standard format, you can set it permanently by placing
in the @file{$DINODISK:dinotrace.dino} file:

@example
file_format vpd
vector_separator "["
@end example

For this to work, you must have the @prog{vpd2vcd} program installed in
your search path.  It was distributed with VCS, and requires a key to
operate; contact your simulation vendor for details.

Dinotrace will convert the format to a standard VCD file using a pipe.
Thus all of the notes above for the @ref{Verilog Value Change Dumps}
also apply to this format.

@menu
* Making VPDs in Verilog::      
@end menu

@node Making VPDs in Verilog,  , Verilog Value Plus Dumps, Verilog Value Plus Dumps
@subsection Making VPDs in Verilog
@cindex Verilog-XL, Making Traces
@cindex VCS, Making Traces

To create a value plus dump file inside of Verilog, add the code
somewhere in a module:

@example
// Create a vpd file
initial begin
        $vcdpluson (12, top);
end
@end example

Where top is the name of the module to be traced, and 12 is the number
of levels of hierarchy underneath top to be traced.  For this to work
you may also need a @switch{-I} or other compile time option for your
simulator.

@c ----------------------------------------------------------------------
@node ASCII Traces, Tempest Traces, Verilog Value Plus Dumps, File Formats
@section ASCII Traces
@cindex ASCII Traces

The initial format that Dinotrace supported was a Decsim ASCII format.
This format is still very useful for reading traces created by
@prog{perl} scripts and other quick programs.  For large traces, any of
the other formats will make significantly smaller files.

@menu
* Making Decsim ASCII Traces::  
* ASCII Trace Format::          
@end menu

@node Making Decsim ASCII Traces, ASCII Trace Format, ASCII Traces, ASCII Traces
@subsection Making Decsim ASCII Traces
@cindex Decsim, Making Traces

Decsim provides both ASCII and binary formats.  For a Decsim ASCII
trace, type at the command prompt:

@example
set trace/radix=2/vector/header/exact/logname=name
	clock, signal1, signal2, signal3
@end example

For information, see @ref{Making Decsim Binary Traces}.

@node ASCII Trace Format,  , Making Decsim ASCII Traces, ASCII Traces
@subsection ASCII Trace Format
@cindex ASCII Trace Format

The ASCII Trace format is broken into two pieces, the header, and the
data lines.

The header consists of a leading !, followed by signal names that are
read vertically, with each bit in a independent column.  Some character
separates the signal name from the bit number, this exact character
varies depending on the simulator.  The header is actually optional,
Dinotrace will create some pretty boring names if the header is not
present.

Here's a header, with the signal names SIG[2:0] and OUT.  (Read it sideways.)

@example
!     SSS
!     III
!     GGGO
!     ___U
!     210T
@end example

The data follows, with one time per line.  The spaces leading the header
above were added so that the first signal column lines up with the first
value after the time stamp.  Actually, the time stamps are optional, in
which case Dinotrace will assign successive times, starting at 0 and
incrementing by 100 for each data line.

@example
0     xxxx
100   000x
103   0000
200   1100
203   0001
@end example

Dinotrace understands the values @code{0}, @code{1}, the tristate
@code{Z}, and the unknowns @code{?}, @code{X}, and @code{U}.  Case does
not matter.

@c ----------------------------------------------------------------------

@node Tempest Traces, Making Verilator Traces, ASCII Traces, File Formats
@section Tempest Traces

Dinotrace supports Digital's tempest (BT02) format, as produced by CCLI,
COSMOS and other tools.  After creating a trace, start up Dinotrace.
Under the @dmenu{Trace Read} menu section, select @widget{Tempest
Format}.  (To make this the default, read the instructions about
configuration files.)  Select @dmenu{Trace Read} to read the file.

Tempest designs use underscores to indicate bus subscripts.  To have
Dinotrace collapse signals into vectors, create a configuration file
with the lines:

@example
vector_separator "<"
hierarchy_separator ">"
@end example

Some CPU groups use a timestamp that is a integer that increases every
other cycle.  The half cycle is a phase.  Dinotrace can either count
phases, which is the default, or cycles.  Since Dinotrace times are
integers, the trick is to change the time resolution so that fractional
values can be displayed:

@example
time_multiplier 500
time_precision ps
time_rep ns
@end example

To detect traces that start on phase B, the second signal in the trace,
right after the cycle_count, must be "phase", which toggles zero/one
every phase.  If this signal is not present, it is assumed the trace
starts on phase A.  (If incorrect - it starts on phase B and there is no
phase signal, the first phase in the entire trace will seem to be
stretched one cycle.)

To save disk space you may wish to store files as gziped.  This
will result in about a 50 times space savings, and Dinotrace will
uncompress them automatically.

@node Making Verilator Traces, Making Cosmos Traces, Tempest Traces, File Formats
@section Making Verilator Traces
@cindex Verilator, Making Traces

Dinotrace can read in Verilator traces created using CCLI.  Dinotrace
will convert the two signals that Verilator creates for tristate busses
(foo and foo__en) into a single signal with tristates shown normally.

@node Making Cosmos Traces, Tempest Trace Format, Making Verilator Traces, File Formats
@section Making Cosmos Traces
@cindex Cosmos, Making Traces

Dinotrace can read in COSMOS traces created under Merlin.  Dinotrace
will convert the two signals that COSMOS creates for each signal (foo
and foo__cos) into a single signal with unknowns shown normally.

@node Tempest Trace Format, Tempest XOR Traces, Making Cosmos Traces, File Formats
@section Tempest Trace Format
@cindex Tempest Trace Format

The Tempest Trace Format is a relatively simple binary format.  Files
all have a @file{.bt} extension, and are stored by unix @code{write()}s
of arrays of @strong{little-endian} longwords.  (Little is the
endianness as Windows NT and Digital Unix, and opposite that of Suns.)

The first record is at the head of the file, and is the identification
block.

@table @samp
@item char (4 bytes)
@cindex BT02
File signature plus revision (e.g. @samp{BT02}).
@item uint (32 bits)
Number of bytes for the header.
@item uint (32 bits)
Number of signals.
@item uint (32 bits)
Number of simulation rows (Do not rely on this, it is not correct if not known when the header is written)
@item uint (32 bits)
Number of bits per simulation 'row', non-padded.
@item uint (32 bits)
Number of bits per simulation 'row', padded to mod 64.
@end table

Following that is a signal description block for every signal in the design.
The number of such records was read from the above identification block.

@table @samp
@item uint (32 bits)
Flags for signal characteristics:
@table @samp
@item bit 0
Signal is input.           
@item bit 1
Signal is output.                  
@item bit 2
Signal is pseudo-pin.
@item bit 3
Signal contains time-stamp value (not a real signal in design).
@item bit 4
Signal is 3 or 4 state (not 2 state).
@end table
@item uint (32 bits)
Offset in body row (in bits).
@item uint (32 bits)
Width of signal (in bits).
@item uint (32 bits)
Number of chars in signal name.  @var{n} below.
@item char (@var{n} bytes)
Signal name, not null terminated.
@item char padding (8-(@var{n}%(8 bytes))) if @var{n}%8 != 0
Padding characters to insure quadword alignment.
@end table

Finally is binary packed data.  Each simulation row contains the value
of all signals at that time stamp.  The location of each bit was defined
in the signal description blocks above.  For example, storage of 300
signals requires 320 bits per row of simulation data.  This data
continues to EOF.  (The number of simulation rows in the header may not
be correct if it was unknown at the time the header was written.)

For three and four state signals, the four state bit in the flag section
is set for that signal.  Two bits are stored in the file per wire bit,
where 00=0, 01=1, 10=tristate, and 11=unknown.

@c ----------------------------------------------------------------------

@node Tempest XOR Traces, Making Verilator XOR Traces, Tempest Trace Format, File Formats
@section Tempest XOR Traces

Dinotrace and Verilator have colluded to make a derivative of the
Tempest format, called XOR format (format string BX02).  This format is
detected by Dinotrace automatically when tempest format is selected.

Ungziped files are only slightly smaller than as traditional Tempest
files.  Gziping however yields a 90% shrink in file size.  Since the
code to generate the trace is compiled in, the actual simulation time to
create the trace is also greatly reduced, speeding simulations by 30% or
so.

@node Making Verilator XOR Traces, Tempest XOR Format, Tempest XOR Traces, File Formats
@section Making Verilator XOR Traces
@cindex Verilator, Making Traces

Verilator makes Tempest XOR traces using the fast trace @prog{perl}
script (see the @cite{Verilator Manual}).  A list of signals to be
traced must be provided at compile time.

@node Tempest XOR Format, Decsim Binary, Making Verilator XOR Traces, File Formats
@section Tempest XOR Format
@cindex Tempest XOR Format
@cindex BX02

Tempest XOR format is very close to tempest normal format.  The first
difference is that the format characters are BX02 rather than BT02.

The second difference is that the binary data for each time record is a
XOR of the previous row's binary data.  (Starting with all zeros before
the first record.)  Thus if a single signal changes in a given time, the
first longword will have a couple of bits set to indicate the bits that
changed in the time stamp, and a single bit will be set in a later
longword for the bit that changed.

This seemingly trivial change greatly improves compression, as 0's are
now the majority of the file, and compress to near nothing.

Any Tempest XOR format readers and writers should only operate on gziped
files.  Thus the normal file extension is @file{.bt.gz}.

@c ----------------------------------------------------------------------
@node Decsim Binary,  , Tempest XOR Format, File Formats
@section Decsim Binary

The Digital internal Decsim simulator has a proprietary format supported
by Dinotrace built under VMS only.

Decsim designs use <>'s to indicate bus subscripts.  To have Dinotrace
collapse signals into vectors, create a configuration file with the
line: @config{vector_separator "<"}.

@menu
* Making Decsim Binary Traces::  
@end menu

@node Making Decsim Binary Traces,  , Decsim Binary, Decsim Binary
@subsection Making Decsim Binary Traces
@cindex Decsim, Making Binary Traces

Decsim uses the set trace command to create Dinotrace compatible
traces.  Usually a clock should be the first signal as Dinotrace
will automatically align the grid to the first signal in a trace.

At the command prompt, type:

@example
set trace/radix=2/vector/binary/exact/logname=name
	clock, signal1, signal2, signal3
@end example

Our group creates a trace file for each sub chip, and turns that
trace into a macro in a separate file.  This way the same trace may
be called from many tests. For example:

@file{TRACE_subchip.IND}:
@example
macro/command TRACE_subchip [$text] =
set trace/radix=2/vector/binary/exact/logname=$text
	clock,
	signal1,
	signal2
$endmacro
@end example

A test would then call:
@example
@@TRACE_subchip.IND
TRACE_subchip testname_subchip
@end example

The test will create a file testname_subchip.TRA.  We find this naming
convention convenient as it will group all of the traces from one chip
together.  For example, running the test @file{ERRORS} with the trace
files @file{TRACE_SSM.IND} and @file{TRACE_CSR.IND} creates the trace
files @file{ERRORS_SSM.TRA} and @file{ERRORS_CSR.TRA}.

@c ======================================================================

@node Bugs, Index, File Formats, Top
@chapter Bugs
@cindex Bugs

This chapter describes bug reporting and the known bugs in the current
version.

Please report bugs to @email{wsnyder@@wsnyder.org}

The following bugs are known to exist:

@itemize @bullet
@item
@pindex lessTIF
When using @prog{lessTIF}, the lines indicating highlighted signals and
cursors that appear in the scroll bars may not always appear.  To
make them reappear, simply press the refresh widget.

@item
@pindex Motif
The Ultrix version of Dinotrace requires @prog{Motif V1.1.3}.  It will run
under older versions, however toolkit warnings will be printed
which may be ignored and Trace Open will make the window size too
large.

@item
@cindex Decsim, Arrays Bug
Decsim does not correctly create binary traces of arrays.  For
example @code{signal[1:0]<1:0>} will not display the correct data in
Dinotrace because Decsim incorrectly creates the file.  Decsim will
work correctly if the trace is changed to ASCII.

@item
There is a problem with the @prog{X-11} Toolkit that causes strange dots
to appear in the trace window.  This only occurs on some systems.
Please contact me if this occurs on your systems.

@end itemize

@c ======================================================================
@node Index,  , Bugs, Top
@unnumbered Index

This is an alphabetical index of this manual.

@printindex cp

@contents
@bye
@comment
  Local Variables:
  eval:(setq font-lock-keywords `(t
    ("^\\(@c\\|@comment\\)\\>.*"
     (0 font-lock-comment-face))
    ("@\\([a-zA-Z]+\\|[^ 	\n]\\)"
     (1 font-lock-keyword-face))
    ("^\\*\\(.*\\)[	 ]*$"
     (1 font-lock-function-name-face t))
    ("@\\(emph\\|strong\\|b\\|i\\){\\([^}]+\\)"
     (2 font-lock-comment-face))
    ("@\\(file\\|prog\\|kbd\\|key\\|url\\|email\\){\\([^}]+\\)"
     (2 font-lock-string-face))
    ("@\\(samp\\|config\\|dmenu\\|resource\\|switch\\|widget\\|code\\|var\\|math\\){\\([^}]+\\)"
     (2 font-lock-variable-name-face))
    ("@\\(cite\\|xref\\|pxref\\){\\([^}]+\\)"
     (2 font-lock-reference-face))
    ("@\\(end\\|itemx?\\) +\\(.+\\)"
     (2 font-lock-function-name-face keep))))
  End:
@end comment