======================================

Discussion Board

======================================
See this course's Blackboard site Discussion Board.
You may find what you want mentioned there.

======================================

How do I use the testbench, test.jelib:testALLinstr?
How do I run testALLinstr.asm in our verilog simulation?

======================================
You need to read the src/README, the run/README, and the src/Makefile.
You will edit the Makefile, then use "make" to execute a series of
steps that take the assembly source code src/testALLinstr.asm and
produces run/prog.bin. The testbench will read run/prog.bin into
LC3 memory at simulation start-up. The series of steps includes
(1) pre-processing the assembly source code to translate aliases
such as "halt" and "out" (lc3pp.sed and lc3pp.m4), (2) assembling
the source code (lc3as) to a .obj machine code object file,
(3) stripping out the .obj header and translating the .obj machine
code into a .bin file which contains an ASCII representation of
the machine code's 0's and 1's (obj2bin), and finally (4) moving
the resulting file "src/prog.bin" to "run/prog.bin".

The Makefile also contains rules for building the needed tools,
eg., lc3as and obj2bin. The unix program "make" searches the text
file "Makefile" for rules for the targets specified on the
command line. For instance, "make lc3tools" searches for a
target "lc3tools". That target string is followed by a list of
"dependencies", which are other targets that this target depends on.
Following the dependencies are the actions which tell
"make" what to do for that target. For instance, this Makefile rule,

    foo: foo.c
	cc foo.c -o foo

has the target "foo", the dependency "foo.c" and the action
"cc foo.c -o foo". Entering "make foo" on the unix command line
will cause "make" to fork a sub-shell to execute the command
"cc foo.c -o foo" as if you had typed it into the command line
yourself. The program "make" also has the feature that it will
only fire the action if the dependencies have been altered since
the last time the target's actions were fired. There are many
tutorials online for "make", if you need more documentation.

======================================

Mac OS X root and system software installation.

======================================

If you have never done any compiling natively on your Mac, 
to install system software you need to activate the root account.
You may need to do this to install XCode as well. 
The root account is all powerful, which is why it is disabled by 
default since most users are not building system software. 
Avoid using the unix command "su" to switch the current user to
root. It is safer to do "sudo", which does a 
temporary switch to root just for the one command that follows "sudo".
(For example, "sudo rm foo".) You don't want to wander around your machine 
logged in as the root, you might forget and do something really unpleasant 
accidently. Superuser can change things belonging to anybody, included those 
owned by "root". Do "ls -l" to see details of file/directory ownership.

By default, Apple hides the root directory from the user's view and also 
disables the root user. However, when installing something like Verilog 
(which installs in root/usr/local), installation needs root permissions
to write into usr/local/. To install Verilog, enable the root user, see,
    http://support.apple.com/kb/ht1528
then use the command "sudo" aka "su -c" in a terminal window, see,
    http://www.linfo.org/command_index.html
Enter the root's password (which you created when you enabled root), 
and then do the install. For security reasons, disable the root 
user as soon as you are finished installing system software.

======================================

The unix/linux/OS X/cygwin environment.

======================================

Getting to know your way around unix takes a bit of getting used to.
You should read the tutorials in README-unix.html.
Here, I will just give a very brief rundown.

(1) Unix is an operating system: a program that manages your computer.
(2) One thing it manages is running programs.
(3) The essential interface to the OS is a terminal window.
(4) A terminal window is the display portion of a program called a "shell".
(5) The OS starts the shell program running, the shell listens
to the keyboard and displays characters on the screen (via the OS).
(6) The shell (bash, eg.) has a language it understands. Mostly, you
type in the name of another program to run, and it looks for it and asks
the OS to run it. The shell searches for the program by prepending its name
with a file system path, eg., /bin or /usr/local/bin. If it finds the program
there, it begins running it; otherwise, it complains. Here's an example:
    > ls
causes /bin/ls to be executed. You can cd to / and then to bin and look to
see what is there. You can find out what path the shell will use this way:
    > which ls
(7) Each running program is a "process". The parent, bash eg., spawns
a new "child" process that is the execution of another program.
(8) Processes have "environment variables" inherited from their parents.
(9) You can see all the variables of your shell using the "set" command.
(10) Non-environment variables are not inherited.
(11) Programs often query their environment variables. Eg., the bash shell
queries the variable "PATH". You can see the contents of PATH this way,
    > echo $PATH
(12) The PATH environment variable holds a collection of file system paths.
When searching for an executable program, bash prepends each path, and then
checks to see if such a file exists. Eg., if PATH=/bin:/usr/local/bin
then bash will try "/bin/ls" and "/usr/local/bin/ls" when looking for
the executable "ls". Colons separate the path prefixes.
(13) If you install a program in some location in the file system,
your PATH variable might not have the prefix for that path. You need to
add that path to the contents of PATH, eg.,
    > export PATH=/path/to/my/executable:${PATH}
    > echo $PATH
    /path/to/my/executable:/bin:/usr/bin
(14) It is easier to have this done automagically by putting that command
into a file that bash will read, .bashrc or .bash_profile. Use your favorite
text editor to put an "export" line in the .bash_profile in your home directory.
Bash only reads that file when it starts, ie., when you open a terminal
window or login to one. You can force bash to reread the file this way:
    > source .bash_profile
So, if you have changed .bashr_profile, you must use "source" for 
the change to take effect immediately.
(15) Many programs look for information in the environment variables.
Eg., svn looks for "VISUAL" or "EDITOR" to find out what kind of editor
you want to use when creating a log comment when doing "svn ci".
Add something like this to your .bash_profile,
    export VISUAL=vi
    export EDITOR=vi
if you want it to use vi; replace "vi" w/ "emacs" if you want emacs.
(16) Read README-unix.html

======================================

Q. Verilog: declare "reg" gives syntax error?

======================================
Q. After I create a cell/circuit, I am trying to declare wires as reg.
I keep getting a compiling error.

/**/initial begin
/**/reg A;
/**/$finish;
/**/end

I keep getting a malformed statement error.

A. First, you have made a type declaration ("reg") inside of an "initial"
statement. That is not where type declarations go: they go outside
"always" and "initial" statements. Second, even if you had put the 
type declaration in correctly, you cannot declare something as 
both "wire" and "reg". If you look in your verilog code produced 
by Electric, you will see that the wires connecting the gates in 
your design are "wire". The easy way is to declare
"reg Asrc; assign A = Asrc;" and set Asrc as needed in your testbench.

You can also use blackboxes with output ports 
declared "reg". Blackboxes must be in a lower-level cell:
(1) create a cell with a blackbox and an output port declared as 
type "reg", (2) create an icon for that cell/module, drop an
instance into your cell, (4) insert verilog code at the top-level 
to manipulate the outputs of the lower-level cell/module instances.

Finally, one last error: your "initial" statement creates its first 
event at simulation time 0. As there is no delay in your statement, 
the "$finish" creates an event w/ timestamp 0. The simulator will 
execute the $finish action at simulation time 0, ending the simulation.

======================================

Subversion revision check-out, branching

======================================

Q. How to checkout earlier svn revisions, and make a branch.

A. If we only want to play around with it, checking it out temporarily to a 
new working directory is fine, just make sure not to check in changes from 
there and delete that working copy when done. But usually, we want to continue 
developing anew from the older version. That is called "creating a branch in 
the development tree", that is, you want to bud a new branch of changes from 
that version. To do that, you don't want to

 "svn co -r 1234 foo"  (suppose 1234 was the old version)

to a new working directory. That would not create a branch. If you were to 
check in changes from that working copy, WHAT version would result? 
Instead, you want to create your own new branch,

	%> svn copy -r 1234 ./trunk ./branches/newTrunk

That creates a copy of the entire trunk, but only up to revision 1234.
You first need to create "branches". Assuming you are in the top level of a working
copy of your tree, create your own "branches" subdirectory and add it,

	%> mkdir branches
	%> svn add branches
	%> svn copy -r 1234 ./trunk ./branches/newTrunk
	%> svn ci

and send it to the repository. Now you can work on your newTrunk instead. If you
later want to apply the changes you make in newTrunk back into trunk, use svn merge.

======================================

MacPorts, unix tools for OSX.

======================================
MacPorts.org keeps a repository up-to-date versions of many open source tools:

	http://www.macports.org/install.php

Follow directions to install (after, skip down to instructions for using it).
MacPorts is a commandline tool, syntax is,

	%> sudo port install subversion

You need root privileges (see earlier Q.). MacPorts keeps all its stuff in /opt 
so as not to collide with other installed stuff (Xcode, Fink, ...). 
It builds everything (which takes awhile), including building other tools 
needed by the build, so you need Xcode installed (see earlier Q.). 
It also sets your .bash_profile so that your PATH environment variable to 
include /opt/local/bin and /opt/local/sbin; so, you want to check when using 
your commandline, which executables you are actually using (use "which foo", 
for instance): you might be using a MacPort when you thought you were using 
something else, or vice versa. Mostly, this should not be a problem. To find 
available MacPorts packages:

	%> port search iverilog

for instance.

======================================

Verilog compile and path problems

======================================
Q.
I Downloaded verilog source, tried to compile it, it didn't work; 
so, I had to manually go into the files that were giving errors and 
change a couple things like deleting a semicolon and declaring 
variables. Then it compiled fine. I had to install it into a 
different place than it would go by default because it says it 
doesn't have permission to make directories in my computer's 
/usr/local directory, so I changed the path prefix to the verilog 
folder on my desktop, which worked. Then to run iverilog, I didn't 
remember how to change the environment path, so I manually typed the 
source path for verilog to compile the verilog code. When I tried to 
vvp a.out, it gave me an error saying 
	'Unable to find system.vpi module on the search path'
	'Unable to find a v2005_math.vpi module on the search path'
	'Unable to find a va_math.vpi module on the search path'
Do you think this is an issue with the search path or with the 
way I compiled and installed verilog?  I'm working on a Mac by the way,
so I don't know if that affects anything.

A.  Congrats on getting it to compile! Not sure why you got source code that 
was not complete/correct.

When iverilog tries to execute other tools it comes with, it can't find them
because the path environment variable is not set. Cd to your home directory.
Do an "ls -a -l" and you will see some ".*rc" files or 
something like .profile. Depends on which shell you use: sh or bash
then look for .profile or .bashrc; csh or ksh or one of those, look 
for .cshrc or .login. You will no doubt find in there somewhere a line like,

	set PATH=/usr/bin: ... :${PATH}
	export PATH

(that's for sh/bash). Use the same syntax to prepend the path to your iverilog 
executables. Do this in your .profile or .bashrc. (.profile is the more 
logical as it gets read once at login.) That is, add a line like the one 
above to you .profile. By the way, the syntax for csh-like shells is something 
like,

	setenv PATH=???

I've forgotten exactly, but it is easy to look up via google or "man csh".

Not that you need to install your executable to /usr/local, although that's the 
logical place, but if you do want to, you need to see who owns that directory.
It is probably not owned by you! Usually, it's owned by "root". On the mac, you 
need to "sudo" (switch user to root and do) whatever command you want. 
However, you need to know root's login password for that to work. For that 
you have to activate the root account and set a password. I've forgotten how 
you do that, but google it and you'll see it's not hard (also, see above).

======================================

Electric copy/paste removes exports.

======================================
Q. I want to replace the content of an Electric schematic cell with another
cell's content. They both use the exact same exports. I copy/paste, but the
exports are not copied. If I then try to add them, the cell's icon gets messed
up and the cell's connectivity in higher-level cells breaks.

A.
Suppose you decide to implement some of the LC3's cells as structural
models: only basic logic gates and wire/busses are used instead of verilog
behavioral modeling code. For instance, the parts:MUX16_4x1 cell initially
consists of a blackbox with verilog behavioral code, and you want to
implement it using only AND, OR, and NOT gates. Actually, you only
need to implement a lowest-level cell, MUX1_2X1, that way; MUX16_4x1 can
be implemented as a hierarchy of cells built using instances of that cell.

You may try to go about this by deleting the contents of MUX16_4x1{sch} and
copy/paste replacing it with the contents of another cell that implements
the same function. That might be the case if you use a posted homework 
solution, for example. But, Electric's cell exports are not copied in the 
copy/paste operation. If you then try to add exports to correct this,
Electric will notice that the cell's embedded icon already has those
exports and create new ones. This will completely mess up the cell's
connectivity in higher-level cells.

Cells that have export problems are listed in Electric's message
window when you do,

    Tools.Simulation(Verilog).WriteVerilogDeck.

For instance, if MUX16_4x1{sch} is missing exports, Electric's message window
would report,

    parts:MUX16_4x1;1{ic}: Icon port has no equivalent port
    parts:MUX16_4x1;1{ic}: Icon port has no equivalent port
    parts:MUX16_4x1;1{ic}: Icon port has no equivalent port
    parts:MUX16_4x1;1{ic}: Icon port has no equivalent port

The problem is that there are no exports in MUX16_4x1{sch}, except on the
icon, which is an instance of MUX16_4x1{ic} embedded in MUX16_4x1{sch}.
Delete that instance; DO NOT delete the cell MUX16_4x1{ic}. After deleting
the icon from MUX16_4x1{sch}, there will be exports left that were on the
icon instance. Delete all of those exports from MUX16_4x1{sch}, You can now
create the cell's exports as you normally would. Make sure you use the exact
same export names as those appearing in MUX16_4x1{ic}, and that they have
the correct port directions, "input" or "output". Now, check MUX16_4x1{ic}
to make sure the exports match. If they do not match, you will see
additional ports on the icon. If you made that mistake, use
Edit.Undo (ctl-z or Apple-z) to back up and try again. Doing the repair
this way, the icon's instances in the other cells will remain connected
as they were, and the icon's artwork (location of port connectors,
labels, and so forth) will remain intact as well.

======================================

Electric arrays, editing pre-existing cells.
Missing ports, missing connections.
All my wires disappeared!

======================================

Arrays of gates/devices.
If you are editing pre-existing cells,
be careful to not delete the ports when removing the old implementation.
It is easy to create a 16-bit circuit from 1-bit elements using Electric's
Edit.Array command. First, build a 1-bit element; eg., a 1-bit AND, with
short wires attached to inputs and outputs. Name the wires as bus
elements; eg., inA[0], inB[0], and out[0]. Now, select the entire 1-bit
device by dragging a select-frame over it. Then, use Edit.Array, and fill
in the appropriate number of repetitions of the device (16 in this case).
Decide if you want them laid out vertically or horizontally. Recall
that Edit.undo is ctl-z in MS Windows and Apple-z in Mac. The wires will
be automagically numbered Ain[0], Ain[1], and so forth. All that's left
to do is check that the cell's bus ports are still working. If you were
careful not to delete the ports and you used the same naming scheme for
wires/busses used originally, they should be ok. (But, if you have the
same signal going to all instances in your array, as in MUX selects, you
may have to rename them since they will be numbered as if they form a bus.)
If you have to create an entire cell from scratch, remember to set all
port's input/output characteristics appropriately, and do View.MakeIconView.
You can edit the icon view, "{ic}", to move text around and resize it, add
text to inputs and outputs, and move the location of ports. To move ports
you may have to Edit.Rotate them and their attached wire/bus (select the
pin, not the wire/bus for moving, select both for rotation.)

Missing ports and connections.
When you edit or delete cells, either schematic or icon cells,
you may find your connections to its icon in higher-level cells break,
or your (ex)ports disappear or get automagically renamed in the
schematic. Check your connections. In the worst case, you may need to
delete the old icon from the cells in which there are instances (including
in its schematic cell), and put a new icon in and reconnect it. But if you
are only editing an existing schematic, you can delete the icon in the
cell's schematic view without deleting its icon view and create ports that
match the cell's icon view. You can visually check connections three ways:
(1) in a higher-level cell, select the (ex)port crosshairs of your icon,
all connected wire/bus nets will be highlighted, (2) in your schematic cell,
select the (ex)port name, all connected nets will be hightlighted, (3) in
your schematic cell, select the (ex)port crosshairs on the cell's icon,
all connected nets in your schematic cell will be highlighted. Be aware that
wires you draw might not be connected as you think. If you have trouble,
try deleting the wires in the schematic and instead use connection-by-name:
put matching names on wire/bus stubs to make connections rather than drawing
connecting wire/bus. Always add a wire connection to the ports of an
instance icon. Watch Electric's message window, it will warn you of some
problems, such as wire/bus pins not connecting to instance ports or
missing (ex)ports, eg., when you do Tools.Simulation(Verilog).WriteVerilogDeck.

Missing wire/bus nets. It is easy to inadvertently cause all the wires/busses to
suddenly disappear. This is very upsetting. The good news is that you probably
have not deleted them by accident. Keyboard shortcuts may be the problem.
You can make "layers" of your design invisible. See Electric's
Window.Visible.SetAllVisible. Other things besides wires/busses may become
invisible also.