************************************************************************* * * * Myricom LANai3 Simulator Software and Documentation * * * * Copyright (c) 1994, 1995 by Myricom, Inc. * * All rights reserved. * * * * Permission to use, copy, modify, and distribute this software and its * * documentation in source and binary forms for non-commercial purposes * * and without fee is hereby granted, provided that the modified software* * is returned to Myricom, Inc. for redistribution. The above copyright * * notice must appear in all copies and both the copyright notice and * * this permission notice must appear in supporting documentation, and * * any documentation, advertising materials, and other materials related * * to such distribution and use must acknowledge that the software was * * developed by Myricom, Inc. The name of Myricom, Inc. may not be used * * to endorse or promote products derived from this software without * * specific prior written permission. * * * * Myricom, Inc. makes no representations about the suitability of this * * software for any purpose. * * * * THIS FILE IS PROVIDED "AS-IS" WITHOUT WARRANTY OF ANY KIND, WHETHER * * EXPRESSED OR IMPLIED, INCLUDING THE WARRANTY OF MERCHANTABILITY * * OR FITNESS FOR A PARTICULAR PURPOSE. MYRICOM, INC. SHALL HAVE NO * * LIABILITY WITH RESPECT TO THE INFRINGEMENT OF COPYRIGHTS, TRADE * * SECRETS OR ANY PATENTS BY THIS FILE OR ANY PART THEREOF. * * * * In no event will Myricom, Inc. be liable for any lost revenue * * or profits or other special, indirect and consequential damages, even * * if Myricom has been advised of the possibility of such damages. * * * * Other copyrights might apply to parts of this software and are so * * noted when applicable. * * * * Myricom, Inc. Email: info@myri.com * * 325 N. Santa Anita Ave. World Wide Web: http://www.myri.com/ * * Arcadia, CA 91024 * *************************************************************************
`L3sim' is the Tcl/Tk/Expect-based LANai3 simulator. More specifically, `L3sim' is merely the `expectk' shell, to which several commands have been added. This manual only covers the additions to `expectk', so you should refer to the Expect, Tk, and Tcl documentation for any details not covered here.
Currently, `L3sim' only simulates 1MB of memory and the CPU core of
the LANai3. The following memory-mapped registers of the LANai3 are
simulated: IPF0, IPF1, CUR0, CUR1,
PREV0, PREV1, DATA0, DATA1, DPF0,
DPF1. Interrupts are simulated, but the packet and DMA interfaces
are not simulated and never modify the isr register, so
interrupts do not occur unless the debug_bit of the imr
register is set. All instructions are simulated, including the
punt instruction. Although memory contention is supported, the
simulator generates only random bus contention if requested using
"sim_set contention type" (see section sim-set); the packet
and DMA interfaces do not generate memory contention because they
are not simulated (see section Extending the Simulator).
The simulator has been tested extensively against a (much slower) simulation derived directly from the LANai3.1 layout. To our knowledge, the two simulations behave identically except under the following circumstances:
`L3sim' is based on the Tcl/Tk libraries and source files. The University of California holds the copyright for this software. This copyright notice can be found in the file `exp_main_tk.c' in the source distribution. We thank John Ousterhout and UCB for their generous contribution of this software.
`L3sim' is also based on on the Expect package by Don Libes at the National Institute of Standards and Technology. The Expect software has been placed in the public domain. We thank Don and the NIST for their generous contribution of this software.
In addition to the Tcl/Tk commands, which are described in Tcl and the Tk Toolkit by John K. Ousterhout, `L3sim' implements the following commands:
sim_cat_mem
sim_cat_mem returns the output of
`/usr/bin/od -Xw4 file 0x0' where file is a temporary
binary file in which the contents of the simulated memory has been dumped.
sim_clocking [1|single|2|double]
sim_do_cycle
sim_do_cycle simulates a single clock cycle of the LANai3.
If the simulation is in single-clocked mode, this corresponds to two
memory accesses times. If the simulation is in double-clocked mode, this
corresponds to a single memory access time.
sim_get_mem [ start [ end ] ]
sim_get_mem first rounds start and end down
to a multiple of 4. Then it returns a space-separated list
of the word values at memory locations start to end. Each
value is printed using the format `0x%08X'.
If neither start nor end is given, the entire contents of
memory is returned. If only start is given, only the value
at start rounded down to a multiple 4 is printed.
sim_get_reg [ -absolute ] [ reg ... ]
sim_get_reg displays the contents of the processor registers.
If the -absolute option is specified, then the registers are
displayed from the point-of-view of the system context. If this
option is not specified, then the registers are displayed as seen
by the current context.
If no reg is specified, sim_get_reg returns a
space-separated list of the contents of registers 0 to 31. If one or
more regs are specified, then the specified registers are listed.
reg may be one of `apc', `aps', `imr', `isr',
`pc', `ps', or `r0' to `r31'. `pc0',
`pc1', `ps0', and `ps1' may be used to specify the
system-context (0) or user-context (1) values of pc and ps
with or without the -absolute option. Case is ignored when
examining reg.
All listed registers are printed in hexadecimal (using the `0x%08X'
format).
sim_info [ key ... ]
sim_info is used to print the state of various variables in the
simulator. If no key is specified or key is `all', all
available information is returned in a human-readable format. If one or
more keys is specified, the values corresponding to the keys are
returned in a space-separated list. The sim_set command can be
used to set any of the variables. The returned values are formatted
based on the returned values type as follows:
uint
uint values are 32 bit values formatted using `0x%08X'.
sint
sint values are in the range 0-A (hex) and are formatted using
`%1X'.
bool
bool values are boolean and printed as `0' (false) or `1'
(true).
mmod
mmod values are memory modes and are printed asrandom_seed, too_fast_for_CRP_insns, and context
keys are likely to be of interest outside Myricom.
ADDR
after_punt
commit
contention
clocking
curr_insn[0]
CUR0
curr_insn[1]
CUR1
data[0]
DATA0
data[1]
DATA1
dest
ext_enable_
enum arb_state {
ARB_IDLE = 0,ARB_RQST,ARB_GRANT,ARB_DONE
};
The memory operation occurs during the memory cycle following a grant.
fetched_data[0]
DPF0
fetched_data[1]
DPF1
fetched_insn[0]
IPF0
fetched_insn[1]
IPF1
insn_rqst
ext_enable_, but for CPU instruction fetch requests.
load_rqst
ext_enable_, but for CPU memory load requests.
mode
next_context
period
period distinguishes between
the accesses in a pair. For example, Ebus memory accesses only occur
in period 0.
prev_commit
prev_context
prev_ext_enable_
ext_enable_ signal.
prev_insn[0]
PREV0
prev_insn[1]
PREV1
prev_recv_rqst
recv_rqst signal.
prev_send_rqst
send_rqst signal.
random_seed
recv_rqst
ext_enable_, but for packet interface receive requests.
send_rqst
ext_enable_, but for packet interface send requests.
sequence
stor_rqst
ext_enable_, but for CPU memory load requests.
store_value
too_fast_for_CRP_insns
load and put instructions
that modify pc will cause pc to be set to a random value.
This variable defaults to 0.
sim_load_mem file
sim_load_mem loads the .dat or .dat3 file file
into the memory of the simulator. An appropriate .dat file
can be generated using the `gendat' program, which is available
separately from Myricom.
sim_randomize_state
sim_randomize_state writes random values into all registers and
all memory locations. Using this command before sim_load_mem
can make bugs in programs more apparent.
sim_reset
sim_reset simulates a hardware reset.
sim_run
sim_run repeatedly performs sim_do_cycle until the
user-defined global Tcl function should_break returns a non-zero
value. The function should_break must be define by the
user. This command is not available in L3simpler.
sim_set key value
sim_set sets the simulator variable indicated by key
to value. The keys are the same as for the sim_info
command (see section sim-info).
value must be a number.
sim_set_mem address value [ value ... ]
sim_set_mem sets the words in memory starting at address
(rounded down to a multiple of four) to the specified values.
sim_set_reg [ -absolute ] reg value [ reg value ... ]
sim_set_reg sets the specified registers to the specified
values. If the -absolute option is specified, the named
system registers are set; otherwise, the current context's registers are
set. The registers must be specified as in the sim_get_reg
command. The specified values must be integers.
The file `examples/init.tcl' included with the source distribution
is a simple example of how the simulator can be extended using the
builtin Tcl/Tk interpreter. To use the file, start the simulator and
execute the command `source examples/init.tcl'. A window will
appear showing the contents of the registers in the simulator and
displaying buttons to perform simple tasks. Because initially the
contents of memory are random, you should use the load_mem
command to load a program and then the reset command to reset the
simulator before using any other commands.
`examples/init.tcl' implements the following commands:
get_mem
get_reg
load_mem
reset
set_mem
set_reg
step
run
sim_do_cycle until should_break
returns a nonzero value. This commands takes no argument. Note that
while the simulation is running, you can execute commands
on the command-line (e.g.: stop).
should_break
should_break is called, the display is updated.
stop
While `L3sim' is currently built with the Tk and Expect packages,
it would not be difficult to eliminate these dependencies and create
a version of `L3sim' that requires only the Tcl package. The
Tk package is only used for the very primitive GUI and to allow
the sim_run command to run in the background, the Expect package
adds some features to the simulator that are not used by the
simulator, but facilitated some automated testing at Myricom.
If you wish to extend the simulator to simulate other parts of the LANai3, such as DMA or the packet interface, you will probably want to modify the following:
simulate_other_requests()
do_memory_arbitration()
simulate_other_requests().
do_granted_access()
get_mem(), set_mem_preshifted(), or
increment DMA counters).
set_mem_preshifted()
get_mem()
switch statement in each of these functions
to handle any memory-mapped registers in your hardware.