src/mem/slicc/README

Overview
========
This is SLICC, a domain specific language to specify cache coherence protocol
we have developed in Multifacet group.

It is developed by Milo Martin <milo@cs.wisc.edu>
This document is prepared by Min Xu <mxu@cae.wisc.edu> while I am learning the
system.  With minor correctness updates by Brad Beckmann <beckmann@cs.wisc.edu>

It can be used to generate C++ code that works with RUBY cache simulator as
well as generate HTML and other document to describe the target protocol.

Some user document is available in doc directory.

Tech details
============
SLICC take a text input with similar syntax to C++ language and use the lexer
and parser in parser directory to construct a Abstract Syntax Tree (AST)
internally. After having done this first pass, the AST is traversed to fill
several interval table, such as symbol table, type table, etc. Finally the code
is generated by traversing the tree once again.

Note, by Milo's good coding habit, almost all C++ class define their private
copy/assignment constructor. This prevents accidentally copying/assigning an
object by its address.

The AST basically looks like a hierarchical representation of the text input.
At the highest level, it has the "Machine", each Machine has several "states"
and "events" and "actions" and "transistions".

Since the language is domain specific, many assumptions of the target system is
hardcoded in SLICC. For example, ruby would expect the generated code for each
system node, has the following components:
  processor(sequencer, not generated?)
  cache
  directory (with memory block value, only when compiled with tester)
  network interface (NI)

Directory generator/ contains routines to generate HTML/MIF format output.
fileio.[Ch] has a routine to conditionally write a file only when the original
content of the file is different from what is going to be written, this avoid
re-make those file after regenerate the protocol.  html_gen.[Ch] contains the
symbol name munge and index page generation. mif_gen.[Ch] contains the entire
MIF output generation routine, mainly a table buildup.

Directory symbol/ contains classes to represent symbols in the slicc input
file. Base class is "Symbol". Derived subclasses are "Action Event Func State
StateMachine Transition Type Var". "Symbol" has knowledge about its locations
in the source file and short name, long name. "SymbolTable" is a list of
symbols and g_sym_table is the global SymbolTable of the slicc system.
One can query a SymbolTable by symbol's id. Also SymbolTable is responsible for
keeping track of Symbol's declaration in correct scope. The current
implementation uses a stack which dynamically determine the scope of symbol
lookups. Global scope is at bottom of the stack (vector[0]). SymbolTable is
also the main place to write out the generated C++/HTML/MIF files.
SymbolTable::writeNodeFiles() is one of the place to look for hardcoded C++
code for node.[Ch]. And Type.[Ch] is the place where generating enumeration and
Message/NetworkMessage declaration and implementation. Func.[Ch] is used to
generate function of the class Chip. StateMachine.[Ch] wrap the whole thing
up by putting States, Actions, Events together. It actually has a two dimension
table like the one represented in the HTML output. Actions are indexed with
the initial state and observed event. After the tabel being built, the
StateMachine class can write out Transitions/Controller/wakeup_logic into C++
outputs. Finally, in symbol directory, Var.[Ch] seem to incomplete?

Demystify all those "predefined" external types, like "Address". Where are
they defined? They are in ../protocol/RubySlicc-*.sm and
../protocol/RubySlicc_interfaces.slicc is include in the slicc invocation
command in ../ruby/Makefile.

Another myth: "trigger" method is hardcoded in ast/InPortDeclAST.C and
ast/FuncCallExprAST.C. The function is similar to inlined function in the
output generated code, so you cannot find any occurance of string "trigger" in
the generated code. "trigger" also increment a counter that is checked every
time a transition is done. In one ruby cycle, only TRANSITIONS_PER_RUBY_CYCLE
number of transitions can be done. ast/FuncCallExprAST.C also contains some
code for function "error" and "assert" and "DEBUG_EXPR", all in the same
manner. Ruby always issues transitions from the first port while there is any.
Stalled transition in Ruby does not consume a sub-cycle. This models the
hardware that probe all port in parallel, pick one transition from the highest
priority queue if the transistion was not stalled by any resources constraint.

Another note: scheduleEvent() call of ruby make sure a consumer is woken up at
specified cycle, and only once per cycle.

Action z_stall, where is it? It is hardcoded in symbols/StateMachine.C. In
function StateMachine::printCSwitch(), z_stall cause the generated code return
TransitionResult_ProtocolStall. Also the HTML output for z_stall has to be
consequently hardcoded. I am not sure that's really a good idea or not. :-)

Question: How comes there is no "for" loop statement in slicc?
Answer: Been there, done that. That is easy to add, first of all. But unbound
loop make slicc eventually un-synthesizable. We want to avoid that. If you want
to loop through a bounded array do something, make the action done in a
external interface in RubySlicc_Util.h. Inside, you just pass the vector as
parameter to the external interface to achieve the same effects.

Another bad thing of using loop statement like for is that we can not determine
how many buffer space to allocate before the transition. With a vector, if it
easy to understand we can always allocate the worst case number of hardware
resources.

Question: Wait! It seems statement check_allocate does nothing!
Answer: No, it does call areNSoltsAvailable() function of the object before any
statement is executed in one action. It does *NOT* generate code in its
original place in the code, instead, it scan the body of the action code and
determine how many slots are needed to allocated before hand. So the
transaction is all done or nothing done. I had tried to make all actions return
boolean values and the false return cause a transition to abort with
ResourceStall. But it is later on deemed to be too flexible in its semantics.
We should never introduce control flow inside the transitions, so that each
transition is either "all" or "nothing". Just that simple. BTW, if you call
check_allocate twice, areNSoltsAvailable(2) is generated, three times generates
areNSoltsAvailable(3), etc.